Developers
API v1
A REST API over the same model the console uses: 47 operations in 18 groups, described by an OpenAPI 3.1 document that is generated from the API's own route table.
Base URL and authentication
Send requests to your console's address under /api/v1/, for example https://api.ringura.com/api/v1/contacts. Accounts on a reseller's own console domain use that domain instead.
Authenticate every request with a bearer token: Authorization: Bearer cck_.... An administrator whose session has passed MFA creates tokens in the console's Developer page, each with the scopes it needs and a limit of requests a minute. A token in a URL is never accepted, and your account's API allow-list of IP addresses applies.
Each token belongs to one account, and every request sees only that account's data.
Scopes
Each operation needs one scope. A token without it gets 403 insufficient_scope.
Conventions
Pagination
Lists take limit (1 to 200, 50 by default) and cursor, and answer { "data": [...], "nextCursor": "..." }. Pass nextCursor back as cursor for the next page; it is null on the last one. Cursors are opaque and keyed on a stable order, so rows inserted while you page are never repeated or skipped.
Idempotency
Writes accept an Idempotency-Key header (8 to 100 letters, digits or _ . : -). A retry with the same key and body gets the first answer with Idempotent-Replayed: true; the same key with another body gets 422. A failed write leaves no key behind, so it can be retried.
Rate limits
Each token has a limit of requests a minute. Every answer carries RateLimit-Limit and RateLimit-Remaining; over the limit, the answer is 429 with Retry-After in seconds.
Times, money and phone numbers
Times are ISO 8601 in UTC. Amounts are integers in minor units (cents) with a currency. Phone numbers are E.164, such as +441632960000.
Errors
Errors are JSON: { "error": "code", "message": "..." }, with problems listing each field that did not fit on a 400. The statuses the API uses:
| Status | Meaning |
|---|---|
400 | The request is malformed: see problems. |
401 | No valid bearer token. |
403 | The token lacks the scope, or the address is not allowed. |
404 | No such object in your tenant. |
409 | The object is not in a state that allows this. |
422 | The Idempotency-Key was used with another request. |
429 | Rate limit: wait Retry-After seconds. |
API reference
Every operation with its parameters, request and response fields and an example. The same content as the OpenAPI document.
Contacts
4 operations:
GET /contacts,POST /contacts,GET /contacts/{id},PATCH /contacts/{id}Conversations
3 operations:
GET /conversations,GET /conversations/{id},PATCH /conversations/{id}Messages
2 operations:
GET /conversations/{id}/messages,POST /conversations/{id}/messagesInteractions
2 operations:
GET /interactions,GET /interactions/{id}Campaigns
2 operations:
GET /campaigns,GET /campaigns/{id}People
3 operations:
GET /users,GET /agents,GET /queuesWallet
1 operations:
GET /walletTickets
6 operations:
GET /tickets,POST /tickets,GET /tickets/{id},PATCH /tickets/{id},POST /tickets/{id}/merge,POST /tickets/{id}/splitWebhooks
8 operations:
GET /event-types,GET /webhook-endpoints,POST /webhook-endpoints,GET /webhook-endpoints/{id},PATCH /webhook-endpoints/{id},POST /webhook-endpoints/{id}/rotate-secret,GET /webhook-deliveries,POST /webhook-deliveries/{id}/replayReports
1 operations:
GET /reports/{groupBy}Surveys
2 operations:
GET /surveys,POST /surveys/{id}/responsesAnalytics
4 operations:
GET /exports,POST /exports,GET /exports/{id},GET /exports/{id}/downloadOutcomes
1 operations:
POST /outcomesCalls
1 operations:
POST /callsLeads
1 operations:
POST /leadsTasks
2 operations:
POST /tasks,GET /tasks/{id}Notifications
3 operations:
POST /notifications,GET /notifications/{id},PUT /contacts/{id}/notification-preferencesQuality
1 operations:
GET /qa/evaluations