Conventions

This page describes the conventions the Core API follows. It is intended to help you read the OpenAPI specification and predict how the API behaves across endpoints.

Operation identifiers

Every operation in the spec carries an operationId — a unique symbolic name in camelCase (e.g. getCp, listCards, createReservation).

You can use the operationId as:

a stable anchor when linking to a specific endpoint in Swagger UI,
the method name produced by SDK generators (OpenAPI Generator, Speakeasy, Postman code-gen, …),
a precise identifier when reporting issues to support.

The format is <verb><Resource>:

Verb	Meaning
`get`	Retrieve a single resource by its identifier
`list`	Retrieve a collection (paginated or unbounded)
`create`	Create a new resource
`update`	Replace an existing resource
`patch`	Partially update an existing resource
`delete`	Remove an existing resource
`<action>`	Action-style endpoints use the action as the verb — e.g. `exportChargeLog`, `triggerRemoteStartAttempt`, `validateVat`, `changePassword`, `downloadInvoice`

A few examples mapping path → operationId:

GET /cp/{uuid} → getCp
GET /cards/{contact_uuid} → getCards
POST /charge_log_export/ → exportChargeLog
POST /remote_start_attempt/trigger → triggerRemoteStartAttempt
GET /contact_kpi/dashboard_stats/{contact_uuid} → getContactKpiDashboardStats

Path parameters

Path parameters use snake_case (e.g. {cp_uuid}, {contact_uuid}, {rate_id}). Where the resource type is unambiguous from the path, the parameter name reflects the resource type ({cp_uuid} rather than the generic {id}).

Query and body parameter casing

For historical reasons, query and body parameters in v1 use a mix of snake_case and camelCase. The exact casing of each parameter is documented per-operation in the OpenAPI spec — refer to the spec for the authoritative name.

Standard formats

Where applicable, the spec uses OpenAPI standard format keywords so that SDK generators and validators can interpret values correctly. The wire payload remains a JSON string in every case.

`format`	Used for
`uuid`	Resource identifiers shaped like `"550e8400-e29b-41d4-a716-446655440000"`
`email`	Email addresses
`uri`	URLs / hyperlinks
`date`	Calendar dates without a time component (`"2026-12-31"`)
`date-time`	ISO 8601 timestamps (`"2026-12-31T23:59:59Z"`)
`int32`,
`int64`	Numeric identifiers and counters

Where a parameter or response field has a fixed set of legal values, the spec declares an enum rather than a free-form string.

Errors

Operations declare both successful (2xx) and error (4xx / 5xx) responses. Only the codes listed below are ever returned by the v1 surface; the API does not use 401, 409, 422 or 429.

Status	Meaning
`400 Bad Request`	Malformed input or failed request-shape validation — e.g. a missing required parameter or an unparseable body.
`403 Forbidden`	Authentication or authorisation failure. The v1 surface does not distinguish `401` from `403` — a missing, invalid, or expired token returns `403` just like a token whose tenant lacks permission for the operation.
`404 Not Found`	The requested resource does not exist or is not visible to the authenticated tenant.
`405` (repurposed)	Business-rule violation, not the standard “Method Not Allowed”. Used for duplicates, password mismatches, invalid IBAN/BIC, unsupported parameter combinations and similar semantic rejections. Read the `message` field for the specific cause.
`406 Not Acceptable`	The negotiated response format is not supported for this operation.
`500 Server Error`	An unexpected server-side error occurred — safe to retry with exponential back-off.

Deprecation

Endpoints scheduled for removal carry deprecated: true in the spec. The endpoint’s description explains the replacement and, when one has been agreed, the sunset date. Deprecated endpoints continue to function until the sunset date.