API reference

Tickets

6 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/tickets`

Tickets, newest reference number first.

Scope: tickets:read
Operation id: listTickets

Parameters

Parameters of GET /api/v1/tickets
Name	In	Type	Required	Constraints
`limit`	query	integer	No	1 to 200
`cursor`	query	string	No	at most 400 characters
`status`	query	string	No	one of "open", "pending", "snoozed", "resolved", "closed"
`tag`	query	string	No	at most 40 characters

Response

200 JSON with these fields.

Response fields of GET /api/v1/tickets
Field	Type	Required	Constraints
`data`	array of object	Yes
`data[].id`	string (uuid)	Yes
`data[].caseNumber`	integer	Yes
`data[].reference`	string	Yes
`data[].subject`	string or null	Yes
`data[].status`	string	Yes
`data[].priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`data[].caseType`	string or null	Yes
`data[].fields`	object	Yes	free-form object
`data[].disposition`	string or null	Yes
`data[].tags`	array of string	Yes
`data[].assigneeId`	string (uuid) or null	Yes
`data[].queueId`	string (uuid) or null	Yes
`data[].contactId`	string (uuid)	Yes
`data[].version`	integer	Yes
`data[].slaPolicyId`	string (uuid) or null	Yes
`data[].firstResponseDueAt`	string (date-time) or null	Yes
`data[].nextResponseDueAt`	string (date-time) or null	Yes
`data[].resolutionDueAt`	string (date-time) or null	Yes
`data[].firstRepliedAt`	string (date-time) or null	Yes
`data[].openedAt`	string (date-time) or null	Yes
`data[].closedAt`	string (date-time) or null	Yes
`data[].mergedInto`	string (uuid) or null	Yes
`data[].lastActivityAt`	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/tickets' \
  -H "Authorization: Bearer $CC_TOKEN"

POST `/api/v1/tickets`

Make a conversation a ticket: a reference number, case fields and SLA due times.

Scope: tickets:write
Operation id: createTicket
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of POST /api/v1/tickets
Name	In	Type	Required	Constraints
`Idempotency-Key`	header	string	No	matches ^[A-Za-z0-9_.:-]{8,100}$

Request body

JSON (Content-Type: application/json).

Request body of POST /api/v1/tickets
Field	Type	Required	Constraints
`conversationId`	string (uuid)	Yes
`subject`	string	No	1-500 characters
`priority`	string	No	one of "urgent", "high", "normal", "low", "lowest"
`caseType`	string	No	1-100 characters
`fields`	object	No	free-form object
`tags`	array of string	No	at most 50 items
`assigneeId`	string (uuid) or null	No

Response

201 JSON with these fields.

Response fields of POST /api/v1/tickets
Field	Type	Required	Constraints
`id`	string (uuid)	Yes
`caseNumber`	integer	Yes
`reference`	string	Yes
`subject`	string or null	Yes
`status`	string	Yes
`priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`caseType`	string or null	Yes
`fields`	object	Yes	free-form object
`disposition`	string or null	Yes
`tags`	array of string	Yes
`assigneeId`	string (uuid) or null	Yes
`queueId`	string (uuid) or null	Yes
`contactId`	string (uuid)	Yes
`version`	integer	Yes
`slaPolicyId`	string (uuid) or null	Yes
`firstResponseDueAt`	string (date-time) or null	Yes
`nextResponseDueAt`	string (date-time) or null	Yes
`resolutionDueAt`	string (date-time) or null	Yes
`firstRepliedAt`	string (date-time) or null	Yes
`openedAt`	string (date-time) or null	Yes
`closedAt`	string (date-time) or null	Yes
`mergedInto`	string (uuid) or null	Yes
`lastActivityAt`	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/tickets' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "conversationId": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e"
}'

GET `/api/v1/tickets/{id}`

One ticket.

Scope: tickets:read
Operation id: getTicket

Parameters

Parameters of GET /api/v1/tickets/{id}
Name	In	Type	Required	Constraints
`id`	path	string (uuid)	Yes

Response

200 JSON with these fields.

Response fields of GET /api/v1/tickets/{id}
Field	Type	Required	Constraints
`id`	string (uuid)	Yes
`caseNumber`	integer	Yes
`reference`	string	Yes
`subject`	string or null	Yes
`status`	string	Yes
`priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`caseType`	string or null	Yes
`fields`	object	Yes	free-form object
`disposition`	string or null	Yes
`tags`	array of string	Yes
`assigneeId`	string (uuid) or null	Yes
`queueId`	string (uuid) or null	Yes
`contactId`	string (uuid)	Yes
`version`	integer	Yes
`slaPolicyId`	string (uuid) or null	Yes
`firstResponseDueAt`	string (date-time) or null	Yes
`nextResponseDueAt`	string (date-time) or null	Yes
`resolutionDueAt`	string (date-time) or null	Yes
`firstRepliedAt`	string (date-time) or null	Yes
`openedAt`	string (date-time) or null	Yes
`closedAt`	string (date-time) or null	Yes
`mergedInto`	string (uuid) or null	Yes
`lastActivityAt`	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/tickets/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
  -H "Authorization: Bearer $CC_TOKEN"

PATCH `/api/v1/tickets/{id}`

Change a ticket. Send the version you read: a stale version is refused with 409 version_conflict.

Scope: tickets:write
Operation id: updateTicket
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of PATCH /api/v1/tickets/{id}
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).

Request body of PATCH /api/v1/tickets/{id}
Field	Type	Required	Constraints
`version`	integer	Yes	at least 0
`status`	string	No	one of "open", "pending", "resolved"
`priority`	string	No	one of "urgent", "high", "normal", "low", "lowest"
`subject`	string	No	1-500 characters
`caseType`	string or null	No	1-100 characters
`assigneeId`	string (uuid) or null	No
`tags`	array of string	No	at most 50 items
`addTags`	array of string	No	at most 50 items
`removeTags`	array of string	No	at most 50 items
`fields`	object	No	free-form object
`disposition`	string	No	1-100 characters

Response

200 JSON with these fields.

Response fields of PATCH /api/v1/tickets/{id}
Field	Type	Required	Constraints
`id`	string (uuid)	Yes
`caseNumber`	integer	Yes
`reference`	string	Yes
`subject`	string or null	Yes
`status`	string	Yes
`priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`caseType`	string or null	Yes
`fields`	object	Yes	free-form object
`disposition`	string or null	Yes
`tags`	array of string	Yes
`assigneeId`	string (uuid) or null	Yes
`queueId`	string (uuid) or null	Yes
`contactId`	string (uuid)	Yes
`version`	integer	Yes
`slaPolicyId`	string (uuid) or null	Yes
`firstResponseDueAt`	string (date-time) or null	Yes
`nextResponseDueAt`	string (date-time) or null	Yes
`resolutionDueAt`	string (date-time) or null	Yes
`firstRepliedAt`	string (date-time) or null	Yes
`openedAt`	string (date-time) or null	Yes
`closedAt`	string (date-time) or null	Yes
`mergedInto`	string (uuid) or null	Yes
`lastActivityAt`	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/tickets/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 0
}'

POST `/api/v1/tickets/{id}/merge`

Merge this ticket into another of the same contact.

Scope: tickets:write
Operation id: mergeTicket
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of POST /api/v1/tickets/{id}/merge
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).

Request body of POST /api/v1/tickets/{id}/merge
Field	Type	Required	Constraints
`into`	string (uuid)	Yes

Response

200 JSON with these fields.

Response fields of POST /api/v1/tickets/{id}/merge
Field	Type	Required	Constraints
`source`	object	Yes
`source.id`	string (uuid)	Yes
`source.caseNumber`	integer	Yes
`source.reference`	string	Yes
`source.subject`	string or null	Yes
`source.status`	string	Yes
`source.priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`source.caseType`	string or null	Yes
`source.fields`	object	Yes	free-form object
`source.disposition`	string or null	Yes
`source.tags`	array of string	Yes
`source.assigneeId`	string (uuid) or null	Yes
`source.queueId`	string (uuid) or null	Yes
`source.contactId`	string (uuid)	Yes
`source.version`	integer	Yes
`source.slaPolicyId`	string (uuid) or null	Yes
`source.firstResponseDueAt`	string (date-time) or null	Yes
`source.nextResponseDueAt`	string (date-time) or null	Yes
`source.resolutionDueAt`	string (date-time) or null	Yes
`source.firstRepliedAt`	string (date-time) or null	Yes
`source.openedAt`	string (date-time) or null	Yes
`source.closedAt`	string (date-time) or null	Yes
`source.mergedInto`	string (uuid) or null	Yes
`source.lastActivityAt`	string (date-time)	Yes
`target`	object	Yes
`target.id`	string (uuid)	Yes
`target.caseNumber`	integer	Yes
`target.reference`	string	Yes
`target.subject`	string or null	Yes
`target.status`	string	Yes
`target.priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`target.caseType`	string or null	Yes
`target.fields`	object	Yes	free-form object
`target.disposition`	string or null	Yes
`target.tags`	array of string	Yes
`target.assigneeId`	string (uuid) or null	Yes
`target.queueId`	string (uuid) or null	Yes
`target.contactId`	string (uuid)	Yes
`target.version`	integer	Yes
`target.slaPolicyId`	string (uuid) or null	Yes
`target.firstResponseDueAt`	string (date-time) or null	Yes
`target.nextResponseDueAt`	string (date-time) or null	Yes
`target.resolutionDueAt`	string (date-time) or null	Yes
`target.firstRepliedAt`	string (date-time) or null	Yes
`target.openedAt`	string (date-time) or null	Yes
`target.closedAt`	string (date-time) or null	Yes
`target.mergedInto`	string (uuid) or null	Yes
`target.lastActivityAt`	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/tickets/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e/merge' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "into": "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e"
}'

POST `/api/v1/tickets/{id}/split`

Move threads off this ticket into a new one.

Scope: tickets:write
Operation id: splitTicket
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of POST /api/v1/tickets/{id}/split
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).

Request body of POST /api/v1/tickets/{id}/split
Field	Type	Required	Constraints
`interactionIds`	array of string (uuid)	Yes	at least 1 items at most 100 items
`subject`	string	No	1-500 characters

Response

201 JSON with these fields.

Response fields of POST /api/v1/tickets/{id}/split
Field	Type	Required	Constraints
`source`	object	Yes
`source.id`	string (uuid)	Yes
`source.caseNumber`	integer	Yes
`source.reference`	string	Yes
`source.subject`	string or null	Yes
`source.status`	string	Yes
`source.priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`source.caseType`	string or null	Yes
`source.fields`	object	Yes	free-form object
`source.disposition`	string or null	Yes
`source.tags`	array of string	Yes
`source.assigneeId`	string (uuid) or null	Yes
`source.queueId`	string (uuid) or null	Yes
`source.contactId`	string (uuid)	Yes
`source.version`	integer	Yes
`source.slaPolicyId`	string (uuid) or null	Yes
`source.firstResponseDueAt`	string (date-time) or null	Yes
`source.nextResponseDueAt`	string (date-time) or null	Yes
`source.resolutionDueAt`	string (date-time) or null	Yes
`source.firstRepliedAt`	string (date-time) or null	Yes
`source.openedAt`	string (date-time) or null	Yes
`source.closedAt`	string (date-time) or null	Yes
`source.mergedInto`	string (uuid) or null	Yes
`source.lastActivityAt`	string (date-time)	Yes
`ticket`	object	Yes
`ticket.id`	string (uuid)	Yes
`ticket.caseNumber`	integer	Yes
`ticket.reference`	string	Yes
`ticket.subject`	string or null	Yes
`ticket.status`	string	Yes
`ticket.priority`	string	Yes	one of "urgent", "high", "normal", "low", "lowest"
`ticket.caseType`	string or null	Yes
`ticket.fields`	object	Yes	free-form object
`ticket.disposition`	string or null	Yes
`ticket.tags`	array of string	Yes
`ticket.assigneeId`	string (uuid) or null	Yes
`ticket.queueId`	string (uuid) or null	Yes
`ticket.contactId`	string (uuid)	Yes
`ticket.version`	integer	Yes
`ticket.slaPolicyId`	string (uuid) or null	Yes
`ticket.firstResponseDueAt`	string (date-time) or null	Yes
`ticket.nextResponseDueAt`	string (date-time) or null	Yes
`ticket.resolutionDueAt`	string (date-time) or null	Yes
`ticket.firstRepliedAt`	string (date-time) or null	Yes
`ticket.openedAt`	string (date-time) or null	Yes
`ticket.closedAt`	string (date-time) or null	Yes
`ticket.mergedInto`	string (uuid) or null	Yes
`ticket.lastActivityAt`	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/tickets/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e/split' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "interactionIds": [
    "0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e"
  ]
}'

Tickets

GET /api/v1/tickets

Parameters

Response

Errors

Example request

POST /api/v1/tickets

Parameters

Request body

Response

Errors

Example request

GET /api/v1/tickets/{id}

Parameters

Response

Errors

Example request

PATCH /api/v1/tickets/{id}

Parameters

Request body

Response

Errors

Example request

POST /api/v1/tickets/{id}/merge

Parameters

Request body

Response

Errors

Example request

POST /api/v1/tickets/{id}/split

Parameters

Request body

Response

Errors

Example request

GET `/api/v1/tickets`

POST `/api/v1/tickets`

GET `/api/v1/tickets/{id}`

PATCH `/api/v1/tickets/{id}`

POST `/api/v1/tickets/{id}/merge`

POST `/api/v1/tickets/{id}/split`