Request/Response Conventions

All responses from the Turris API follow a consistent structure to facilitate integration and debugging.

Top-Level Structure

Every response, successful or not, carries a requestId and a timestamp. Quote the requestId when contacting support: it is how we find your exact request in our logs. Successful payloads are wrapped in a data object. Errors are not — their fields sit at the top level.

{
  "data": { },
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "timestamp": "2023-10-16T12:34:56Z"
}

A success response carries no statusCode field. Read the status from the HTTP status line. Error responses do carry one, mirroring the HTTP status — the asymmetry is historical, and both shapes are shown below.

Date Format

All date and timestamp fields are returned in ISO 8601 format:

2025-03-17T10:15:45.000Z

This is consistent with standard MongoDB date representations.

Identifier Format

All unique identifiers (e.g., downstreamEntityId, agentId, policyId) are returned as MongoDB ObjectId strings:

5f1e88b5b8f1c8001cfb7d9a

Request Headers

Required Headers

Header	Value	Description
`Content-Type`	`application/json`	Required for POST/PUT/PATCH requests
`Authorization`	`Bearer <token>`	OAuth JWT token

Alternative Authentication

Header	Value	Description
`x-restricted-access-token`	`<token>`	Restricted access token (alternative to OAuth)

Optional Headers

Header	Value	Description
`idempotency-key`	UUID v4	For idempotent operations
`x-idempotency-key`	UUID v4	Alternative idempotency header

Success Responses

The payload is under data. What sits inside it is per endpoint; the record below is only illustrative.

{
  "data": {
    "agentId": "5f1e88b5b8f1c8001cfb7d9a",
    "firstName": "Jon",
    "lastName": "Doe"
  },
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "timestamp": "2023-10-16T12:34:56Z"
}

A paginated list puts the page envelope inside data rather than beside it, so the outer shape never changes:

{
  "data": {
    "items": [],
    "total": 137,
    "page": 1,
    "limit": 50,
    "totalPages": 3
  },
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "timestamp": "2023-10-16T12:34:56Z"
}

Every agency list is paginated. On the carrier surface only one endpoint is, policy transactions, and it keys its array on transactions rather than items. See Pagination.

Error Responses

Errors are not wrapped in data. For detail, see Error Handling.

{
  "statusCode": 400,
  "requestId": "dev-d9ff9170-cc06-4fa0-8177-8f1d34405a48",
  "errorType": "validation_error",
  "errorMessage": ["email must be an email"],
  "timestamp": "2023-10-16T12:34:56Z"
}

Two things to code against rather than guess:

errorMessage is always an array of strings, even for a single error. A validation failure returns one entry per field.
Branch on errorType, never on the message text. The messages are prose and may be reworded; the codes are a published enum, listed on every endpoint’s error schema.

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request - Invalid input
`401`	Unauthorized - Invalid or expired token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Server Error - Internal error

Start Here

API Conventions

Tools & Integrations

Support

Top-Level Structure

Date Format

Identifier Format

Request Headers

Required Headers

Alternative Authentication

Optional Headers

Success Responses

Error Responses

HTTP Status Codes

​Top-Level Structure

​Date Format

​Identifier Format

​Request Headers

​Required Headers

​Alternative Authentication

​Optional Headers

​Success Responses

​Error Responses

​HTTP Status Codes

Top-Level Structure

Date Format

Identifier Format

Request Headers

Required Headers

Alternative Authentication

Optional Headers

Success Responses

Error Responses

HTTP Status Codes