Create a call

Create a new outbound call via the REST API

Endpoint

POST https://api.graine.cloud/v1/Accounts/{AccountSid}/Calls
Content-Type: application/json

Reference: REST Call Control — Create Call

Path parameters

Parameter	Type	Required	Description
AccountSid	string	Yes	Account SID

Headers

Header	Required	Description
Authorization	Yes	Bearer token

Request body

Property	Type	Required	Description
from	string	Yes	The calling party number
to	object	Yes	Destination for the call (see Target schema)
application_sid	string	No	The application to use to control this call. Either application_sid or call_hook is required.
call_hook	Webhook	No	Inline webhook config. Either application_sid or call_hook is required.
call_status_hook	Webhook	No	Webhook for call status events
answerOnBridge	boolean	No	If true, inbound leg rings until dialed number answers, then 200 OK is sent. If false, inbound is answered immediately.
timeout	integer	No	Seconds to wait for answer. Default: 60.
timeLimit	integer	No	Max length of call in seconds
tag	object	No	Initial customer-supplied metadata (see Graine ‘tag’ verb)
headers	object	No	Customer SIP headers to associate with the call
fromHost	string	No	Hostname for the SIP From header of the INVITE
sipRequestWithinDialogHook	string	No	SIP in-dialog hook for session messages
speech_synthesis_vendor	string	No	TTS vendor (required if application_sid not used)
speech_synthesis_language	string	No	TTS language (required if application_sid not used)
speech_synthesis_voice	string	No	TTS voice (required if application_sid not used)
speech_recognizer_vendor	string	No	STT vendor (required if application_sid not used)
speech_recognizer_language	string	No	STT language (required if application_sid not used)
amd	object	No	Answering machine detection config

Target (to) schema

Property	Type	Required	Description
type	string	Yes	One of: phone, sip, user, teams
number	string	No	Phone number (when type is phone)
sipUri	string	No	SIP URI (when type is sip)
name	string	No	Registered Graine user name (when type is user)
trunk	string	No	Carrier name for delivery (when type is phone)
auth	object	No	username, password for SIP auth when challenged
proxy	string	No	SIP Proxy for the outgoing INVITE
tenant	string	No	Microsoft Teams tenant (when type is teams)
vmail	boolean	No	Dial into Teams user voicemail (when type is teams)
overrideTo	string	No	SIP URI for To header in outbound INVITE

Response

201 — Call successfully created

{
  "sid": "<uuid>"
}

400 — Bad request

Example

import requests

url = "https://api.graine.cloud/v1/Accounts/AccountSid/Calls"

payload = {
    "from": "16175551212",
    "to": {
        "type": "phone",
        "number": "[phone]"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

const url = 'https://api.graine.cloud/v1/Accounts/AccountSid/Calls';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '16175551212',
    to: { type: 'phone', number: '[phone]' }
  })
};

const response = await fetch(url, options);
const data = await response.json();
console.log(data);