Callmatic

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

  1. Sign in at the Callmatic Admin Portal.
  2. Open Profile → Account Section → Generate API Key.
  3. 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 accepts a language and prompt; update accepts a single edit prompt per request — edit history is stored server-side by campaignId.

Create Campaign

POST/campaign

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

Headers

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

Sample Request

curl --location 'https://api.callmatic.ai/v1/campaign' \
--header 'api-key: {{your_api_key}}' \
--header 'Content-Type: application/json' \
--data '{
  "language": "en",
  "prompt": "I need a home loan campaign",
  "name": "Home Loan Qualifier"
}'

Request Body

{
  "language": "en",
  "prompt": "I need a home loan campaign",
  "name": "Home Loan Qualifier"
}

language and prompt are required. name is optional.

Response — campaign created

{
  "success": true,
  "data": {
    "createCampaign": true,
    "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb",
    "message": "Your home loan agent is ready."
  }
}

Update Campaign Prompt

PUT/campaign/{campaignId}

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

The prompt is a change request (e.g. "Make the opening warmer"), not the full call script. Prior edit turns for this campaignId are kept on the server, so follow-up edits can build on earlier instructions.

Headers

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

Sample Request

curl --location --request PUT 'https://api.callmatic.ai/v1/campaign/a04c3520-c85c-4443-9ffd-7175625e9ecb' \
--header 'api-key: {{your_api_key}}' \
--header 'Content-Type: application/json' \
--data '{
  "prompt": "Make the opening warmer and ask for monthly income earlier.",
  "name": "Home Loan Qualifier"
}'

Request Body

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

Rename only: send { "name": "New name" }. Prompt only: omit name.

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 active Cartesia 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"
      }
    ]
  }
}

Inbound Routing

Configure what happens when someone calls your allocated phone numbers — forward to another number or route to a voice agent campaign (same as the dashboard Inbound Call Flow page).

Get Inbound Routing

GET/routing

Returns each account phone number and its current inbound mapping (forward, campaign link, or none).

Headers

api-key: {{your_api_key}}

Sample Request

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

Response

{
  "success": true,
  "data": {
    "phoneNumbers": [
      {
        "phoneNumber": "+9198xxxxxxxx",
        "mapping": {
          "type": "campaign",
          "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
        }
      },
      {
        "phoneNumber": "+9199xxxxxxxx",
        "mapping": {
          "type": "forward",
          "forwardToNumber": "+919876543210"
        }
      },
      {
        "phoneNumber": "+9177xxxxxxxx",
        "mapping": null
      }
    ]
  }
}

Response — no numbers allocated (HTTP 200)

{
  "success": true,
  "data": {
    "phoneNumbers": [],
    "message": "No phone numbers allocated to this account. Purchase or allocate numbers first (GET /v1/phone-numbers)."
  }
}

Inbound forward/link/clear calls return HTTP 400 with the same message until at least one number is allocated. Check GET /phone-numbers for the account's allocated numbers.

Set Inbound Routing

PUT/routing

Routes inbound calls on a number — either forward to another phone number or link to a voice agent campaign. Provide forwardToNumber or campaignId, not both.

Headers

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

Request Body — forward

{
  "phoneNumber": "+9198xxxxxxxx",
  "forwardToNumber": "+919876543210"
}

Request Body — campaign

{
  "phoneNumber": "+9198xxxxxxxx",
  "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
}

Alias: inboundNumber is accepted instead of phoneNumber.

Response — forward

{
  "success": true,
  "data": {
    "phoneNumber": "+9198xxxxxxxx",
    "mapping": {
      "type": "forward",
      "forwardToNumber": "+919876543210"
    }
  }
}

Response — campaign

{
  "success": true,
  "data": {
    "phoneNumber": "+9198xxxxxxxx",
    "mapping": {
      "type": "campaign",
      "campaignId": "a04c3520-c85c-4443-9ffd-7175625e9ecb"
    }
  }
}

Clear Inbound Routing

DELETE/routing

Removes forward or campaign routing for a phone number.

Headers

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

Request Body

{
  "phoneNumber": "+9198xxxxxxxx"
}

Response

{
  "success": true,
  "data": {
    "cleared": true
  }
}

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