CallTone

API Reference

Integrate CallTone into your stack with our RESTful JSON API.

Back to Documentation

Base URL

All API requests are made to the following base URL. HTTPS is required for every request.

https://calltone.ai/api/v1

Authentication

Authenticate by including your API key in the Authorization header as a Bearer token. API keys are prefixed with vxf_ and can be created in Settings → API Keys.

Authorization: Bearer vxf_your_api_key_here

Keep your API key secret. Do not expose it in client-side code or public repositories. If you believe a key has been compromised, revoke it immediately from the dashboard and generate a new one.

Rate Limits

The API enforces a rate limit of 100 requests per minute per API key. When you exceed the limit you will receive a 429 Too Many Requests response. Rate-limit headers are included on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1707500000

Error Format

When an error occurs the API returns a JSON object with an error key containing a machine-readable code and a human-readable message.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked."
  }
}

Common error codes include invalid_api_key, not_found, validation_error, rate_limit_exceeded, and internal_error.

Endpoints

GET /agents

Returns a paginated list of all voice agents in your organization.

curl https://calltone.ai/api/v1/agents \
  -H "Authorization: Bearer vxf_your_api_key"

Response:

{
  "data": [
    {
      "id": "agt_abc123",
      "name": "Sales Outreach",
      "voice": "alloy",
      "model": "gpt-4o",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 4
  }
}

POST /agents

Creates a new voice agent. Returns the created agent object.

curl -X POST https://calltone.ai/api/v1/agents \
  -H "Authorization: Bearer vxf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Setter",
    "systemPrompt": "You are a friendly appointment scheduler for Acme Dental...",
    "voice": "shimmer",
    "model": "gpt-4o",
    "firstMessage": "Hi! This is Acme Dental calling to help you schedule your next visit."
  }'

Response (201 Created):

{
  "data": {
    "id": "agt_def456",
    "name": "Appointment Setter",
    "voice": "shimmer",
    "model": "gpt-4o",
    "status": "active",
    "createdAt": "2026-02-10T14:22:00Z"
  }
}

GET /agents/:id

Returns the full details of a single agent including its system prompt, voice configuration, and capabilities.

curl https://calltone.ai/api/v1/agents/agt_abc123 \
  -H "Authorization: Bearer vxf_your_api_key"

Response:

{
  "data": {
    "id": "agt_abc123",
    "name": "Sales Outreach",
    "systemPrompt": "You are a sales representative for...",
    "voice": "alloy",
    "voiceProvider": "vapi",
    "model": "gpt-4o",
    "firstMessage": "Hi, this is Sarah from Acme Solutions...",
    "appointmentScheduling": true,
    "receptionistMode": false,
    "status": "active",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-02-01T09:15:00Z"
  }
}

GET /calls

Returns a paginated list of calls. Filter by agent, status, direction, or date range using query parameters.

curl "https://calltone.ai/api/v1/calls?agentId=agt_abc123&status=completed&limit=10" \
  -H "Authorization: Bearer vxf_your_api_key"

Response:

{
  "data": [
    {
      "id": "call_xyz789",
      "agentId": "agt_abc123",
      "direction": "outbound",
      "status": "completed",
      "from": "+14155551234",
      "to": "+16505559876",
      "duration": 142,
      "sentiment": "positive",
      "summary": "Prospect agreed to a follow-up demo on Thursday.",
      "createdAt": "2026-02-10T16:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 238
  }
}

POST /calls

Initiates an outbound call. The call will be placed immediately using the specified agent and phone number.

curl -X POST https://calltone.ai/api/v1/calls \
  -H "Authorization: Bearer vxf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_abc123",
    "phoneNumberId": "phn_001",
    "to": "+16505559876"
  }'

Response (201 Created):

{
  "data": {
    "id": "call_new001",
    "agentId": "agt_abc123",
    "direction": "outbound",
    "status": "queued",
    "to": "+16505559876",
    "createdAt": "2026-02-11T09:00:00Z"
  }
}

GET /campaigns

Returns all campaigns in your organization. Includes status, progress, and schedule information.

curl https://calltone.ai/api/v1/campaigns \
  -H "Authorization: Bearer vxf_your_api_key"

Response:

{
  "data": [
    {
      "id": "cmp_winter01",
      "name": "Winter Promo Outreach",
      "agentId": "agt_abc123",
      "status": "running",
      "totalContacts": 500,
      "contactsReached": 312,
      "startDate": "2026-02-01T09:00:00Z",
      "endDate": "2026-02-28T17:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 3
  }
}

POST /campaigns

Creates a new outbound calling campaign. You must specify the agent, phone number, contact list, and calling schedule.

curl -X POST https://calltone.ai/api/v1/campaigns \
  -H "Authorization: Bearer vxf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Sale Blitz",
    "agentId": "agt_abc123",
    "phoneNumberId": "phn_001",
    "contactListId": "lst_spring2026",
    "schedule": {
      "startDate": "2026-03-01",
      "endDate": "2026-03-15",
      "callingHoursStart": "09:00",
      "callingHoursEnd": "17:00",
      "timezone": "America/New_York",
      "maxCallsPerDay": 200
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "cmp_spring01",
    "name": "Spring Sale Blitz",
    "status": "scheduled",
    "totalContacts": 1200,
    "createdAt": "2026-02-11T11:00:00Z"
  }
}

GET /contacts

Returns a paginated list of contacts. Supports filtering by name, phone, email, and tags.

curl "https://calltone.ai/api/v1/contacts?tag=lead&limit=5" \
  -H "Authorization: Bearer vxf_your_api_key"

Response:

{
  "data": [
    {
      "id": "cnt_001",
      "firstName": "Jane",
      "lastName": "Doe",
      "phone": "+16505551234",
      "email": "[email protected]",
      "tags": ["lead", "demo-requested"],
      "createdAt": "2026-01-20T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 5,
    "totalCount": 842
  }
}

POST /contacts

Creates a new contact record. Phone number is required and must be in E.164 format.

curl -X POST https://calltone.ai/api/v1/contacts \
  -H "Authorization: Bearer vxf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+14085559999",
    "email": "[email protected]",
    "company": "Smith & Co",
    "tags": ["prospect"]
  }'

Response (201 Created):

{
  "data": {
    "id": "cnt_new002",
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+14085559999",
    "email": "[email protected]",
    "company": "Smith & Co",
    "tags": ["prospect"],
    "createdAt": "2026-02-11T12:30:00Z"
  }
}

Pagination

All list endpoints return paginated results. Use the page and limit query parameters to navigate through results. The maximum page size is 100. The response includes a pagination object with page, pageSize, and totalCount.

Need Help?

If you run into issues with the API, reach out to us at [email protected] or check the Tutorials page for step-by-step integration guides.