Plans Features Integrations Languages CompareAPI Docs

Callmatic API Documentation

Customer API for calls, campaigns, account data, reports, and dialing controls. All paths below are relative to the Base URL.

API Setup Guide

Use an apiKey and a campaignId. Create a campaign via POST /campaign or copy an ID from the admin portal.

1. Generate API Key

Sign in at the Callmatic Admin Portal.
Open Profile → Account Section → Generate API Key.
Store the key securely.

Authentication

All API requests must include an API key in the header:

api-key: {{your_api_key}}

Base URL

https://api.callmatic.ai/v1

Response Format

Successful responses use a consistent envelope: { "success": true, "data": { ... } }. Errors use { "success": false, ... } with an HTTP error status.

Calls

Trigger outbound calls, list call history, and fetch call details.

Trigger a Single Call

POST/calls

Initiates one outbound call.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "phoneNumber": "7760524807",
  "variables": {
    "callee_name": "Shivank"
  }
}

Response

{
  "success": true,
  "data": {
    "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
    "phoneNumber": "7760524807",
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
  }
}

Trigger Batch Calls

POST/calls/batch

Initiates multiple calls under one campaign (max 200 per request).

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "to": [
    {
      "phoneNumber": "7760524807",
      "variables": { "callee_name": "Shivank" }
    }
  ]
}

Get Call Details

GET/calls/{callId}

Retrieve status, transcript, and insights for one call.

Headers

api-key: {{your_api_key}}

Sample Request

curl --location 'https://api.callmatic.ai/v1/calls/e08bad66-ee60-458d-958f-a02b1f12d355' \
--header 'api-key: {{your_api_key}}'

List Calls

GET/calls

List calls for your account in a time range (paginated).

Headers

api-key: {{your_api_key}}

Query Parameters

startTime (required) — ISO datetime
endTime (required) — ISO datetime
campaignId (optional) — filter to one campaign
page (optional, default 1)
pageSize (optional, default 20, max 100)

Sample Request

curl --location 'https://api.callmatic.ai/v1/calls?campaignId=a04c3520-c85c-4443-9ffd-7175625e9ecb&startTime=2026-07-01T00:00:00Z&endTime=2026-07-15T23:59:59Z&page=1&pageSize=20' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "calls": [
      {
        "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
        "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
        "direction": "OUTBOUND",
        "status": "completed",
        "phoneNumber": "7760524807",
        "duration": 42,
        "createdAt": "2026-07-10T12:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

Get Call Recording

GET/recordings/{callId}

Fetch the audio recording for a call.

Headers

api-key: {{your_api_key}}

Sample Request

curl --location --globoff 'https://api.callmatic.ai/v1/recordings/{{CallId}}' \
--header 'api-key: {{your_api_key}}'

Campaigns

Create and manage voice agents (campaigns), settings, and post-call actions.

Create Campaign

POST/campaign

Creates a campaign from a language template + prompt using the same CampaignCreator path as the dashboard chat builder.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "language": "en",
  "prompt": "You are a helpful sales agent for home loans.",
  "name": "Home Loan Qualifier"
}

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
  }
}

Update Campaign Prompt

PUT/campaign/{campaignId}

Updates the agent prompt (CampaignCreator edit path) and/or the campaign name. Send at least one of prompt or name.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "prompt": "Make the opening warmer and ask for monthly income earlier.",
  "name": "Home Loan Qualifier"
}

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "campaignName": "Home Loan Qualifier"
  }
}

Update Campaign Settings

PUT/campaign/{campaignId}/settings

Updates campaign name, voice, caller phone, duration, retry, and schedule (chat settings controls). Send only fields you want to change.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "name": "Home Loan Qualifier",
  "voiceId": "112344",
  "callerIdNumber": "+919876543210",
  "maxCallDuration": 300,
  "retry": {
    "active": true,
    "maxCount": 2,
    "delay": 60,
    "retryOnStatus": ["no-answer", "busy"]
  },
  "callSchedule": {
    "enabled": true,
    "slots": [
      {
        "days": [1, 2, 3, 4, 5],
        "startTime": "10:00",
        "endTime": "18:00"
      }
    ]
  }
}

callSchedule.slots must be an array. days are 0–6 (Sun–Sat), e.g. Mon–Fri = [1,2,3,4,5]. Day names like Mon are also accepted. Times must be HH:00 or HH:30. Sending string day names without the array shape caused CastError on callSchedule.slots.

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
  }
}

Update Post-Call Actions (Insights)

PUT/campaign/{campaignId}/insights

Updates callback webhook and post-call actions (summarize, categorize resolution, extract data). Same as chat post-call modal.

Preferred alias: PUT /campaign/{campaignId}/post-call-actions

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "callbackUrl": "https://crm.partner.com/webhooks/callmatic",
  "summarize": { "enabled": true, "maxWordLimit": 20 },
  "categorizeResolution": {
    "enabled": true,
    "categories": {
      "INTERESTED": "Caller wants to proceed",
      "NOT_INTERESTED": "Caller declined"
    }
  },
  "extractData": {
    "enabled": true,
    "fields": {
      "loan_amount": "Amount mentioned by caller",
      "lead_score": "Lead quality score"
    }
  }
}

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
  }
}

Clone Campaign

POST/campaign/clone

Creates a copy of an existing campaign.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "name": "Home Loan Qualifier Copy"
}

Response

{
  "success": true,
  "data": {
    "campaignId": "b15d4631-d96d-5554-a00e-8286736f0fdc"
  }
}

Get Campaign Details

GET/campaign/{campaignId}

Returns campaign status, call-initiation variables, extract-data fields, and categorize-resolution categories.

Headers

api-key: {{your_api_key}}

Sample Request

curl --location 'https://api.callmatic.ai/v1/campaign/a04c3520-c85c-4443-9ffd-7175625e9ecb' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "campaignName": "Home Loan Qualifier",
    "status": "ACTIVE",
    "state": "ACTIVE",
    "callbackUrl": "https://crm.partner.com/webhooks/callmatic",
    "callVariables": ["callee_name", "city_name"],
    "postCallDataVariables": [
      { "key": "loan_amount", "description": "Amount mentioned by caller" }
    ],
    "categorizeResolutionVariables": [
      { "key": "INTERESTED", "description": "Caller wants to proceed" }
    ],
    "summarize": { "enabled": true, "maxWordLimit": 20 }
  }
}

Account

Account-scoped lists for campaigns, payments, and purchases.

List Campaigns

GET/campaigns

Returns all campaigns for the authenticated account.

Headers

api-key: {{your_api_key}}

Sample Request

curl --location 'https://api.callmatic.ai/v1/campaigns' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
        "name": "Home Loan Qualifier",
        "status": "ACTIVE",
        "state": "ACTIVE"
      }
    ]
  }
}

List Payments

GET/payments

Payment history for the account (paginated).

Headers

api-key: {{your_api_key}}

Query Parameters

startTime (optional)
endTime (optional)
page (optional, default 1)
pageSize (optional, default 20, max 100)

Sample Request

curl --location 'https://api.callmatic.ai/v1/payments?startTime=2026-07-01T00:00:00Z&endTime=2026-07-15T23:59:59Z&page=1&pageSize=20' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "payments": [
      {
        "paymentId": "pay_123",
        "amount": 4999,
        "currency": "INR",
        "status": "captured",
        "planId": "plan_abc",
        "createdAt": "2026-07-10T12:00:00Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 20, "total": 1, "totalPages": 1 }
  }
}

List Purchases

GET/purchases

Purchase / entitlement history for the account (paginated).

Headers

api-key: {{your_api_key}}

Query Parameters

startTime (optional)
endTime (optional)
page (optional, default 1)
pageSize (optional, default 20, max 100)

Sample Request

curl --location 'https://api.callmatic.ai/v1/purchases?startTime=2026-07-01T00:00:00Z&endTime=2026-07-15T23:59:59Z&page=1&pageSize=20' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "purchases": [
      {
        "purchaseId": "pur_123",
        "planId": "plan_abc",
        "status": "active",
        "expiry": "2026-08-10T00:00:00Z",
        "limits": { "minutes": 1000, "calls": 1000 }
      }
    ],
    "pagination": { "page": 1, "pageSize": 20, "total": 1, "totalPages": 1 }
  }
}

Reports

Get Reports

GET/reports

Call analytics funnel + time series (same engine as the dashboard). Pass full ISO startTime / endTime (time is kept). Prefer the account timezone offset (e.g. +05:30) with timeZone=Asia/Kolkata.

Headers

api-key: {{your_api_key}}

Query Parameters

startTime (required, ISO)
endTime (required, ISO)
campaignId (optional)
timeZone (optional, default Asia/Kolkata)
page (optional, default 1)
pageSize (optional, default 20, max 100)

Sample Request

curl --location 'https://api.callmatic.ai/v1/reports?campaignId=a04c3520-c85c-4443-9ffd-7175625e9ecb&startTime=2026-07-01T00:00:00%2B05:30&endTime=2026-07-15T18:30:59%2B05:30&timeZone=Asia/Kolkata' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "startTime": "2026-07-01T00:00:00Z",
    "endTime": "2026-07-15T23:59:59Z",
    "funnel": {
      "triggeredCalls": 120,
      "completedCalls": 80,
      "failedCalls": 40
    },
    "timeSeries": [],
    "inFlightCallsCount": 2,
    "pagination": { "page": 1, "pageSize": 20, "total": 0, "totalPages": 0 }
  }
}

Voices, Plan & Phone Numbers

List Voices

GET/voice

Available TTS voices for campaign settings.

Headers

api-key: {{your_api_key}}

Query Parameters

language (optional) — e.g. en, hi

Response

{
  "success": true,
  "data": {
    "voices": [
      { "id": "112344", "name": "Dynamic Kangana" },
      { "id": "112345", "name": "Soft Arjun" }
    ]
  }
}

Get Active Plan

GET/plan

Active plan and usage for the account — same values shown in the dashboard Plan & usage widget. Returns final plan and usage fields only (no internal storage details).

Headers

api-key: {{your_api_key}}

Sample Request

curl --location 'https://api.callmatic.ai/v1/plan' \
--header 'api-key: {{your_api_key}}'

Response

{
  "success": true,
  "data": {
    "accountId": "acc_123",
    "account": {
      "status": "ACTIVE",
      "pauseSource": null,
      "pauseReason": null,
      "paused": false
    },
    "plan": {
      "planId": "plan_abc",
      "planName": "Growth",
      "status": "active",
      "expiry": "2026-08-10T00:00:00.000Z",
      "limits": { "minutes": 1000, "calls": 1000 },
      "purchaseId": "pur_123",
      "isPostpaid": false,
      "hasActivePlan": true
    },
    "usage": {
      "secondsLimit": 60000,
      "callsLimit": 1000,
      "secondsUsed": 1200,
      "callsUsed": 40,
      "secondsRemaining": 58800,
      "callsRemaining": 960,
      "minutesLimit": 1000,
      "minutesUsed": 20,
      "minutesRemaining": 980,
      "activePurchaseId": "pur_123",
      "lastProcessedAt": "2026-07-15T08:00:00.000Z"
    },
    "queuedPurchases": []
  }
}

List Phone Numbers

GET/phone-numbers

Phone numbers allocated to the account.

Headers

api-key: {{your_api_key}}

Response

{
  "success": true,
  "data": {
    "phoneNumbers": [
      {
        "phoneNumber": "+9198xxxxxxxx",
        "status": "active",
        "expiresAt": "2026-08-10T00:00:00Z",
        "gateway": "EXOTEL"
      }
    ]
  }
}

Pause / Resume

Control dialing at campaign or account level.

Pause Campaign

POST/campaigns/{campaignId}/pause

Pauses outbound dialing for one campaign.

Headers

api-key: {{your_api_key}}

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "status": "PAUSED"
  }
}

Resume Campaign

POST/campaigns/{campaignId}/resume

Resumes outbound dialing for a paused campaign.

Headers

api-key: {{your_api_key}}

Response

{
  "success": true,
  "data": {
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "status": "ACTIVE"
  }
}

Pause Account

POST/account/pause

Pauses outbound dialing for the entire account.

Headers

Content-Type: application/json
api-key: {{your_api_key}}

Request Body

{
  "reason": "Paused from CRM"
}

Response

{
  "success": true,
  "data": {
    "accountStatus": "PAUSED"
  }
}

Resume Account

POST/account/resume

Resumes outbound dialing for a paused account.

Headers

api-key: {{your_api_key}}

Response

{
  "success": true,
  "data": {
    "accountStatus": "ACTIVE"
  }
}

Error Handling

Errors return JSON with an HTTP status code.

{
  "success": false,
  "error": "Invalid API key"
}

Webhook Callback Notification

After a call completes, we POST to your campaign callback URL. Configure it with PUT /campaign/{campaignId}/insights.

Request body

{
  "callId": "e08bad66-ee60-458d-958f-a02b1f12d355",
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
  "direction": "OUTBOUND",
  "phoneNumber": "7347087599",
  "status": "completed",
  "duration": 19.18,
  "transcript": [],
  "insights": [
    {
      "actionType": "SUMMARIZE",
      "output": { "summary": "..." }
    }
  ]
}

Back to home