SMS API reference | CaptiFi Connect

The basics

Base URL https://captificonnect.co.uk/api/v1. Send Authorization: Bearer <api key> on every request, and JSON bodies with Content-Type: application/json, up to 1 MB. Each key can make 20 requests a second, with bursts up to 40.

Successful responses are { "data": ..., "meta": ... }. Lists are newest first, 25 to a page by default (up to 100 with limit); pass meta.next_cursor back as cursor for the next page. Errors are described in errors, and events in webhooks.

Messages

Send texts and read what was sent and received.

get/messages
post/messages
post/messages/quote
get/messages/{id}
post/messages/{id}/cancel
get/messages/export

List messages

get/api/v1/messages

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.
`direction`query	one of outbound, inbound
`status`query	MessageStatus
`q`query	string	A number (any format) or text to find in the body.
`campaign_id`query	string
`batch_id`query	string
`client_ref`query	string
`since`query	date-time
`until`query	date-time

Responses

200A page of messages.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Send texts

post/api/v1/messages

Sends one text to every recipient given in to, contact_ids and list_id together. Numbers are checked and de-duplicated; refused numbers are listed in rejected and not charged. Merge fields such as {first_name} are filled from contacts. Credits are taken when the request is accepted (one per SMS part) and refunded for any text that fails before leaving.

Parameters

Name	Type	About
`Idempotency-Key`header	string	Up to 200 characters. Makes a retried request safe.

Request body (JSON)

Name	Type	About
`to`	string or array of string	UK numbers in any common format. A string may hold several, separated by commas or new lines.
`contact_ids`	array of string
`list_id`	string
`body`	string	Up to 10 SMS parts. Merge fields: {first_name}, {last_name}, {full_name}, {phone}, {email}.
`template_id`	string	Used when body is empty.
`sender`	string or null	An approved sender name. Leave out to send from a number people can reply to.
`schedule_at`	date-time or null	Up to a year ahead.
`client_ref`	string or null	Your own reference, echoed back in webhooks.
`append_opt_out`	boolean	Adds the account opt-out line (for marketing texts).

Example request body

{
  "to": [
    "07412 000001",
    "+447412000002"
  ],
  "body": "Hi {first_name}, your order is ready.",
  "client_ref": "order-881"
}

Responses

200An idempotent replay of an earlier request.
201Accepted. Texts are queued (or scheduled).
401Missing, wrong or revoked key.
402Not enough credit. details.needed and details.balance say by how much.
403The account is pending approval (account_pending) or suspended (account_suspended).
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Price a send without sending

post/api/v1/messages/quote

Takes the same body as POST /messages and returns what it would charge.

Request body (JSON)

Name	Type	About
`to`	string or array of string	UK numbers in any common format. A string may hold several, separated by commas or new lines.
`contact_ids`	array of string
`list_id`	string
`body`	string	Up to 10 SMS parts. Merge fields: {first_name}, {last_name}, {full_name}, {phone}, {email}.
`template_id`	string	Used when body is empty.
`sender`	string or null	An approved sender name. Leave out to send from a number people can reply to.
`schedule_at`	date-time or null	Up to a year ahead.
`client_ref`	string or null	Your own reference, echoed back in webhooks.
`append_opt_out`	boolean	Adds the account opt-out line (for marketing texts).

Responses

200The quote.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get a message with its status timeline

get/api/v1/messages/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The message id.

Responses

200The message.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Example 200 response

{
  "data": {
    "id": "msg_01J9Z8X7W6V5T4S3R2Q1P0N9M8",
    "direction": "outbound",
    "status": "delivered",
    "to": "+447412000001",
    "from": "+447700900321",
    "contact_number": "+447412000001",
    "body": "Your table for 4 at 7pm is confirmed.",
    "encoding": "gsm7",
    "segments": 1,
    "credits": 1,
    "route": "sim",
    "sender": null,
    "client_ref": "booking-1042",
    "batch_id": "bat_01J9Z8X7W6V5T4S3R2Q1P0N9M7",
    "campaign_id": null,
    "contact_id": null,
    "error_code": null,
    "error_message": null,
    "test": false,
    "scheduled_at": null,
    "sent_at": "2026-10-16T09:00:02.000Z",
    "delivered_at": "2026-10-16T09:00:06.000Z",
    "failed_at": null,
    "cancelled_at": null,
    "received_at": null,
    "read_at": null,
    "created_at": "2026-10-16T09:00:00.000Z",
    "events": [
      {
        "status": "queued",
        "detail": null,
        "at": "2026-10-16T09:00:00.000Z"
      }
    ]
  },
  "meta": null
}

Cancel a scheduled text

post/api/v1/messages/{id}/cancel

Works while the text is scheduled or still queued. Its credits are refunded.

Parameters

Name	Type	About
`id`pathrequired	string	The message id.

Responses

200Cancelled.
401Missing, wrong or revoked key.
404No such resource in this account.
409Already on its way.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Export messages as CSV

get/api/v1/messages/export

Accepts the list filters. Up to 50,000 rows.

Responses

200CSV file.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Conversations

Two-way threads, one per number that replied.

get/conversations
get/conversations/{phone}
post/conversations/{phone}/read

List conversations

get/api/v1/conversations

One entry per number that has texted you, newest activity first.

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.
`unread`query	one of true, false
`q`query	string

Responses

200Conversations.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get one conversation

get/api/v1/conversations/{phone}

Parameters

Name	Type	About
`phone`pathrequired	string	The number in E.164, URL-encoded (%2B447412000001).

Responses

200The last 200 texts, oldest first.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Mark a conversation read

post/api/v1/conversations/{phone}/read

Parameters

Name	Type	About
`phone`pathrequired	string

Responses

200How many texts were marked read.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Contacts

Your address book.

get/contacts/fields
get/contacts
post/contacts
get/contacts/{id}
patch/contacts/{id}
delete/contacts/{id}
post/contacts/import

List custom field names

get/api/v1/contacts/fields

The distinct custom field names in use across your contacts, so a text can merge them as {field_name}.

Responses

200Field names, sorted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Example 200 response

{
  "data": [
    "booking_ref",
    "branch"
  ],
  "meta": null
}

List contacts

get/api/v1/contacts

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.
`q`query	string
`list_id`query	string

Responses

200A page of contacts.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Create a contact

post/api/v1/contacts

Request body (JSON)

Name	Type	About
`phone`required	string
`first_name`	string or null
`last_name`	string or null
`email`	string or null
`notes`	string or null
`custom`	object

Example request body

{
  "phone": "07412 000001",
  "first_name": "Priya",
  "last_name": "Shah"
}

Responses

201Created.
401Missing, wrong or revoked key.
404No such resource in this account.
409That number is already a contact.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get a contact

get/api/v1/contacts/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The contact id.

Responses

200The contact and its list ids.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Update a contact

patch/api/v1/contacts/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The contact id.

Request body (JSON)

Name	Type	About
`phone`required	string
`first_name`	string or null
`last_name`	string or null
`email`	string or null
`notes`	string or null
`custom`	object

Responses

200Updated.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Delete a contact

delete/api/v1/contacts/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The contact id.

Responses

204Deleted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Import contacts

post/api/v1/contacts/import

Upserts up to 20,000 rows by number. Blank fields leave stored values alone.

Request body (JSON)

Name	Type	About
`rows`required	array of ContactInput
`list_id`	string or null

Responses

200What happened to each row.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Lists

Groups of contacts.

get/lists
post/lists
get/lists/{id}
patch/lists/{id}
delete/lists/{id}
get/lists/{id}/contacts
post/lists/{id}/contacts
delete/lists/{id}/contacts/{contactId}

List lists

get/api/v1/lists

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.

Responses

200Lists.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Create a list

post/api/v1/lists

Request body (JSON)

Name	Type	About
`name`required	string
`description`	string or null

Responses

201Created.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get a list

get/api/v1/lists/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The list id.

Responses

200The list.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Rename a list

patch/api/v1/lists/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The list id.

Request body (JSON)

Name	Type	About
`name`required	string
`description`	string or null

Responses

200Updated.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Delete a list (contacts stay)

delete/api/v1/lists/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The list id.

Responses

204Deleted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

List members

get/api/v1/lists/{id}/contacts

Parameters

Name	Type	About
`id`pathrequired	string	The list id.
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.

Responses

200Members.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Add members

post/api/v1/lists/{id}/contacts

By contact id or by number (new numbers become contacts).

Parameters

Name	Type	About
`id`pathrequired	string	The list id.

Request body (JSON)

Name	Type	About
`contact_ids`	array of string
`phones`	array of string

Responses

200How many were added.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Remove a member

delete/api/v1/lists/{id}/contacts/{contactId}

Parameters

Name	Type	About
`id`pathrequired	string	The list id.
`contactId`pathrequired	string

Responses

204Removed.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Campaigns

One text to a whole list.

get/campaigns
post/campaigns
get/campaigns/{id}
patch/campaigns/{id}
delete/campaigns/{id}
post/campaigns/{id}/send
post/campaigns/{id}/cancel

List campaigns

get/api/v1/campaigns

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.

Responses

200Campaigns with message counts.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Create a draft campaign

post/api/v1/campaigns

Request body (JSON)

Name	Type	About
`name`required	string
`body`required	string
`list_id`required	string
`sender`	string or null
`append_opt_out`	boolean

Responses

201The draft.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get a campaign

get/api/v1/campaigns/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The campaign id.

Responses

200The campaign.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Edit a draft

patch/api/v1/campaigns/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The campaign id.

Request body (JSON)

Name	Type	About
`name`required	string
`body`required	string
`list_id`required	string
`sender`	string or null
`append_opt_out`	boolean

Responses

200Updated.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Delete a draft

delete/api/v1/campaigns/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The campaign id.

Responses

204Deleted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Send or schedule a draft

post/api/v1/campaigns/{id}/send

Parameters

Name	Type	About
`id`pathrequired	string	The campaign id.

Request body (JSON)

Name	Type	About
`schedule_at`	date-time or null

Responses

200Launched.
401Missing, wrong or revoked key.
402Not enough credit. details.needed and details.balance say by how much.
404No such resource in this account.
409Already launched.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Cancel a scheduled or sending campaign

post/api/v1/campaigns/{id}/cancel

Texts not yet taken by a route are cancelled and refunded.

Parameters

Name	Type	About
`id`pathrequired	string	The campaign id.

Responses

200Cancelled.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Templates

Saved texts.

get/templates
post/templates
get/templates/{id}
patch/templates/{id}
delete/templates/{id}

List templates

get/api/v1/templates

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.
`q`query	string

Responses

200Templates.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Create a template

post/api/v1/templates

Request body (JSON)

Name	Type	About
`name`required	string
`body`required	string

Responses

201Created.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get a template

get/api/v1/templates/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The template id.

Responses

200The template.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Update a template

patch/api/v1/templates/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The template id.

Request body (JSON)

Name	Type	About
`name`required	string
`body`required	string

Responses

200Updated.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Delete a template

delete/api/v1/templates/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The template id.

Responses

204Deleted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Opt-outs

Numbers that must not be texted.

get/opt-outs
post/opt-outs
delete/opt-outs/{phone}

List opt-outs

get/api/v1/opt-outs

Parameters

Name	Type	About
`limit`query	integer
`offset`query	integer
`q`query	string

Responses

200Opt-outs.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Add an opt-out

post/api/v1/opt-outs

Request body (JSON)

Name	Type	About
`phone`required	string
`note`	string or null

Responses

200Already opted out.
201Added.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Remove an opt-out

delete/api/v1/opt-outs/{phone}

Only when the person has asked to hear from you again.

Parameters

Name	Type	About
`phone`pathrequired	string

Responses

204Removed.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Sender names

Alphanumeric senders (approval needed).

get/sender-ids
post/sender-ids

List sender names

get/api/v1/sender-ids

Responses

200Sender names and their review state.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Ask for a sender name

post/api/v1/sender-ids

Request body (JSON)

Name	Type	About
`value`required	string
`purpose`	string

Responses

201Waiting for review.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Webhooks

Endpoints that receive events.

get/webhooks
post/webhooks
patch/webhooks/{id}
delete/webhooks/{id}
post/webhooks/{id}/test
get/webhooks/{id}/deliveries

List webhooks

get/api/v1/webhooks

Responses

200Webhooks.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Create a webhook

post/api/v1/webhooks

The response includes secret, shown only this once.

Request body (JSON)

Name	Type	About
`url`	string
`events`	array of one of message.sent, message.delivered, message.failed, message.received, opt_out.created
`description`	string or null
`enabled`	boolean
`rotate_secret`	boolean

Example request body

{
  "url": "https://example.com/connect/events",
  "events": [
    "message.delivered",
    "message.received"
  ]
}

Responses

201Created.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Update a webhook

patch/api/v1/webhooks/{id}

rotate_secret: true issues a new secret, returned once.

Parameters

Name	Type	About
`id`pathrequired	string	The webhook id.

Request body (JSON)

Name	Type	About
`url`	string
`events`	array of one of message.sent, message.delivered, message.failed, message.received, opt_out.created
`description`	string or null
`enabled`	boolean
`rotate_secret`	boolean

Responses

200Updated.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Delete a webhook

delete/api/v1/webhooks/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The webhook id.

Responses

204Deleted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Send a test event now

post/api/v1/webhooks/{id}/test

Parameters

Name	Type	About
`id`pathrequired	string	The webhook id.

Responses

200What your endpoint answered.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Recent deliveries

get/api/v1/webhooks/{id}/deliveries

Parameters

Name	Type	About
`id`pathrequired	string	The webhook id.
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.

Responses

200Deliveries.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Account

Balance and usage.

get/numbers
get/balance
get/stats/summary
get/stats/timeseries

List dedicated numbers

get/api/v1/numbers

The UK mobile numbers dedicated to the account. Texts on the SIM route go from one of them and every reply to it belongs to the account. Each is rented monthly in credits (rental_credits, taken every 30 days from rental_charged_at). Ask for one, or release one, from the Numbers page in the dashboard.

Responses

200Dedicated numbers.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Example 200 response

{
  "data": [
    {
      "id": "gw_01J9Z8X7W6V5T4S3R2Q1P0N9M8",
      "phone_number": "+447700900321",
      "online": true,
      "rental_credits": 250,
      "monthly_credits": 250,
      "rental_charged_at": "2026-10-16T09:00:00.000Z",
      "assigned_at": "2026-10-16T09:00:00.000Z"
    }
  ],
  "meta": null
}

Credit balance

get/api/v1/balance

Responses

200Balance.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Example 200 response

{
  "data": {
    "credits": 1240,
    "account_status": "active"
  },
  "meta": null
}

Totals for a period

get/api/v1/stats/summary

Parameters

Name	Type	About
`days`query	integer
`from`query	date-time
`to`query	date-time

Responses

200Sent, delivered, received and credits, with the change on the period before.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Daily counts for a period

get/api/v1/stats/timeseries

Parameters

Name	Type	About
`days`query	integer

Responses

200One row per day.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Keywords

Words people text in for an automatic reply and a list.

get/keywords
post/keywords
get/keywords/{id}
patch/keywords/{id}
delete/keywords/{id}

List keywords

get/api/v1/keywords

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.

Responses

200Keywords.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Create a keyword

post/api/v1/keywords

A keyword is matched against the first word of an inbound text, ignoring case and punctuation. When it matches, the sender becomes a contact, is added to add_to_list_id when set, and gets reply as a text from your number (one credit per part, nothing to an opted-out number). STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, START and UNSTOP are reserved and refused with reserved_keyword. On a shared number a keyword works for people you texted in the last 30 days; on a dedicated number it works for anyone.

Request body (JSON)

Name	Type	About
`keyword`required	string	Letters and digits; stored upper-case. Not an opt-out or opt-in word.
`reply`	string or null	Sent back from your number when the keyword matches. Leave empty for no reply.
`add_to_list_id`	string or null	A list of yours the sender is added to.
`enabled`	boolean

Example request body

{
  "keyword": "JOIN",
  "reply": "Thanks, you are on the list.",
  "add_to_list_id": "lst_01J9Z8X7W6V5T4S3R2Q1P0N9M2"
}

Responses

201Created.
401Missing, wrong or revoked key.
404No such resource in this account.
409That keyword already exists on the account (keyword_exists).
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Example 201 response

{
  "data": {
    "id": "kw_01J9Z8X7W6V5T4S3R2Q1P0N9M1",
    "keyword": "JOIN",
    "reply": "Thanks, you are on the list. Reply STOP at any time to leave.",
    "add_to_list_id": "lst_01J9Z8X7W6V5T4S3R2Q1P0N9M2",
    "enabled": true,
    "match_count": 12,
    "last_matched_at": "2026-10-16T09:12:00.000Z",
    "created_at": "2026-10-01T10:00:00.000Z",
    "updated_at": "2026-10-01T10:00:00.000Z"
  },
  "meta": null
}

Get a keyword

get/api/v1/keywords/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The keyword id.

Responses

200The keyword.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Edit a keyword

patch/api/v1/keywords/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The keyword id.

Request body (JSON)

Name	Type	About
`keyword`required	string	Letters and digits; stored upper-case. Not an opt-out or opt-in word.
`reply`	string or null	Sent back from your number when the keyword matches. Leave empty for no reply.
`add_to_list_id`	string or null	A list of yours the sender is added to.
`enabled`	boolean

Responses

200Updated.
401Missing, wrong or revoked key.
404No such resource in this account.
409That keyword already exists on the account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Delete a keyword

delete/api/v1/keywords/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The keyword id.

Responses

204Deleted.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Links

Short tracked links and their clicks.

get/links
get/links/{id}

List tracked links

get/api/v1/links

One row per URL per recipient, newest first. Filter by campaign or message.

Parameters

Name	Type	About
`limit`query	integer	Items per page, 1 to 100 (default 25).
`cursor`query	string	The `meta.next_cursor` of the previous page.
`campaign_id`query	string
`message_id`query	string

Responses

200Links.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Get a tracked link

get/api/v1/links/{id}

Parameters

Name	Type	About
`id`pathrequired	string	The link id.

Responses

200The link.
401Missing, wrong or revoked key.
404No such resource in this account.
422The request is not valid; details lists the fields.
429Over 20 requests a second (burst 40). Retry after the Retry-After header.

Example 200 response

{
  "data": {
    "id": "lnk_01J9Z8X7W6V5T4S3R2Q1P0N9M3",
    "code": "k3Dx9aQ",
    "short_url": "https://captificonnect.co.uk/l/k3Dx9aQ",
    "url": "https://example.com/october-offer",
    "message_id": "msg_01J9Z8X7W6V5T4S3R2Q1P0N9M8",
    "campaign_id": "cmp_01J9Z8X7W6V5T4S3R2Q1P0N9M4",
    "contact_number": "+447412000001",
    "clicks": 1,
    "first_clicked_at": "2026-10-16T09:05:00.000Z",
    "last_clicked_at": "2026-10-16T09:05:00.000Z",
    "created_at": "2026-10-16T09:00:00.000Z"
  },
  "meta": null
}