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.
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
- Arrange access. Contact Tervan through Book a Demo for account credentials and to confirm your environment. The API has no public key-provisioning endpoint.
- 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. - 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.
export TERVAN_BASE_URL='https://api.tervan.io'
export TERVAN_API_KEY='YOUR_SECRET_API_KEY'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"
}'{
"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.
Authorization: Bearer YOUR_SECRET_API_KEYKeep 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
/v1/clientsCreates 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
| Parameter | Location / type | Details |
|---|---|---|
Idempotency-KeyOptional | headerstring | 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.
| Field | Type | Details |
|---|---|---|
external_refOptional | string | Your own ID for the client, such as its ID in your CRM. Unique within your account. Minimum length: 1 Maximum length: 255 |
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
| Status | Meaning | Schema |
|---|---|---|
201 | The new client. | Client |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
409 | The request conflicts with the current state, for example a reference that's already in use. | Problem |
422 | The 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.
| Field | Type | Details |
|---|---|---|
idRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
external_refRequired | string | null | Your own ID for the client, if you gave one. |
created_atRequired | string | Format: date-time |
{
"id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
"external_ref": "crm-104233",
"created_at": "2026-10-03T09:00:00Z"
}Clients
List clients
/v1/clientsReturns clients in your account, newest first. An external_ref filter returns only a matching client.
Authentication: secret API key · Response: application/json
Parameters
| Parameter | Location / type | Details |
|---|---|---|
external_refOptional | querystring | Only the client with this reference. Minimum length: 1 Maximum length: 255 |
limitOptional | queryinteger | The most items to return. Format: int32 Default: 20 Minimum: 1 Maximum: 100 |
cursorOptional | querystring | The `next_cursor` of the previous page. Minimum length: 1 Maximum length: 255 |
Request body
No request body is required.
curl --request GET "${TERVAN_BASE_URL}/v1/clients?limit=20" \
--header "Authorization: Bearer ${TERVAN_API_KEY}"Responses
| Status | Meaning | Schema |
|---|---|---|
200 | A page of clients. | ClientList |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
For framework-level failures and the shared error schema, see Errors.
| Field | Type | Details |
|---|---|---|
dataRequired | array | |
data[].idRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
data[].external_refRequired | string | null | Your own ID for the client, if you gave one. |
data[].created_atRequired | string | Format: date-time |
next_cursorRequired | string | null | Pass as `cursor` to get the next page. `null` on the last page. |
{
"data": [
{
"id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
"external_ref": "crm-104233",
"created_at": "2026-10-03T09:00:00Z"
}
],
"next_cursor": null
}Clients
Get a client
/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
| Parameter | Location / type | Details |
|---|---|---|
client_idRequired | pathstring | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
Request body
No request body is required.
curl --request GET "${TERVAN_BASE_URL}/v1/clients/c_01j9zq3k8m2v7a5x6y4w3t2s1r" \
--header "Authorization: Bearer ${TERVAN_API_KEY}"Responses
| Status | Meaning | Schema |
|---|---|---|
200 | The client. | Client |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
404 | Nothing with this ID exists in your account. | Problem |
For framework-level failures and the shared error schema, see Errors.
| Field | Type | Details |
|---|---|---|
idRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
external_refRequired | string | null | Your own ID for the client, if you gave one. |
created_atRequired | string | Format: date-time |
{
"id": "c_01j9zq3k8m2v7a5x6y4w3t2s1r",
"external_ref": "crm-104233",
"created_at": "2026-10-03T09:00:00Z"
}Sessions
Start an advice session
/v1/sessionsStarts 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
| Parameter | Location / type | Details |
|---|---|---|
Idempotency-KeyOptional | headerstring | 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.
| Field | Type | Details |
|---|---|---|
clientRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
question_setRequired | string | 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}))?$ |
purposeRequired | string | 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_sessionOptional | string | 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}$ |
localeRequired | string | 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_atOptional | string | 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 |
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
| Status | Meaning | Schema |
|---|---|---|
201 | The new session. | Session |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
422 | The 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.
| Field | Type | Details |
|---|---|---|
idRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
clientRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
question_setRequired | string | The question-set version the session is pinned to, as key@major.minor. |
purposeRequired | string | 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_sessionRequired | string | null | For a periodic review, the session it follows on from. |
localeRequired | string | |
statusRequired | string | - `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_atRequired | string | Format: date-time |
expires_atRequired | string | Format: date-time |
completed_atRequired | string | null | Format: date-time |
answer_countRequired | integer | null | Once completed, how many answers the session holds, corrections included. Format: int32 |
answers_hashRequired | string | null | Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint. |
retain_untilRequired | string | 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 |
outcomeRequired | object | 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. |
{
"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
/v1/sessionsReturns sessions in your account, newest first. Use client to limit the results to one client.
Authentication: secret API key · Response: application/json
Parameters
| Parameter | Location / type | Details |
|---|---|---|
clientOptional | querystring | Only this client's sessions. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
limitOptional | queryinteger | The most items to return. Format: int32 Default: 20 Minimum: 1 Maximum: 100 |
cursorOptional | querystring | The `next_cursor` of the previous page. Minimum length: 1 Maximum length: 255 |
Request body
No request body is required.
curl --request GET "${TERVAN_BASE_URL}/v1/sessions?limit=20" \
--header "Authorization: Bearer ${TERVAN_API_KEY}"Responses
| Status | Meaning | Schema |
|---|---|---|
200 | A page of sessions. | SessionList |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
For framework-level failures and the shared error schema, see Errors.
| Field | Type | Details |
|---|---|---|
dataRequired | array | |
data[].idRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
data[].clientRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
data[].question_setRequired | string | The question-set version the session is pinned to, as key@major.minor. |
data[].purposeRequired | string | 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_sessionRequired | string | null | For a periodic review, the session it follows on from. |
data[].localeRequired | string | |
data[].statusRequired | string | - `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_atRequired | string | Format: date-time |
data[].expires_atRequired | string | Format: date-time |
data[].completed_atRequired | string | null | Format: date-time |
data[].answer_countRequired | integer | null | Once completed, how many answers the session holds, corrections included. Format: int32 |
data[].answers_hashRequired | string | 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_untilRequired | string | 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[].outcomeRequired | object | 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_cursorRequired | string | null | Pass as `cursor` to get the next page. `null` on the last page. |
{
"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
/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
| Parameter | Location / type | Details |
|---|---|---|
session_idRequired | pathstring | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
Request body
No request body is required.
curl --request GET "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k" \
--header "Authorization: Bearer ${TERVAN_API_KEY}"Responses
| Status | Meaning | Schema |
|---|---|---|
200 | The session. | Session |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
404 | Nothing with this ID exists in your account. | Problem |
For framework-level failures and the shared error schema, see Errors.
| Field | Type | Details |
|---|---|---|
idRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
clientRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
question_setRequired | string | The question-set version the session is pinned to, as key@major.minor. |
purposeRequired | string | 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_sessionRequired | string | null | For a periodic review, the session it follows on from. |
localeRequired | string | |
statusRequired | string | - `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_atRequired | string | Format: date-time |
expires_atRequired | string | Format: date-time |
completed_atRequired | string | null | Format: date-time |
answer_countRequired | integer | null | Once completed, how many answers the session holds, corrections included. Format: int32 |
answers_hashRequired | string | null | Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint. |
retain_untilRequired | string | 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 |
outcomeRequired | object | 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. |
{
"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
/v1/sessions/{session_id}/cancelCancels 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
| Parameter | Location / type | Details |
|---|---|---|
session_idRequired | pathstring | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
Idempotency-KeyOptional | headerstring | 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.
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
| Status | Meaning | Schema |
|---|---|---|
200 | The cancelled session. | Session |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
404 | Nothing with this ID exists in your account. | Problem |
409 | The request conflicts with the current state, for example a reference that's already in use. | Problem |
422 | The 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.
| Field | Type | Details |
|---|---|---|
idRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
clientRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
question_setRequired | string | The question-set version the session is pinned to, as key@major.minor. |
purposeRequired | string | 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_sessionRequired | string | null | For a periodic review, the session it follows on from. |
localeRequired | string | |
statusRequired | string | - `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_atRequired | string | Format: date-time |
expires_atRequired | string | Format: date-time |
completed_atRequired | string | null | Format: date-time |
answer_countRequired | integer | null | Once completed, how many answers the session holds, corrections included. Format: int32 |
answers_hashRequired | string | null | Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint. |
retain_untilRequired | string | 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 |
outcomeRequired | object | 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. |
{
"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
/v1/sessions/{session_id}/completeComputes 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
| Parameter | Location / type | Details |
|---|---|---|
session_idRequired | pathstring | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
Idempotency-KeyOptional | headerstring | 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.
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
| Status | Meaning | Schema |
|---|---|---|
200 | The completed session, with its outcome. | Session |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
404 | Nothing with this ID exists in your account. | Problem |
409 | The request conflicts with the current state, for example a reference that's already in use. | Problem |
422 | The 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.
| Field | Type | Details |
|---|---|---|
idRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
clientRequired | string | A client ID, starting with `c_`. Pattern: ^c_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
question_setRequired | string | The question-set version the session is pinned to, as key@major.minor. |
purposeRequired | string | 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_sessionRequired | string | null | For a periodic review, the session it follows on from. |
localeRequired | string | |
statusRequired | string | - `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_atRequired | string | Format: date-time |
expires_atRequired | string | Format: date-time |
completed_atRequired | string | null | Format: date-time |
answer_countRequired | integer | null | Once completed, how many answers the session holds, corrections included. Format: int32 |
answers_hashRequired | string | null | Once completed, the SHA-256 of the session's answers in lowercase hex. This API does not expose an answer export endpoint. |
retain_untilRequired | string | 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 |
outcomeRequired | object | 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. |
{
"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
/v1/sessions/{session_id}/questionnaireReturns 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
| Parameter | Location / type | Details |
|---|---|---|
session_idRequired | pathstring | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
Request body
No request body is required.
curl --request GET "${TERVAN_BASE_URL}/v1/sessions/s_01j9zq4a7b6c5d4e3f2g1h0j9k/questionnaire" \
--header "Authorization: Bearer ${TERVAN_API_KEY}"Responses
| Status | Meaning | Schema |
|---|---|---|
200 | The questionnaire. | Questionnaire |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
404 | Nothing with this ID exists in your account. | Problem |
For framework-level failures and the shared error schema, see Errors.
| Field | Type | Details |
|---|---|---|
sessionRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
localeRequired | string | The locale the texts are in. |
questionsRequired | array | The questions shown now, in order. |
questions[].keyRequired | string | Identifies the question. Use it when answering. |
questions[].typeRequired | string | 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[].textRequired | string | |
questions[].helpRequired | string | null | Further explanation to show with the question. |
questions[].requiredRequired | boolean | Whether the session needs an answer to the question before it can be completed. |
questions[].optionsRequired | array | The options of a choice question, in order. Empty for other types. |
questions[].options[].valueRequired | string | What an answer gives to choose this option. |
questions[].options[].labelRequired | string | |
questions[].min_selectedRequired | integer | null | Format: int32 |
questions[].max_selectedRequired | integer | null | Format: int32 |
questions[].minRequired | number | null | |
questions[].maxRequired | number | null | |
questions[].integerRequired | boolean | Whether a number must be a whole number. |
questions[].unitRequired | string | null | The unit of a number, such as NOK. |
questions[].max_lengthRequired | integer | null | The most characters a text answer can have. Format: int32 |
questions[].answerRequired | object | The current answer, in the form its type describes, or `null` when there is none. |
unansweredRequired | array | The keys of shown questions that still need an answer. |
ready_to_completeRequired | boolean | Whether the session can be completed now. |
{
"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
/v1/sessions/{session_id}/answersRecords 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
| Parameter | Location / type | Details |
|---|---|---|
session_idRequired | pathstring | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
Idempotency-KeyOptional | headerstring | 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.
| Field | Type | Details |
|---|---|---|
answersRequired | array | At least one answer, applied in order. |
answers[].questionRequired | string | The question's key. Pattern: ^[a-z][a-z0-9_]{0,63}$ |
answers[].valueRequired | object | The answer, in the form the question's type describes. |
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
| Status | Meaning | Schema |
|---|---|---|
200 | The questionnaire, after the answers. | Questionnaire |
400 | The request is malformed or fails validation. | Problem |
401 | The API key is missing, unknown or revoked. | Problem |
404 | Nothing with this ID exists in your account. | Problem |
409 | The request conflicts with the current state, for example a reference that's already in use. | Problem |
422 | The 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.
| Field | Type | Details |
|---|---|---|
sessionRequired | string | A session ID, starting with `s_`. Pattern: ^s_[0-7][0-9a-hjkmnp-tv-z]{25}$ |
localeRequired | string | The locale the texts are in. |
questionsRequired | array | The questions shown now, in order. |
questions[].keyRequired | string | Identifies the question. Use it when answering. |
questions[].typeRequired | string | 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[].textRequired | string | |
questions[].helpRequired | string | null | Further explanation to show with the question. |
questions[].requiredRequired | boolean | Whether the session needs an answer to the question before it can be completed. |
questions[].optionsRequired | array | The options of a choice question, in order. Empty for other types. |
questions[].options[].valueRequired | string | What an answer gives to choose this option. |
questions[].options[].labelRequired | string | |
questions[].min_selectedRequired | integer | null | Format: int32 |
questions[].max_selectedRequired | integer | null | Format: int32 |
questions[].minRequired | number | null | |
questions[].maxRequired | number | null | |
questions[].integerRequired | boolean | Whether a number must be a whole number. |
questions[].unitRequired | string | null | The unit of a number, such as NOK. |
questions[].max_lengthRequired | integer | null | The most characters a text answer can have. Format: int32 |
questions[].answerRequired | object | The current answer, in the form its type describes, or `null` when there is none. |
unansweredRequired | array | The keys of shown questions that still need an answer. |
ready_to_completeRequired | boolean | Whether the session can be completed now. |
{
"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.
| Field | Type | Details |
|---|---|---|
typeOptional | string | 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 |
titleRequired | string | A short summary of the kind of problem. |
statusRequired | integer | Format: int32 |
detailOptional | string | What went wrong with this request, for people to read. |
instanceOptional | string | The request path. |
errorsOptional | array | Each part of the request that caused the problem. |
errors[].detailRequired | string | What's wrong with it, for people to read. |
errors[].pointerOptional | string | A JSON Pointer to the field in the request body, in URI fragment form (RFC 6901). |
errors[].parameterOptional | string | The name of the query, path or header parameter. |
{
"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"
}
]
}| Status | What to check |
|---|---|
| 400 | Malformed JSON, unknown fields, invalid IDs, parameter ranges or schema validation. Inspect errors. |
| 401 / 403 | Authentication or access denied. Check your server-held credential and the configured account. |
| 404 | The resource does not exist in this account, or the path is unknown. |
| 405 / 415 | Unsupported HTTP method or media type. Match the method and use JSON for request bodies. |
| 409 | A duplicate client reference, a session that cannot be cancelled, or a concurrent state change. Read the current record before deciding to retry. |
| 422 | A well-formed request with an unavailable client or question set, an invalid previous session, unsupported locale, past expiry, or a reused idempotency key. |
| 500 | An 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.