Trigger an outbound call

curl --request POST \
  --url https://app.revve.ai/api/voice-agents/{agentId}/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "+84775352590",
  "fullName": "Jane Doe",
  "email": "[email protected]",
  "companyName": "<string>",
  "companyWebsite": "<string>",
  "timezone": "Asia/Ho_Chi_Minh",
  "fromPhoneNumber": "<string>",
  "numberPoolId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phoneNumber: '+84775352590',
    fullName: 'Jane Doe',
    email: '[email protected]',
    companyName: '<string>',
    companyWebsite: '<string>',
    timezone: 'Asia/Ho_Chi_Minh',
    fromPhoneNumber: '<string>',
    numberPoolId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://app.revve.ai/api/voice-agents/{agentId}/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.revve.ai/api/voice-agents/{agentId}/calls"

payload = {
    "phoneNumber": "+84775352590",
    "fullName": "Jane Doe",
    "email": "[email protected]",
    "companyName": "<string>",
    "companyWebsite": "<string>",
    "timezone": "Asia/Ho_Chi_Minh",
    "fromPhoneNumber": "<string>",
    "numberPoolId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "callRequestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rescheduled": true,
  "runsAt": "2023-11-07T05:31:56Z"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "success": false,
  "message": "Agent not found",
  "reason": "<string>"
}

API Reference

Trigger an outbound call

Places (or schedules) an outbound call from a voice agent to a phone number. The contact is created or updated from the identifying fields before dialing, so the agent’s {{contact}} placeholders resolve. Any additional body fields beyond the ones listed become dynamic variables available to the agent’s prompt templates.

A call requested outside the agent’s allowed calling hours is scheduled for the next allowed slot and returns rescheduled: true with runsAt (this scheduling happens before the guardrail checks below, which then apply when the scheduled call fires).

Guardrails: team call limits and plan limits (429); the outbound whitelist when enabled (400); numbers on the Do Not Call list are not dialed; a number with a call already processed in the last 12 hours is not re-dialed (both of the latter surface through the 500 response with an explanatory message).

Caller ID: uses the agent’s configured outbound number or pool. Override per call with fromPhoneNumber (must be an active team number with outbound calling provisioned) or numberPoolId — when both are sent, the pool wins.

POST

api

voice-agents

{agentId}

calls

Trigger an outbound call

curl --request POST \
  --url https://app.revve.ai/api/voice-agents/{agentId}/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "+84775352590",
  "fullName": "Jane Doe",
  "email": "[email protected]",
  "companyName": "<string>",
  "companyWebsite": "<string>",
  "timezone": "Asia/Ho_Chi_Minh",
  "fromPhoneNumber": "<string>",
  "numberPoolId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phoneNumber: '+84775352590',
    fullName: 'Jane Doe',
    email: '[email protected]',
    companyName: '<string>',
    companyWebsite: '<string>',
    timezone: 'Asia/Ho_Chi_Minh',
    fromPhoneNumber: '<string>',
    numberPoolId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://app.revve.ai/api/voice-agents/{agentId}/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.revve.ai/api/voice-agents/{agentId}/calls"

payload = {
    "phoneNumber": "+84775352590",
    "fullName": "Jane Doe",
    "email": "[email protected]",
    "companyName": "<string>",
    "companyWebsite": "<string>",
    "timezone": "Asia/Ho_Chi_Minh",
    "fromPhoneNumber": "<string>",
    "numberPoolId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "callRequestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "rescheduled": true,
  "runsAt": "2023-11-07T05:31:56Z"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "success": false,
  "message": "Agent not found",
  "reason": "<string>"
}

Authorizations

Authorization

string

header

required

Pass your team's API key as a Bearer token: Authorization: Bearer YOUR_API_KEY. Find your API key in the dashboard under Settings. The key must belong to the same team as the teamId in the request body.

Path Parameters

agentId

string<uuid>

required

The voice agent ID.

Body

application/json

phoneNumber

string

required

The number to call.

Example:

"+84775352590"

fullName

string

Contact full name (alias: name).

Example:

"Jane Doe"

string<email>

companyName

string

companyWebsite

string

timezone

string

IANA timezone for the contact; used for calling-hours evaluation.

Example:

"Asia/Ho_Chi_Minh"

fromPhoneNumber

string

Optional caller-ID override. Must be an active phone number belonging to your team with outbound calling provisioned.

numberPoolId

string<uuid>

Optional number pool to pick the caller ID from. Takes precedence over fromPhoneNumber and the agent's configured pool.

{key}

any

Any extra keys are passed to the agent as dynamic template variables.

Response

Call queued for dialing, or scheduled for the next allowed calling window (rescheduled: true with runsAt).

success

boolean

Example:

true

callRequestId

string<uuid>

rescheduled

boolean

Present and true when the call was scheduled for the next allowed calling window.

runsAt

string<date-time>

When the rescheduled call will run.

Create a contact