API reference
Contacts
4 operations. Base URL: https://api.ringura.com/api/v1. Authenticate with a bearer token that carries the scope named on each operation.
GET /api/v1/contacts
List contacts, oldest first; filter by phone (E.164) or e-mail for screen-pop.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
limit | query | integer | No | 1 to 200 |
cursor | query | string | No | at most 400 characters |
phone | query | string | No | matches ^[+][1-9][0-9]{6,14}$ |
email | query | string | No | at most 320 characters |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
data | array of object | Yes | |
data[].id | string (uuid) | Yes | |
data[].displayName | string or null | Yes | |
data[].language | string or null | Yes | |
data[].timeZone | string or null | Yes | |
data[].identifiers | array of object | Yes | |
data[].identifiers[].kind | string | Yes | |
data[].identifiers[].value | string | Yes | |
data[].identifiers[].scope | string | Yes | |
data[].identifiers[].verified | boolean | Yes | |
data[].createdAt | string (date-time) | Yes | |
nextCursor | string or null | Yes |
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/contacts' \
-H "Authorization: Bearer $CC_TOKEN"POST /api/v1/contacts
Create a contact with at least one phone number or e-mail address.
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 |
|---|---|---|---|
displayName | string | No | 1-200 characters |
language | string | No | matches ^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$ |
timeZone | string | No | at most 64 characters |
identifiers | array of object | Yes | at least 1 items at most 10 items |
identifiers[].kind | string | Yes | one of "e164", "email" |
identifiers[].value | string | Yes | 3-320 characters |
Response
201 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
displayName | string or null | Yes | |
language | string or null | Yes | |
timeZone | string or null | Yes | |
identifiers | array of object | Yes | |
identifiers[].kind | string | Yes | |
identifiers[].value | string | Yes | |
identifiers[].scope | string | Yes | |
identifiers[].verified | boolean | Yes | |
createdAt | string (date-time) | Yes |
Errors
400, 401, 403, 404, 409, 422, 429. What each status means
Example request
curl -X POST 'https://api.ringura.com/api/v1/contacts' \
-H "Authorization: Bearer $CC_TOKEN" \
-H 'Idempotency-Key: order-2027-0001' \
-H 'Content-Type: application/json' \
-d '{
"identifiers": [
{
"kind": "e164",
"value": "example"
}
]
}'GET /api/v1/contacts/{id}
One contact with its identifiers.
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 | |
displayName | string or null | Yes | |
language | string or null | Yes | |
timeZone | string or null | Yes | |
identifiers | array of object | Yes | |
identifiers[].kind | string | Yes | |
identifiers[].value | string | Yes | |
identifiers[].scope | string | Yes | |
identifiers[].verified | boolean | Yes | |
createdAt | string (date-time) | Yes |
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/contacts/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
-H "Authorization: Bearer $CC_TOKEN"PATCH /api/v1/contacts/{id}
Change a contact's name, language or time zone.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
id | path | string (uuid) | Yes | |
Idempotency-Key | header | string | No | matches ^[A-Za-z0-9_.:-]{8,100}$ |
Request body
JSON (Content-Type: application/json).
| Field | Type | Required | Constraints |
|---|---|---|---|
displayName | string or null | No | 1-200 characters |
language | string or null | No | matches ^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$ |
timeZone | string or null | No | at most 64 characters |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
displayName | string or null | Yes | |
language | string or null | Yes | |
timeZone | string or null | Yes | |
identifiers | array of object | Yes | |
identifiers[].kind | string | Yes | |
identifiers[].value | string | Yes | |
identifiers[].scope | string | Yes | |
identifiers[].verified | boolean | Yes | |
createdAt | string (date-time) | Yes |
Errors
400, 401, 403, 404, 409, 422, 429. What each status means
Example request
curl -X PATCH 'https://api.ringura.com/api/v1/contacts/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
-H "Authorization: Bearer $CC_TOKEN" \
-H 'Idempotency-Key: order-2027-0001' \
-H 'Content-Type: application/json' \
-d '{
"displayName": "Example"
}'