API reference
Tasks
2 operations. Base URL: https://api.ringura.com/api/v1. Authenticate with a bearer token that carries the scope named on each operation.
POST /api/v1/tasks
Create a task (a callback, voicemail, web form, CRM follow-up or back-office case) routed to the agents of a queue like a conversation; externalRef makes it idempotent.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
Idempotency-Key | header | string | No | matches ^[A-Za-z0-9_.:-]{8,100}$ |
Request body
JSON (Content-Type: application/json).
| Field | Type | Required | Constraints |
|---|---|---|---|
kind | string | Yes | one of "callback", "voicemail", "web_form", "crm_followup", "back_office" |
title | string | Yes | 1-200 characters |
queueId | string (uuid) | Yes | |
contactId | string (uuid) | No | |
priority | integer | No | 1 to 5 |
dueAt | string (date-time) | No | |
externalRef | string | No | 1-200 characters |
details | object | No | free-form object |
Response
201 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
kind | string | Yes | one of "callback", "voicemail", "web_form", "crm_followup", "back_office" |
title | string | Yes | |
details | object | Yes | free-form object |
contactId | string (uuid) or null | Yes | |
conversationId | string (uuid) | Yes | |
interactionId | string (uuid) | Yes | |
queueId | string (uuid) | Yes | |
priority | integer | Yes | |
dueAt | string (date-time) or null | Yes | |
status | string | Yes | one of "open", "done", "cancelled" |
externalRef | string or null | Yes | |
createdBy | string | Yes | |
createdAt | string (date-time) | Yes | |
completedAt | string (date-time) or null | Yes | |
outcome | string or null | Yes | |
workItem | object or null | Yes | free-form object |
Errors
400, 401, 403, 404, 409, 422, 429. What each status means
Example request
curl -X POST 'https://api.ringura.com/api/v1/tasks' \
-H "Authorization: Bearer $CC_TOKEN" \
-H 'Idempotency-Key: order-2027-0001' \
-H 'Content-Type: application/json' \
-d '{
"kind": "callback",
"title": "Order question",
"queueId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e"
}'GET /api/v1/tasks/{id}
One task with its routing state.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
id | path | string (uuid) | Yes |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
kind | string | Yes | one of "callback", "voicemail", "web_form", "crm_followup", "back_office" |
title | string | Yes | |
details | object | Yes | free-form object |
contactId | string (uuid) or null | Yes | |
conversationId | string (uuid) | Yes | |
interactionId | string (uuid) | Yes | |
queueId | string (uuid) | Yes | |
priority | integer | Yes | |
dueAt | string (date-time) or null | Yes | |
status | string | Yes | one of "open", "done", "cancelled" |
externalRef | string or null | Yes | |
createdBy | string | Yes | |
createdAt | string (date-time) | Yes | |
completedAt | string (date-time) or null | Yes | |
outcome | string or null | Yes | |
workItem | object or null | Yes | free-form object |
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/tasks/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
-H "Authorization: Bearer $CC_TOKEN"