Place a voice call
Places an outbound voice call to a single recipient. Accepts a single content source - either a pre-created voice template (template_key or template_alias), which may define a multi-step IVR flow with keypad input and call transfer, or an ad-hoc text-to-speech message (message_content with optional language and voice_gender). Exactly one content source is required.
from must be an approved voice number of the agent and to is the recipient; both must include the country code. If the template defines merge tags, all of them must be supplied in merge_info - a request with missing tags is rejected with the missing tag names listed. Phone numbers should be provided as merge values (for example the agent number of a call-transfer step) and also include country code.
Endpoint
Request URL
https://cpaas.zoho.com/v1.1/voice Copied!
Request Parameters
- Request Headers
API key of an agent. Send the header as Authorization: Zoho-enczapikey {apiKey}. The agent and account are derived from the key.
- Request Body
application/json
Request body for sending a voice call. Exactly one content source is required: template_key/template_alias (a pre-created voice template) or message_content (ad-hoc text-to-speech).
Show Sub-Attributes
Caller id - an approved voice number of the agent, including the country code.
Recipient phone number, including the country code.
Key of a pre-created voice template. Provide this or template_alias (or message_content instead).
Alias of a pre-created voice template. Provide this or template_key (or message_content instead).
Key-value map that resolves the template's {{merge_tags}}. All tags defined by the template are mandatory; if any are missing, the request is rejected and the missing tag names are listed in the error. Phone numbers passed as merge values (for example the agent number of a call-transfer step) must include the country code.
Text-to-speech message spoken to the recipient. Letters, digits, spaces and common punctuation are allowed. Use instead of a template.
Language code used for text-to-speech (e.g. en, hi, fr).
Voice used for text-to-speech.
Key of the sending agent. Optional - defaults to the agent bound to the API token.
Client-supplied reference identifier, echoed in call logs.
Sample Request
curl --request POST \
--url https://cpaas.zoho.com/v1.1/voice \
--header 'Authorization: REPLACE_KEY_VALUE' \
--header 'content-type: application/json' \
--data '{"from":"14155550142","to":"919876543210","template_key":"794dc9c1-b268-11f1-bed6-b6d94062a427","merge_info":{"customer_name":"Paula","company_name":"Example Inc","order_id":"ORD-1001","currency":"INR","amount":"2499"},"client_reference":"order-confirm-1001"}'Sample Request Body
{
"from": "14155550142",
"to": "919876543210",
"template_key": "794dc9c1-b268-11f1-bed6-b6d94062a427",
"merge_info": {
"customer_name": "Paula",
"company_name": "Example Inc",
"order_id": "ORD-1001",
"currency": "INR",
"amount": "2499"
},
"client_reference": "order-confirm-1001"
}
{
"from": "14155550142",
"to": "919876543210",
"template_key": "17af8320-b59c-11f1-8210-8688516064a9",
"merge_info": {
"number": "919845012345"
},
"client_reference": "support-callback-2213"
}
{
"from": "14155550142",
"to": "919876543210",
"message_content": "Hello. Your appointment is confirmed for tomorrow at 10 A M. Goodbye.",
"language": "en",
"voice_gender": "female",
"client_reference": "appt-5501"
}
Response Parameters
- HTTP code 200
Response Body - application/json
Success response returned when the voice call is accepted and initiated.
Show Sub-Attributes
Show Sub-Attributes
Acceptance code.
Unique identifier of the call. Use it with the call-details API.
Unique identifier assigned to the send request.
- HTTP code 400
Response Body - application/json
Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).
Show Sub-Attributes
Show Sub-Attributes
Show Sub-Attributes
A single validation or denial detail inside the error envelope.
Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).
The field the detail refers to, when applicable (e.g. from, to, merge_info).
The offending value, or for VOI_106 the comma-separated list of missing merge tag names.
Identifier of the failed request, when available.
- HTTP code 401
Response Body - application/json
Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).
Show Sub-Attributes
Show Sub-Attributes
Show Sub-Attributes
A single validation or denial detail inside the error envelope.
Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).
The field the detail refers to, when applicable (e.g. from, to, merge_info).
The offending value, or for VOI_106 the comma-separated list of missing merge tag names.
Identifier of the failed request, when available.
- HTTP code 403
Response Body - application/json
Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).
Show Sub-Attributes
Show Sub-Attributes
Show Sub-Attributes
A single validation or denial detail inside the error envelope.
Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).
The field the detail refers to, when applicable (e.g. from, to, merge_info).
The offending value, or for VOI_106 the comma-separated list of missing merge tag names.
Identifier of the failed request, when available.
- HTTP code 422
Response Body - application/json
Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).
Show Sub-Attributes
Show Sub-Attributes
Show Sub-Attributes
A single validation or denial detail inside the error envelope.
Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).
The field the detail refers to, when applicable (e.g. from, to, merge_info).
The offending value, or for VOI_106 the comma-separated list of missing merge tag names.
Identifier of the failed request, when available.
Sample Response: HTTP 200
{
"data": {
"code": "MSG_102",
"message_id": "7ed0c6c0-b670-11f1-8810-3ed350183096",
"message": "Message sent successfully",
"request_id": "2d6f.14350939.v1.7ed0c6c0-b670-11f1-8810-3ed350183096.1a0c8a9dd2c"
},
"status": "success"
}
Sample Response: HTTP 400
{
"error": {
"code": "TM_3301",
"details": [
{
"code": "SERR_110",
"message": "Parameter less than min occurrance",
"target": "to"
}
],
"message": "Bad Syntax"
}
}
Sample Response: HTTP 401
{
"error": {
"code": "TM_4001",
"details": [
{
"code": "SERR_157",
"message": "Invalid API Token found"
}
],
"message": "Access Denied"
}
}
Sample Response: HTTP 403
{
"error": {
"code": "TM_3601",
"details": [
{
"code": "VOI_207",
"target_value": "14155550142",
"message": "The from number is not associated with this mail agent",
"target": "from"
}
],
"message": "Request Denied"
}
}
Sample Response: HTTP 422
{
"error": {
"code": "TM_3501",
"details": [
{
"code": "VOI_106",
"target_value": "customer_name, company_name, order_id, currency, amount",
"message": "Required merge tag(s) missing in the request",
"target": "merge_info"
}
],
"message": "Unprocessable Entity"
}
}
{
"error": {
"code": "TM_3501",
"details": [
{
"code": "VOI_104",
"message": "Caller ID (from) is required",
"target": "from"
}
],
"message": "Unprocessable Entity"
}
}
{
"error": {
"code": "TM_3501",
"details": [
{
"code": "VOI_105",
"message": "Either template key/alias or message content is required"
}
],
"message": "Unprocessable Entity"
}
}
{
"error": {
"code": "TM_3501",
"details": [
{
"code": "MTR_107",
"message": "Template not found"
}
],
"message": "Unprocessable Entity"
}
}
{
"error": {
"code": "TM_3501",
"details": [
{
"code": "VOI_102",
"target_value": "919876500000",
"message": "Invalid phone number",
"target": "from"
}
],
"message": "Unprocessable Entity"
}
}
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.