Verifications

Endpointhttps://api.kontorion.eu/v1

Customer verification tracks identity checks and compliance validations performed through external verification providers. Each verification has a status lifecycle: pending → verified / failed / expired.

Use verifications for KYC/KYB compliance, age verification, or business entity validation.

List customer verifications

GET

https://api.kontorion.eu/v1

/verifications

Returns a paginated list of verifications for the org. Pass ?customer_id= to scope to one customer; omit to see every verification across the org.

List customer verifications › query Parameters

customer_id

string

Filter by customer UUID

status

string

Filter by verification status

verification_type

string

Filter by verification type

occurred_after

string

Filter by created_at >= (RFC3339)

occurred_before

string

Filter by created_at < (RFC3339)

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

List customer verifications › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List customer verifications › Responses

array | null · required

object · required

GET/verifications

curl --request GET \
  --url https://api.kontorion.eu/v1/verifications

shell

Example Responses

{
  "data": [
    {
      "actor_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "check_type": "VAT",
      "created_at": "2024-08-25T15:00:00Z",
      "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "expires_at": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "last_checked_at": "2024-08-25T15:00:00Z",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "provider": "provider",
      "provider_reference": "provider_reference",
      "reason": "reason",
      "result_payload": {},
      "status": "pending",
      "updated_at": "2024-08-25T15:00:00Z",
      "verification_type": "verification_type",
      "verified_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a customer verification

POST

https://api.kontorion.eu/v1

/verifications

Initiates a new verification for a customer by calling the verification provider and storing the result. customer_id is supplied in the request body.

Create a customer verification › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a customer verification › Request Body

check_type

string

Category of check: VAT, IDENTITY, KYC, or SANCTIONS; may be omitted.

customer_id

string · uuid

Customer to create the verification record for. Required.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

provider

string · maxLength: 255

Name of the verification provider to record. Required.

verification_type

string · maxLength: 100

Provider-specific verification subtype label. Required.

Create a customer verification › Responses

Created

object · required

POST/verifications

curl --request POST \
  --url https://api.kontorion.eu/v1/verifications \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "check_type": "check_type",
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "provider": "provider",
  "verification_type": "verification_type"
}
'

shell

Example Request Body

{
  "check_type": "check_type",
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "provider": "provider",
  "verification_type": "verification_type"
}

json

Example Responses

{
  "data": {
    "actor_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "check_type": "VAT",
    "created_at": "2024-08-25T15:00:00Z",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "last_checked_at": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "provider_reference": "provider_reference",
    "reason": "reason",
    "result_payload": {},
    "status": "pending",
    "updated_at": "2024-08-25T15:00:00Z",
    "verification_type": "verification_type",
    "verified_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a customer verification

GET

https://api.kontorion.eu/v1

/verifications/{id}

Returns a single verification check row (VAT, IDENTITY, KYC, or SANCTIONS) with its status, provider reference, timestamps, and raw provider result payload.

Get a customer verification › path Parameters

id

string · uuid · required

Verification UUID

Get a customer verification › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a customer verification › Responses

object · required

GET/verifications/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/verifications/:id

shell

Example Responses

{
  "data": {
    "actor_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "check_type": "VAT",
    "created_at": "2024-08-25T15:00:00Z",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "last_checked_at": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "provider_reference": "provider_reference",
    "reason": "reason",
    "result_payload": {},
    "status": "pending",
    "updated_at": "2024-08-25T15:00:00Z",
    "verification_type": "verification_type",
    "verified_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update verification status

PATCH

https://api.kontorion.eu/v1

/verifications/{id}/status

Admin override to transition a verification's status (e.g., approve, reject, expire).

Update verification status › path Parameters

id

string · uuid · required

Verification UUID

Update verification status › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update verification status › Request Body

status

string · enum

New verification status: one of pending, verified, expired, failed, manual, or maintenance. Required, and must be a permitted transition from the current status.

Enum values:

pending

verified

expired

failed

manual

maintenance

Update verification status › Responses

object · required

PATCH/verifications/{id}/status

curl --request PATCH \
  --url https://api.kontorion.eu/v1/verifications/:id/status \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "pending"
}
'

shell

Example Request Body

{
  "status": "pending"
}

json

Example Responses

{
  "data": {
    "actor_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "check_type": "VAT",
    "created_at": "2024-08-25T15:00:00Z",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "expires_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "last_checked_at": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "provider_reference": "provider_reference",
    "reason": "reason",
    "result_payload": {},
    "status": "pending",
    "updated_at": "2024-08-25T15:00:00Z",
    "verification_type": "verification_type",
    "verified_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Custom Fields Invoice Templates

List customer verifications

GET

https://api.kontorion.eu/v1

/verifications

Returns a paginated list of verifications for the org. Pass ?customer_id= to scope to one customer; omit to see every verification across the org.

List customer verifications › query Parameters

customer_id

string

Filter by customer UUID

status

string

Filter by verification status

verification_type

string

Filter by verification type

occurred_after

string

Filter by created_at >= (RFC3339)

occurred_before

string

Filter by created_at < (RFC3339)

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List customer verifications › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List customer verifications › Responses

array | null · required

object · required

Create a customer verification

POST

https://api.kontorion.eu/v1

/verifications

Initiates a new verification for a customer by calling the verification provider and storing the result. customer_id is supplied in the request body.

Create a customer verification › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a customer verification › Request Body

check_type

string

Category of check: VAT, IDENTITY, KYC, or SANCTIONS; may be omitted.

customer_id

string · uuid

Customer to create the verification record for. Required.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

provider

string · maxLength: 255

Name of the verification provider to record. Required.

verification_type

string · maxLength: 100

Provider-specific verification subtype label. Required.

Create a customer verification › Responses

Created

object · required

Get a customer verification

GET

https://api.kontorion.eu/v1

/verifications/{id}

Returns a single verification check row (VAT, IDENTITY, KYC, or SANCTIONS) with its status, provider reference, timestamps, and raw provider result payload.

Get a customer verification › path Parameters

id

string · uuid · required

Verification UUID

Get a customer verification › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a customer verification › Responses

object · required

Update verification status

PATCH

https://api.kontorion.eu/v1

/verifications/{id}/status

Admin override to transition a verification's status (e.g., approve, reject, expire).

Update verification status › path Parameters

id

string · uuid · required

Verification UUID

Update verification status › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update verification status › Request Body

status

string · enum

New verification status: one of pending, verified, expired, failed, manual, or maintenance. Required, and must be a permitted transition from the current status.

Enum values:

pending

verified

expired

failed

manual

maintenance

Update verification status › Responses

object · required