POST/v1/calls

Calls

Initiate Call

Starts a real phone call: dials the customer, connects them to the specified assistant, and deducts credits from the authenticated user's account. Provide either assistant_id (uses that assistant's assigned live number) or assigned_number (uses the assistant already assigned to that number) — not both.

Request

Endpoint

POST/v1/calls

Authentication

x-api-keyorAuthorization: Bearer

Body Parameters

Name	Type	Description
`customer_number`required	string \| number	The customer's phone number to call. Must not be empty and must look like a phone number (digits, optionally with a leading +, spaces, hyphens, or parentheses — 4 to 20 characters). Not otherwise reformatted — include the country code for international numbers.
`customer_name`required	string	Customer's name — used for personalization and passed through to the assistant. 1 to 200 characters.
`assistant_id`	ObjectId	Assistant to place the call with, using its assigned live number. Must be a valid id — invalid values are rejected before anything is dialed. Provide this or assigned_number, not both.
`assigned_number`	string \| number	Your Vomyra phone number to call from — its assigned assistant places the call. Same format rules as customer_number. Provide this or assistant_id, not both.
`customer_country_code`	string	Customer's country calling code, digits only with an optional leading + (e.g. "+91", 1 to 4 digits). Optional — improves international-call validation accuracy.
`additional_data`	object	Arbitrary context passed through to the assistant and stored on the call record (e.g. order_id, amount). Counts toward the 1 MB request body limit.

Request Body Example

body.json

{
  "customer_number": "9876543210",
  "customer_name": "John Doe",
  "assigned_number": "9123456780",
  "additional_data": {
    "order_id": "ORD123456",
    "amount": 1000
  }
}

Notes

This places a real call and deducts credits immediately — it is not a demo or simulated call.

Use the returned id with GET /v1/calls/{id} to check status, duration, recording, and transcript once the call ends.

Exactly one of assistant_id or assigned_number is required — sending both, or neither, is rejected with 422 before any call is placed or any credit is spent.

All fields are validated up front (format and required-field checks) — a 422 response means nothing happened yet: no call, no charge. A 402 means validation passed but the account doesn't have enough credit.

Response Example

response.json

{
  "success": true,
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "status": "initiated",
    "assistant_number": "+919123456780",
    "customer_number": "9876543210",
    "provider": "Exotel",
    "additional_data": {
      "order_id": "ORD123456",
      "amount": 1000
    }
  }
}

Status Codes

HTTP	Meaning	Description
201	Created	Resource was created.
400	Bad request	Malformed input, invalid ObjectId, or no updatable fields.
401	Unauthorized	Missing, invalid, inactive, or origin-restricted API key.
402	Payment required	Insufficient credits, or premium call minutes exhausted.
403	Forbidden	The requested operation is not available for this resource or tool type.
404	Not found	Resource was not found inside the authenticated user's scope.
415	Unsupported media type	Content-Type header is missing or is not application/json.
422	Validation error	JSON body failed schema or business validation.
429	Rate limited	Per-IP or per-key request budget was exceeded.

Security Model

User-scoped by default

This endpoint only sees resources owned by the user attached to the API key. If another user's id is supplied, the API responds as if the resource does not exist.

curl -X POST "https://api.vomyra.com/v1/calls" \ -H "x-api-key: <api-key>" \ -H "Content-Type: application/json" \ -d '{ "customer_number": "9876543210", "customer_name": "John Doe", "assigned_number": "9123456780", "additional_data": { "order_id": "ORD123456", "amount": 1000 } }'

Initiate Call

Name

Type

Description

customer_numberrequired

string | number

The customer's phone number to call. Must not be empty and must look like a phone number (digits, optionally with a leading +, spaces, hyphens, or parentheses — 4 to 20 characters). Not otherwise reformatted — include the country code for international numbers.

customer_namerequired

string

Customer's name — used for personalization and passed through to the assistant. 1 to 200 characters.

assistant_id

ObjectId

Assistant to place the call with, using its assigned live number. Must be a valid id — invalid values are rejected before anything is dialed. Provide this or assigned_number, not both.

assigned_number

string | number

Your Vomyra phone number to call from — its assigned assistant places the call. Same format rules as customer_number. Provide this or assistant_id, not both.

customer_country_code

string

Customer's country calling code, digits only with an optional leading + (e.g. "+91", 1 to 4 digits). Optional — improves international-call validation accuracy.

additional_data

object

Arbitrary context passed through to the assistant and stored on the call record (e.g. order_id, amount). Counts toward the 1 MB request body limit.

{ "success": true, "data": { "id": "665f1a2b3c4d5e6f7a8b9c0d", "status": "initiated", "assistant_number": "+919123456780", "customer_number": "9876543210", "provider": "Exotel", "additional_data": { "order_id": "ORD123456", "amount": 1000 } } }

HTTP

Meaning

Description

201

Created

Resource was created.

400

Bad request

Malformed input, invalid ObjectId, or no updatable fields.

401

Unauthorized

Missing, invalid, inactive, or origin-restricted API key.

402

Payment required

Insufficient credits, or premium call minutes exhausted.

403

Forbidden

The requested operation is not available for this resource or tool type.

404

Not found

Resource was not found inside the authenticated user's scope.

415

Unsupported media type

Content-Type header is missing or is not application/json.

422

Validation error

JSON body failed schema or business validation.

429

Rate limited

Per-IP or per-key request budget was exceeded.