Schedule a new call
POST
/calls/schedule
maxDurationMinutes, and a content safety review. If the goal is ambiguous, the response may be NEEDS_CLARIFICATION with a follow-up question instead of a scheduled call — set force: true to skip clarification.Request
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/calls/schedule' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"phoneNumber": "string",
"goal": "string",
"scheduledAt": "string",
"timezone": "America/Los_Angeles",
"additionalContext": "string",
"maxDurationMinutes": 15,
"doWeNeedToRetry": false,
"voice": "string",
"retryAfterMinutes": 5,
"force": false,
"askForClarification": false,
"includePrivateData": false,
"agentId": "string",
"allowCallTransfer": false,
"callTransferNumber": "string",
"title": "string",
"firstMessage": "string",
"cronSchedule": "string"
}'Response Response Example
201 - Example 1
{
"success": true,
"call": {
"id": "string",
"userId": "string",
"phoneNumber": "string",
"source": "LEGACY_UNKNOWN",
"callFrom": "string",
"goal": "string",
"goalStatus": "UNKNOWN",
"scheduledAt": "2019-08-24T14:15:22.123Z",
"title": "string",
"status": "QUEUED",
"additionalContext": "string",
"minutesUsed": 0,
"transactions": [
{
"minutes": 0,
"type": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"description": "string"
}
],
"voice": "string",
"retryAfterMinutes": 0,
"maxDurationMinutes": 0,
"doWeNeedToRetry": true,
"recordingUrl": "string",
"userRating": true,
"reviewedAt": "2019-08-24T14:15:22.123Z",
"finalSummary": "string",
"shortFinalSummary": "string",
"placeWhereToCall": "string",
"roleplayTranscript": [
{
"from": "ai",
"text": "string",
"metadata": {
"tone": "string",
"emotion": "string",
"language": "string",
"sentiment": "string"
},
"timestamp": 0
}
],
"agent": {
"id": "string",
"name": "string",
"description": "string",
"avatar": "string",
"isPublic": true,
"isActive": true,
"instructions": "string",
"incomingCallInstructions": "string",
"maxIncomingCallDurationMinutes": 0,
"maxOutgoingCallDurationMinutes": 0,
"gatheringInformationOnIncomingCall": true,
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"deletedAt": "2019-08-24T14:15:22.123Z",
"userId": "string",
"tools": [
{
"agentId": "string",
"toolId": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"tool": {
"id": "string",
"name": "string",
"description": "string",
"instruction": "string",
"toolType": "HTTP",
"url": "string",
"method": "GET",
"headers": {
"Authorization": "Bearer token123",
"Content-Type": "application/json"
},
"mcpServerUrl": "string",
"mcpServerHeaders": {},
"mcpServerName": "string",
"mcpToolName": "string",
"codeLanguage": "PYTHON",
"codeSource": "string",
"codeTestCases": {},
"inputSchema": {
"name": "string",
"type": "string",
"description": "string",
"children": [
{
"name": "query",
"type": "string",
"description": "Search query",
"validations": {
"required": true,
"min": 1,
"max": 100
},
"label": "Search Query"
},
{
"name": "category",
"type": "enum",
"description": "Category filter",
"enumValues": [
"news",
"weather",
"sports"
],
"validations": {
"required": false
}
}
],
"enumValues": [
"string"
],
"validations": {
"required": true,
"min": 0,
"max": 0,
"regex": "string",
"custom": "string",
"default": "string"
},
"label": "string",
"calculatedField": {
"dependencies": [
"string"
],
"formula": "string"
}
},
"isActive": true,
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z"
}
}
],
"accessToKnowledge": true,
"knowledgeAccessMode": "NONE",
"knowledgeAccessTags": [
"string"
],
"allowFollowUps": true,
"followUpInstructions": "string",
"includePrivateData": true,
"useBusinessProfile": true,
"useDetachedReceptionistProfile": true,
"receptionistPreferredName": "string",
"receptionistCompanyName": "string",
"receptionistCompanyWebsite": "string",
"receptionistCompanyDescription": "string",
"receptionistCompanyIndustry": "string",
"receptionistAddress": "string",
"receptionistCityName": "string",
"receptionistStateName": "string",
"receptionistZipCode": "string",
"receptionistTimezone": "string",
"voice": "string",
"modelName": {},
"allowCallTransfer": true,
"callTransferNumber": "string",
"transferHours": {
"MONDAY": [
900,
1730
],
"TUESDAY": [
900,
1730
],
"WEDNESDAY": [
900,
1730
],
"THURSDAY": [
900,
1730
],
"FRIDAY": [
900,
1730
]
},
"firstMessage": "string",
"allowOutboundGreetingInterruptions": false,
"enableVoiceExpressions": true,
"closingPhrase": "string",
"delayAcceptSeconds": 0,
"voiceRecognition": "EN",
"temperature": 0,
"dataCollections": [
{
"dataIdentifier": "string",
"description": "string",
"dataType": "STRING",
"id": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"agentId": "string",
"results": [
{
"id": "string",
"dataCollectionId": "string",
"callId": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"dataValue": {
"property1": "string",
"property2": "string"
}
}
]
}
],
"evaluations": [
{
"name": "string",
"prompt": "string",
"id": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"agentId": "string",
"results": [
{
"id": "string",
"callId": "string",
"evaluationId": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"type": "SUCCESS",
"rationale": "string"
}
]
}
],
"welcomingVoiceMailMessageForContacts": "string",
"welcomingVoiceMailMessageForOthers": "string",
"isVoiceMailAgent": false,
"outgoingCallFlow": {
"nodes": [
{}
],
"edges": [
{}
]
},
"incomingCallFlow": {
"nodes": [
{}
],
"edges": [
{}
]
},
"voiceSpeed": 0.5,
"incomingCallTypingSound": true,
"incomingCallBackgroundSound": true,
"outgoingCallBackgroundSound": true,
"outgoingCallTypingSound": true,
"allowIncomingSms": false,
"incomingSmsInstructions": "",
"autoRespondToSms": true,
"smsResponseDelay": 1,
"useSmsIncomingCallFlow": false,
"postCallSmsMessage": "string",
"allowRealtimeSms": false,
"phoneNumbers": [
{
"id": "string",
"createdAt": "2021-01-01T00:00:00Z",
"updatedAt": "2021-01-01T00:00:00Z",
"phoneNumber": "+1234567890",
"country": "US",
"isActive": true,
"agent": {
"id": "string",
"name": "string"
},
"agentId": "123",
"direction": "INCOMING",
"isSharedOutbound": false,
"provider": "TWILIO",
"source": "RENTED",
"readyToRelease": false,
"markedReadyToReleaseAt": "2019-08-24T14:15:22.123Z",
"markToDeleteAt": "2019-08-24T14:15:22.123Z",
"lastBilledAt": "2019-08-24T14:15:22.123Z",
"monthlyCost": "1.15",
"isTestNumber": false
}
],
"emailAddress": {
"address": "string",
"status": "ACTIVE"
},
"requireDataConsent": false,
"dataConsentText": "string",
"enablePostCallActions": false,
"postCallActionInstructions": "string",
"behaviorPreset": "default",
"strictSpamFilter": false,
"valuableCallRule": "string",
"overrideCallerId": "string"
},
"voicemails": [
{
"transcription": "string",
"audioUrl": "string",
"duration": 0,
"createdAt": "2019-08-24T14:15:22.123Z"
}
],
"callTransferNumber": "string",
"isCallTransferred": false,
"allowCallTransfer": false,
"dataCollections": [
{
"id": "string",
"dataCollectionId": "string",
"callId": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"dataValue": {
"property1": "string",
"property2": "string"
}
}
],
"evaluations": [
{
"id": "string",
"callId": "string",
"evaluationId": "string",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"type": "SUCCESS",
"rationale": "string"
}
],
"analysis": {
"sentiment": "positive",
"sentimentScore": 0,
"detectedLanguage": "string",
"detectedLanguageConfidence": 0
},
"followUps": [
{
"id": "string",
"type": "SMS",
"content": "string",
"recipientEmail": "string",
"recipientPhone": "string",
"status": "PENDING",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"triggeredByCallId": "string"
}
],
"tasks": [
{
"id": "string",
"title": "string",
"description": "string",
"status": "TODO",
"createdAt": "2019-08-24T14:15:22.123Z",
"updatedAt": "2019-08-24T14:15:22.123Z",
"dueDate": "2019-08-24T14:15:22.123Z",
"priority": "HIGH",
"leadNotes": "string",
"leadStatus": "string",
"tags": [
"string"
],
"isAiGenerated": true,
"completedAt": "2019-08-24T14:15:22.123Z",
"completedBy": "string"
}
],
"taskResults": [
{
"id": "string",
"slug": "string",
"title": "string",
"groupName": "string",
"status": "completed",
"reason": "string",
"createdAt": "2019-08-24T14:15:22.123Z"
}
],
"voiceSpeed": 0,
"callTypingSound": true,
"callBackgroundSound": true,
"recommendedNextAction": "string",
"testCall": false,
"isFavorite": false,
"callInterceptedByUser": false,
"shareHash": "string",
"matchedFields": [
"phone",
"summary",
"title",
"goal"
],
"notes": "string",
"contactId": "123e4567-e89b-12d3-a456-426614174000"
}
}Modified at 2026-07-23 18:02:16