Server-to-server API

Build on your existing platform.

Manage client references and advice sessions from your own backend. Keep your client experience and systems of record.

REST / JSONBearer API keysOpenAPI 3.1.0

This reference covers the 10 public operations in the current implementation. It is generated from the same OpenAPI contract used to generate the server interfaces.

Clients are account-scoped references, not personal profiles. Sessions belong to a client and are pinned to an approved question-set version. Store returned IDs as opaque strings.

Make your first request

  1. Arrange access. Contact Tervan through Book a Demo for account credentials and to confirm your environment. The API has no public key-provisioning endpoint.
  2. Configure your backend. The contract specifies https://api.tervan.io. Confirm availability and the appropriate environment before sending data. A separate sandbox URL is not specified.
  3. Create a client reference. Replace the credential placeholder below with your server-held key. Use a new idempotency key for each distinct request and the same key when retrying that request.
Server environment placeholders
export TERVAN_BASE_URL='https://api.tervan.io'
export TERVAN_API_KEY='YOUR_SECRET_API_KEY'
Create a client
curl --request POST "${TERVAN_BASE_URL}/v1/clients" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}" \
  --header "Idempotency-Key: REPLACE_WITH_A_UNIQUE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "external_ref": "crm-104233"
}'
201 Created · illustrative response
{
  "id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "external_ref": "crm-104233",
  "created_at": "2026-10-03T09:00:00Z"
}

The returned id is the client value when starting a session. You also need an approved question set in your account; arrange that with Tervan. Example IDs, references and timestamps throughout this page are fictional.

Authentication

Every endpoint listed here requires a secret API key in the Authorization header. Keys begin with tervan_sk_ and identify the calling account.

Required request header
Authorization: Bearer YOUR_SECRET_API_KEY

Keep credentials on your server. Do not place them in browser JavaScript, an embed, a URL, or a public repository. A missing, unknown, malformed or revoked key receives 401 with WWW-Authenticate: Bearer.

These endpoints use API keys, not an OAuth flow or a browser login session. See the security overview for key handling and account isolation.

Pagination, validation & retries

Cursor pagination

Lists are newest first. The default limit is 20, with a range of 1–100. Pass next_cursor unchanged as cursor to get the next page, keeping the same filters. A null cursor means there are no more pages. Cursors are opaque and specific to the resource you are listing.

Idempotent POST requests

All POST operations accept an optional Idempotency-Key of 1–255 characters, scoped to your account. Choose a new random value for each distinct request. Retry with the same method, path, query and exact body bytes.

A successful replay returns the original status and body with Idempotent-Replayed: true. Reusing a key for a different request returns 422. Failed responses are not stored. No expiry window for idempotency records is specified.

Request and response conventions

Send JSON request bodies with Content-Type: application/json. Unknown request fields are rejected. Timestamps use RFC 3339; responses use UTC. Clients should tolerate new response fields and enum values within v1.

API reference

Methods, paths, parameters, schemas and response codes below come directly from the public contract. All operations require bearer authentication. Schema tables include nested object fields and distinguish nullable values from optional fields.

Clients

Create a client

POST/v1/clients

Creates an account-scoped client reference. Send an empty object if you do not need an external reference.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
Idempotency-KeyOptionalheader
string

Makes the request safe to retry. Use a new random value, such as a UUID, for each distinct request. Keys are scoped to your account.

Minimum length: 1

Maximum length: 255

Request body

Required JSON object. Unknown properties are rejected.

Create a client request — required fields are required within their containing object.
FieldTypeDetails
external_refOptionalstring

Your own ID for the client, such as its ID in your CRM. Unique within your account.

Minimum length: 1

Maximum length: 255

Create a client · curl
curl --request POST "${TERVAN_BASE_URL}/v1/clients" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}" \
  --header "Idempotency-Key: REPLACE_WITH_A_UNIQUE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "external_ref": "crm-104233"
}'

Responses

StatusMeaningSchema
201The new client.Client
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
409The request conflicts with the current state, for example a reference that's already in use.Problem
422The request is well formed but can't be carried out, for example because it refers to something that doesn't exist, or reuses an idempotency key for a different request. Problem

For framework-level failures and the shared error schema, see Errors.

Create a client success response — required fields are required within their containing object.
FieldTypeDetails
idRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

external_refRequiredstring | null

Your own ID for the client, if you gave one.

created_atRequiredstring

Format: date-time

201 · illustrative response
{
  "id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "external_ref": "crm-104233",
  "created_at": "2026-10-03T09:00:00Z"
}

Clients

List clients

GET/v1/clients

Returns clients in your account, newest first. An external_ref filter returns only a matching client.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
external_refOptionalquery
string

Only the client with this reference.

Minimum length: 1

Maximum length: 255

limitOptionalquery
integer

The most items to return.

Format: int32

Default: 20

Minimum: 1

Maximum: 100

cursorOptionalquery
string

The `next_cursor` of the previous page.

Minimum length: 1

Maximum length: 255

Request body

No request body is required.

List clients · curl
curl --request GET "${TERVAN_BASE_URL}/v1/clients?limit=20" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}"

Responses

StatusMeaningSchema
200A page of clients.ClientList
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem

For framework-level failures and the shared error schema, see Errors.

List clients success response — required fields are required within their containing object.
FieldTypeDetails
dataRequiredarray
data[].idRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

data[].external_refRequiredstring | null

Your own ID for the client, if you gave one.

data[].created_atRequiredstring

Format: date-time

next_cursorRequiredstring | null

Pass as `cursor` to get the next page. `null` on the last page.

200 · illustrative response
{
  "data": [
    {
      "id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
      "external_ref": "crm-104233",
      "created_at": "2026-10-03T09:00:00Z"
    }
  ],
  "next_cursor": null
}

Clients

Get a client

GET/v1/clients/{client_id}

Retrieves a client in your account. An unknown ID, or an ID from another account, returns 404.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
client_idRequiredpath
string

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

Request body

No request body is required.

Get a client · curl
curl --request GET "${TERVAN_BASE_URL}/v1/clients/c_01j9zq3k8m2v7a5x6y4w3t2s1r" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}"

Responses

StatusMeaningSchema
200The client.Client
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
404Nothing with this ID exists in your account.Problem

For framework-level failures and the shared error schema, see Errors.

Get a client success response — required fields are required within their containing object.
FieldTypeDetails
idRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

external_refRequiredstring | null

Your own ID for the client, if you gave one.

created_atRequiredstring

Format: date-time

200 · illustrative response
{
  "id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "external_ref": "crm-104233",
  "created_at": "2026-10-03T09:00:00Z"
}

Sessions

Start an advice session

POST/v1/sessions

Starts an open session for a client on an approved question-set version. Name the version exactly, as in `suitability-retail@4.2`, or give only the question set's key to use its latest approved version. The response shows the version the session is pinned to. The client and approved question-set version must already exist in your account. There is no public endpoint for publishing question sets.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
Idempotency-KeyOptionalheader
string

Makes the request safe to retry. Use a new random value, such as a UUID, for each distinct request. Keys are scoped to your account.

Minimum length: 1

Maximum length: 255

Request body

Required JSON object. Unknown properties are rejected.

Start an advice session request — required fields are required within their containing object.
FieldTypeDetails
clientRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

question_setRequiredstring

The question set's key, such as `suitability-retail`, for its latest approved version, or a key and version, such as `suitability-retail@4.2`, for that exact version.

Pattern: ^[a-z0-9]+(-[a-z0-9]+)*(@(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8}))?$

purposeRequiredstring

Why the session was started. - `onboarding`: the first assessment, when the client relationship starts. - `periodic_review`: the periodic suitability review, usually annual.

Values: onboarding, periodic_review

previous_sessionOptionalstring

Only for a periodic review: a completed session belonging to this same client. A missing session, another client's session, an incomplete session or use with onboarding returns 422.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

localeRequiredstring

The language the questions are shown in. One of the locales the question-set version is written in.

Pattern: ^[a-z]{2}-[A-Z]{2}$

expires_atOptionalstring

When the session expires if it hasn't been completed. It takes no answers after that. In the future; 30 days from now by default.

Format: date-time

Start an advice session · curl
curl --request POST "${TERVAN_BASE_URL}/v1/sessions" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}" \
  --header "Idempotency-Key: REPLACE_WITH_A_UNIQUE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "client": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "question_set": "suitability-retail@4.2",
  "purpose": "onboarding",
  "locale": "nb-NO"
}'

Responses

StatusMeaningSchema
201The new session.Session
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
422The request is well formed but can't be carried out, for example because it refers to something that doesn't exist, or reuses an idempotency key for a different request. Problem

For framework-level failures and the shared error schema, see Errors.

Start an advice session success response — required fields are required within their containing object.
FieldTypeDetails
idRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

clientRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

question_setRequiredstring

The question-set version the session is pinned to, as key@major.minor.

purposeRequiredstring

Why the session was started. - `onboarding`: the first assessment, when the client relationship starts. - `periodic_review`: the periodic suitability review, usually annual.

Values: onboarding, periodic_review

previous_sessionRequiredstring | null

For a periodic review, the session it follows on from.

localeRequiredstring
statusRequiredstring

- `open`: taking answers. - `completed`: finished. Its answers are locked: their count and hash are recorded, and nothing can be added. - `cancelled`: stopped before it was completed. - `expired`: not completed before `expires_at`. A session takes no more answers once `expires_at` has passed, and is marked expired within about a minute.

Values: open, completed, cancelled, expired

created_atRequiredstring

Format: date-time

expires_atRequiredstring

Format: date-time

completed_atRequiredstring | null

Format: date-time

answer_countRequiredinteger | null

Once completed, how many answers the session holds, corrections included.

Format: int32

answers_hashRequiredstring | null

Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint.

retain_untilRequiredstring | null

Once the session is completed, cancelled or expired, the earliest time its record may be deleted. It can be extended, never shortened.

Format: date-time

outcomeRequiredobject | null

Once completed, the outcome computed from the answers, such as a risk level. The question set defines its fields. A field is `null` when it rests on a question that wasn't answered.

201 · illustrative response
{
  "id": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
  "client": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "question_set": "suitability-retail@4.2",
  "purpose": "onboarding",
  "previous_session": null,
  "locale": "nb-NO",
  "status": "open",
  "created_at": "2026-10-03T09:00:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "completed_at": null,
  "answer_count": null,
  "answers_hash": null,
  "retain_until": null,
  "outcome": null
}

Sessions

List sessions

GET/v1/sessions

Returns sessions in your account, newest first. Use client to limit the results to one client.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
clientOptionalquery
string

Only this client's sessions.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

limitOptionalquery
integer

The most items to return.

Format: int32

Default: 20

Minimum: 1

Maximum: 100

cursorOptionalquery
string

The `next_cursor` of the previous page.

Minimum length: 1

Maximum length: 255

Request body

No request body is required.

List sessions · curl
curl --request GET "${TERVAN_BASE_URL}/v1/sessions?limit=20" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}"

Responses

StatusMeaningSchema
200A page of sessions.SessionList
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem

For framework-level failures and the shared error schema, see Errors.

List sessions success response — required fields are required within their containing object.
FieldTypeDetails
dataRequiredarray
data[].idRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

data[].clientRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

data[].question_setRequiredstring

The question-set version the session is pinned to, as key@major.minor.

data[].purposeRequiredstring

Why the session was started. - `onboarding`: the first assessment, when the client relationship starts. - `periodic_review`: the periodic suitability review, usually annual.

Values: onboarding, periodic_review

data[].previous_sessionRequiredstring | null

For a periodic review, the session it follows on from.

data[].localeRequiredstring
data[].statusRequiredstring

- `open`: taking answers. - `completed`: finished. Its answers are locked: their count and hash are recorded, and nothing can be added. - `cancelled`: stopped before it was completed. - `expired`: not completed before `expires_at`. A session takes no more answers once `expires_at` has passed, and is marked expired within about a minute.

Values: open, completed, cancelled, expired

data[].created_atRequiredstring

Format: date-time

data[].expires_atRequiredstring

Format: date-time

data[].completed_atRequiredstring | null

Format: date-time

data[].answer_countRequiredinteger | null

Once completed, how many answers the session holds, corrections included.

Format: int32

data[].answers_hashRequiredstring | null

Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint.

data[].retain_untilRequiredstring | null

Once the session is completed, cancelled or expired, the earliest time its record may be deleted. It can be extended, never shortened.

Format: date-time

data[].outcomeRequiredobject | null

Once completed, the outcome computed from the answers, such as a risk level. The question set defines its fields. A field is `null` when it rests on a question that wasn't answered.

next_cursorRequiredstring | null

Pass as `cursor` to get the next page. `null` on the last page.

200 · illustrative response
{
  "data": [
    {
      "id": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
      "client": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
      "question_set": "suitability-retail@4.2",
      "purpose": "onboarding",
      "previous_session": null,
      "locale": "nb-NO",
      "status": "open",
      "created_at": "2026-10-03T09:00:00Z",
      "expires_at": "2026-11-02T09:00:00Z",
      "completed_at": null,
      "answer_count": null,
      "answers_hash": null,
      "retain_until": null,
      "outcome": null
    }
  ],
  "next_cursor": null
}

Sessions

Get a session

GET/v1/sessions/{session_id}

Retrieves a session in your account. An unknown ID, or an ID from another account, returns 404.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
session_idRequiredpath
string

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

Request body

No request body is required.

Get a session · curl
curl --request GET "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}"

Responses

StatusMeaningSchema
200The session.Session
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
404Nothing with this ID exists in your account.Problem

For framework-level failures and the shared error schema, see Errors.

Get a session success response — required fields are required within their containing object.
FieldTypeDetails
idRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

clientRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

question_setRequiredstring

The question-set version the session is pinned to, as key@major.minor.

purposeRequiredstring

Why the session was started. - `onboarding`: the first assessment, when the client relationship starts. - `periodic_review`: the periodic suitability review, usually annual.

Values: onboarding, periodic_review

previous_sessionRequiredstring | null

For a periodic review, the session it follows on from.

localeRequiredstring
statusRequiredstring

- `open`: taking answers. - `completed`: finished. Its answers are locked: their count and hash are recorded, and nothing can be added. - `cancelled`: stopped before it was completed. - `expired`: not completed before `expires_at`. A session takes no more answers once `expires_at` has passed, and is marked expired within about a minute.

Values: open, completed, cancelled, expired

created_atRequiredstring

Format: date-time

expires_atRequiredstring

Format: date-time

completed_atRequiredstring | null

Format: date-time

answer_countRequiredinteger | null

Once completed, how many answers the session holds, corrections included.

Format: int32

answers_hashRequiredstring | null

Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint.

retain_untilRequiredstring | null

Once the session is completed, cancelled or expired, the earliest time its record may be deleted. It can be extended, never shortened.

Format: date-time

outcomeRequiredobject | null

Once completed, the outcome computed from the answers, such as a risk level. The question set defines its fields. A field is `null` when it rests on a question that wasn't answered.

200 · illustrative response
{
  "id": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
  "client": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "question_set": "suitability-retail@4.2",
  "purpose": "onboarding",
  "previous_session": null,
  "locale": "nb-NO",
  "status": "open",
  "created_at": "2026-10-03T09:00:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "completed_at": null,
  "answer_count": null,
  "answers_hash": null,
  "retain_until": null,
  "outcome": null
}

Sessions

Cancel a session

POST/v1/sessions/{session_id}/cancel

Cancels an open session. It takes no more answers, and its retention period starts. Its answers are kept for the record. A session that's past its `expires_at` can't be cancelled: it has expired. A session that is no longer open, or has passed its expiry time, returns 409.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
session_idRequiredpath
string

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

Idempotency-KeyOptionalheader
string

Makes the request safe to retry. Use a new random value, such as a UUID, for each distinct request. Keys are scoped to your account.

Minimum length: 1

Maximum length: 255

Request body

No request body is required.

Cancel a session · curl
curl --request POST "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k/cancel" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}" \
  --header "Idempotency-Key: REPLACE_WITH_A_UNIQUE_KEY"

Responses

StatusMeaningSchema
200The cancelled session.Session
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
404Nothing with this ID exists in your account.Problem
409The request conflicts with the current state, for example a reference that's already in use.Problem
422The request is well formed but can't be carried out, for example because it refers to something that doesn't exist, or reuses an idempotency key for a different request. Problem

For framework-level failures and the shared error schema, see Errors.

Cancel a session success response — required fields are required within their containing object.
FieldTypeDetails
idRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

clientRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

question_setRequiredstring

The question-set version the session is pinned to, as key@major.minor.

purposeRequiredstring

Why the session was started. - `onboarding`: the first assessment, when the client relationship starts. - `periodic_review`: the periodic suitability review, usually annual.

Values: onboarding, periodic_review

previous_sessionRequiredstring | null

For a periodic review, the session it follows on from.

localeRequiredstring
statusRequiredstring

- `open`: taking answers. - `completed`: finished. Its answers are locked: their count and hash are recorded, and nothing can be added. - `cancelled`: stopped before it was completed. - `expired`: not completed before `expires_at`. A session takes no more answers once `expires_at` has passed, and is marked expired within about a minute.

Values: open, completed, cancelled, expired

created_atRequiredstring

Format: date-time

expires_atRequiredstring

Format: date-time

completed_atRequiredstring | null

Format: date-time

answer_countRequiredinteger | null

Once completed, how many answers the session holds, corrections included.

Format: int32

answers_hashRequiredstring | null

Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint.

retain_untilRequiredstring | null

Once the session is completed, cancelled or expired, the earliest time its record may be deleted. It can be extended, never shortened.

Format: date-time

outcomeRequiredobject | null

Once completed, the outcome computed from the answers, such as a risk level. The question set defines its fields. A field is `null` when it rests on a question that wasn't answered.

200 · illustrative response
{
  "id": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
  "client": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "question_set": "suitability-retail@4.2",
  "purpose": "onboarding",
  "previous_session": null,
  "locale": "nb-NO",
  "status": "cancelled",
  "created_at": "2026-10-03T09:00:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "completed_at": null,
  "answer_count": null,
  "answers_hash": null,
  "retain_until": "2033-10-03T10:00:00Z",
  "outcome": null
}

Sessions

Complete a session

POST/v1/sessions/{session_id}/complete

Computes the outcome from the answers, records it with the answers and scores it was computed from, and completes the session. Its answers are locked: their count and hash are recorded, and nothing can be added. Every shown question that needs an answer must have one. A session with unanswered questions, a session that is no longer open, or one that has passed its expiry time returns 409.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
session_idRequiredpath
string

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

Idempotency-KeyOptionalheader
string

Makes the request safe to retry. Use a new random value, such as a UUID, for each distinct request. Keys are scoped to your account.

Minimum length: 1

Maximum length: 255

Request body

No request body is required.

Complete a session · curl
curl --request POST "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k/complete" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}" \
  --header "Idempotency-Key: REPLACE_WITH_A_UNIQUE_KEY"

Responses

StatusMeaningSchema
200The completed session, with its outcome.Session
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
404Nothing with this ID exists in your account.Problem
409The request conflicts with the current state, for example a reference that's already in use.Problem
422The request is well formed but can't be carried out, for example because it refers to something that doesn't exist, or reuses an idempotency key for a different request. Problem

For framework-level failures and the shared error schema, see Errors.

Complete a session success response — required fields are required within their containing object.
FieldTypeDetails
idRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

clientRequiredstring

A client ID, starting with `c_`.

Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$

question_setRequiredstring

The question-set version the session is pinned to, as key@major.minor.

purposeRequiredstring

Why the session was started. - `onboarding`: the first assessment, when the client relationship starts. - `periodic_review`: the periodic suitability review, usually annual.

Values: onboarding, periodic_review

previous_sessionRequiredstring | null

For a periodic review, the session it follows on from.

localeRequiredstring
statusRequiredstring

- `open`: taking answers. - `completed`: finished. Its answers are locked: their count and hash are recorded, and nothing can be added. - `cancelled`: stopped before it was completed. - `expired`: not completed before `expires_at`. A session takes no more answers once `expires_at` has passed, and is marked expired within about a minute.

Values: open, completed, cancelled, expired

created_atRequiredstring

Format: date-time

expires_atRequiredstring

Format: date-time

completed_atRequiredstring | null

Format: date-time

answer_countRequiredinteger | null

Once completed, how many answers the session holds, corrections included.

Format: int32

answers_hashRequiredstring | null

Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint.

retain_untilRequiredstring | null

Once the session is completed, cancelled or expired, the earliest time its record may be deleted. It can be extended, never shortened.

Format: date-time

outcomeRequiredobject | null

Once completed, the outcome computed from the answers, such as a risk level. The question set defines its fields. A field is `null` when it rests on a question that wasn't answered.

200 · illustrative response
{
  "id": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
  "client": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
  "question_set": "suitability-retail@4.2",
  "purpose": "onboarding",
  "previous_session": null,
  "locale": "nb-NO",
  "status": "completed",
  "created_at": "2026-10-03T09:00:00Z",
  "expires_at": "2026-11-02T09:00:00Z",
  "completed_at": "2026-10-03T09:12:00Z",
  "answer_count": 7,
  "answers_hash": "93bef39411cdc8f47975275fa89394e73d13e255758e72ba0a0ffb23db48345c",
  "retain_until": "2033-10-03T09:12:00Z",
  "outcome": {
    "risk_level": 4,
    "portfolio": "balanced",
    "sustainability_preferences": true
  }
}

Questionnaire

Get a session's questions

GET/v1/sessions/{session_id}/questionnaire

Returns the questions the client sees now, in order and in the session's locale, with the current answer to each. A question can be shown or hidden by earlier answers, so fetch the questionnaire again after answering.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
session_idRequiredpath
string

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

Request body

No request body is required.

Get a session's questions · curl
curl --request GET "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k/questionnaire" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}"

Responses

StatusMeaningSchema
200The questionnaire.Questionnaire
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
404Nothing with this ID exists in your account.Problem

For framework-level failures and the shared error schema, see Errors.

Get a session's questions success response — required fields are required within their containing object.
FieldTypeDetails
sessionRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

localeRequiredstring

The locale the texts are in.

questionsRequiredarray

The questions shown now, in order.

questions[].keyRequiredstring

Identifies the question. Use it when answering.

questions[].typeRequiredstring

How the question is answered, and so what the answer is: - `single_choice`: one option's value. - `multiple_choice`: a list of option values. - `number`: a number, with at most 15 significant digits and 6 decimal places. - `yes_no`: `true` or `false`. - `text`: text.

Values: single_choice, multiple_choice, number, yes_no, text

questions[].textRequiredstring
questions[].helpRequiredstring | null

Further explanation to show with the question.

questions[].requiredRequiredboolean

Whether the session needs an answer to the question before it can be completed.

questions[].optionsRequiredarray

The options of a choice question, in order. Empty for other types.

questions[].options[].valueRequiredstring

What an answer gives to choose this option.

questions[].options[].labelRequiredstring
questions[].min_selectedRequiredinteger | null

Format: int32

questions[].max_selectedRequiredinteger | null

Format: int32

questions[].minRequirednumber | null
questions[].maxRequirednumber | null
questions[].integerRequiredboolean

Whether a number must be a whole number.

questions[].unitRequiredstring | null

The unit of a number, such as NOK.

questions[].max_lengthRequiredinteger | null

The most characters a text answer can have.

Format: int32

questions[].answerRequiredobject

The current answer, in the form its type describes, or `null` when there is none.

unansweredRequiredarray

The keys of shown questions that still need an answer.

ready_to_completeRequiredboolean

Whether the session can be completed now.

200 · illustrative response
{
  "session": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
  "locale": "en-GB",
  "questions": [
    {
      "key": "horizon",
      "type": "single_choice",
      "text": "How long do you plan to keep this money invested?",
      "help": null,
      "required": true,
      "options": [
        {
          "value": "short",
          "label": "Under 3 years"
        },
        {
          "value": "long",
          "label": "10 years or more"
        }
      ],
      "min_selected": null,
      "max_selected": null,
      "min": null,
      "max": null,
      "integer": false,
      "unit": null,
      "max_length": null,
      "answer": "long"
    }
  ],
  "unanswered": [],
  "ready_to_complete": true
}

Questionnaire

Answer questions

POST/v1/sessions/{session_id}/answers

Records answers given through your system. They are checked in order, each against the questions shown after the answers before it, and saved together or not at all. Answering a question again records a correction: the earlier answer stays on record, replaced by the new one. An answer equal to the current one changes nothing. A session that is no longer open, or has passed its expiry time, returns 409; an answer that doesn't fit its question returns 422, with a pointer to it.

Authentication: secret API key · Response: application/json

Parameters

ParameterLocation / typeDetails
session_idRequiredpath
string

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

Idempotency-KeyOptionalheader
string

Makes the request safe to retry. Use a new random value, such as a UUID, for each distinct request. Keys are scoped to your account.

Minimum length: 1

Maximum length: 255

Request body

Required JSON object. Unknown properties are rejected.

Answer questions request — required fields are required within their containing object.
FieldTypeDetails
answersRequiredarray

At least one answer, applied in order.

answers[].questionRequiredstring

The question's key.

Pattern: ^[a-z][a-z0-9_]{0,63}$

answers[].valueRequiredobject

The answer, in the form the question's type describes.

Answer questions · curl
curl --request POST "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k/answers" \
  --header "Authorization: Bearer ${TERVAN_API_KEY}" \
  --header "Idempotency-Key: REPLACE_WITH_A_UNIQUE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "answers": [
    {
      "question": "horizon",
      "value": "long"
    },
    {
      "question": "amount",
      "value": 500000
    }
  ]
}'

Responses

StatusMeaningSchema
200The questionnaire, after the answers.Questionnaire
400The request is malformed or fails validation.Problem
401The API key is missing, unknown or revoked.Problem
404Nothing with this ID exists in your account.Problem
409The request conflicts with the current state, for example a reference that's already in use.Problem
422The request is well formed but can't be carried out, for example because it refers to something that doesn't exist, or reuses an idempotency key for a different request. Problem

For framework-level failures and the shared error schema, see Errors.

Answer questions success response — required fields are required within their containing object.
FieldTypeDetails
sessionRequiredstring

A session ID, starting with `s_`.

Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$

localeRequiredstring

The locale the texts are in.

questionsRequiredarray

The questions shown now, in order.

questions[].keyRequiredstring

Identifies the question. Use it when answering.

questions[].typeRequiredstring

How the question is answered, and so what the answer is: - `single_choice`: one option's value. - `multiple_choice`: a list of option values. - `number`: a number, with at most 15 significant digits and 6 decimal places. - `yes_no`: `true` or `false`. - `text`: text.

Values: single_choice, multiple_choice, number, yes_no, text

questions[].textRequiredstring
questions[].helpRequiredstring | null

Further explanation to show with the question.

questions[].requiredRequiredboolean

Whether the session needs an answer to the question before it can be completed.

questions[].optionsRequiredarray

The options of a choice question, in order. Empty for other types.

questions[].options[].valueRequiredstring

What an answer gives to choose this option.

questions[].options[].labelRequiredstring
questions[].min_selectedRequiredinteger | null

Format: int32

questions[].max_selectedRequiredinteger | null

Format: int32

questions[].minRequirednumber | null
questions[].maxRequirednumber | null
questions[].integerRequiredboolean

Whether a number must be a whole number.

questions[].unitRequiredstring | null

The unit of a number, such as NOK.

questions[].max_lengthRequiredinteger | null

The most characters a text answer can have.

Format: int32

questions[].answerRequiredobject

The current answer, in the form its type describes, or `null` when there is none.

unansweredRequiredarray

The keys of shown questions that still need an answer.

ready_to_completeRequiredboolean

Whether the session can be completed now.

200 · illustrative response
{
  "session": "s_01j9zq4a7b6c5d4e3f2g1h0j9k",
  "locale": "en-GB",
  "questions": [
    {
      "key": "horizon",
      "type": "single_choice",
      "text": "How long do you plan to keep this money invested?",
      "help": null,
      "required": true,
      "options": [
        {
          "value": "short",
          "label": "Under 3 years"
        },
        {
          "value": "long",
          "label": "10 years or more"
        }
      ],
      "min_selected": null,
      "max_selected": null,
      "min": null,
      "max": null,
      "integer": false,
      "unit": null,
      "max_length": null,
      "answer": "long"
    }
  ],
  "unanswered": [],
  "ready_to_complete": true
}

Integration scope

The current integration is server-to-server. The interactive product demo uses fictional data and runs in the browser; it is not an installable SDK or web component.

The current public API does not provide browser session tokens, embeddable component packages, answer submission, document generation, signing, or webhook delivery. There are no webhook events, retry guarantees, or signature verification methods to integrate with in this version.

Discuss your integration requirements with Tervan before planning those parts of your workflow.

Errors

Errors use application/problem+json (RFC 9457). Branch on status and, where present, type. Treat detail as human-readable text that may change.

Problem response — required fields are required within their containing object.
FieldTypeDetails
typeOptionalstring

Identifies the kind of problem, for the few that need more than the status code, for example `https://docs.tervan.io/problems/idempotency-key-reused`. Left out when the status code says it all, which means `about:blank`.

Format: uri

titleRequiredstring

A short summary of the kind of problem.

statusRequiredinteger

Format: int32

detailOptionalstring

What went wrong with this request, for people to read.

instanceOptionalstring

The request path.

errorsOptionalarray

Each part of the request that caused the problem.

errors[].detailRequiredstring

What's wrong with it, for people to read.

errors[].pointerOptionalstring

A JSON Pointer to the field in the request body, in URI fragment form (RFC 6901).

errors[].parameterOptionalstring

The name of the query, path or header parameter.

400 · illustrative validation error
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request isn't valid. Each problem is listed in errors.",
  "instance": "/v1/clients",
  "errors": [
    {
      "detail": "Unknown field.",
      "pointer": "#/externalRef"
    }
  ]
}
StatusWhat to check
400Malformed JSON, unknown fields, invalid IDs, parameter ranges or schema validation. Inspect errors.
401 / 403Authentication or access denied. Check your server-held credential and the configured account.
404The resource does not exist in this account, or the path is unknown.
405 / 415Unsupported HTTP method or media type. Match the method and use JSON for request bodies.
409A duplicate client reference, a session that cannot be cancelled, or a concurrent state change. Read the current record before deciding to retry.
422A well-formed request with an unavailable client or question set, an invalid previous session, unsupported locale, past expiry, or a reused idempotency key.
500An unexpected server error. Retry a POST with its original idempotency key; contact Tervan if it persists.

A reused idempotency key has type https://docs.tervan.io/problems/idempotency-key-reused. This is an error identifier, not the API base URL. Body errors use pointer; path, query and header errors use parameter.