Docs

API Reference

Certivo exposes a versioned REST API. Requests and responses are JSON, and every request is authenticated with an organization-scoped API key.

Base URL

The REST API is versioned under the /api/v1 path of your Certivo instance. Production calls use your provisioned host; the examples below use https://api.certivo.com for illustration.

https://api.certivo.com/api/v1

In the sandbox evaluation environment, calls run against your own instance host (for a local run, http://localhost:3101). Sandbox keys are prefixed sk_sandbox_ and all verdicts are simulated.

Authentication

Create a key under Settings → API keys in the console, then pass it as a Bearer token on every request. Keys are scoped to the issuing organization, and only a hash of the key is stored — copy it when it is created. Missing, malformed or revoked keys return 401.

curl -X POST https://api.certivo.com/api/v1/verifications \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "identity", "subject": "Jane Doe" }'

Endpoints

POST/api/v1/verifications201 Created

Create and run a verification. Returns the orchestrated result synchronously.

Request body

{
  "type": "identity",          // identity | document | facematch | liveness
  "subject": "Jane Doe"        // 1–120 chars
}

Response

{
  "id": "ver_9f2c…",
  "object": "verification",
  "type": "identity",
  "subject": "Jane Doe",
  "status": "approved",        // approved | review | declined
  "score": 92,                 // 0–100
  "provider": "sandbox",
  "mode": "sandbox",
  "createdAt": "2026-07-21T10:12:04.000Z"
}

A status of review or declined automatically opens a case for human review.

GET/api/v1/verifications/:id200 OK

Retrieve a single verification, including the full provider result payload.

Response

{
  "id": "ver_9f2c…",
  "object": "verification",
  "type": "identity",
  "subject": "Jane Doe",
  "status": "approved",
  "score": 92,
  "provider": "sandbox",
  "mode": "sandbox",
  "result": { "documentAuthentic": true, "faceMatch": true },
  "createdAt": "2026-07-21T10:12:04.000Z"
}

Returns 404 with a not_found_error if no verification with that id exists in your organization.

POST/api/v1/screenings201 Created

Screen a party against AML, sanctions or PEP data.

Request body

{
  "party": "Acme Holdings Ltd", // 1–120 chars
  "kind": "sanctions"           // aml | sanctions | pep
}

Response

{
  "id": "scr_4a71…",
  "object": "screening",
  "party": "Acme Holdings Ltd",
  "kind": "sanctions",
  "status": "clear",            // clear | review | hit
  "hits": 0,
  "provider": "sandbox",
  "mode": "sandbox",
  "createdAt": "2026-07-21T10:13:41.000Z"
}

GET/api/v1/cases200 OK

List review cases for your organization, most urgent first.

Response

{
  "object": "list",
  "data": [
    {
      "id": "case_1b0e…",
      "object": "case",
      "reference": "CASE-0042",
      "subject": "Jane Doe",
      "status": "open",         // open | in_review | resolved
      "priority": "high",
      "assignee": null,
      "resolution": null,
      "verificationId": "ver_9f2c…",
      "createdAt": "2026-07-21T10:12:05.000Z"
    }
  ]
}

Optional query param `status` filters to one of open | in_review | resolved. Returns up to 100 cases per request, ordered by status then newest first.

POST/api/v1/cases/:id/resolve200 OK

Resolve an open case with a decision.

Request body

{
  "resolution": "approved",    // approved | declined | escalated
  "assignee": "reviewer@bank.com" // optional, ≤120 chars
}

Response

{
  "id": "case_1b0e…",
  "object": "case",
  "reference": "CASE-0042",
  "subject": "Jane Doe",
  "status": "resolved",
  "priority": "high",
  "assignee": "reviewer@bank.com",
  "resolution": "approved",
  "createdAt": "2026-07-21T10:12:05.000Z"
}

Returns 409 with a conflict_error if the case is already resolved.

Errors

Errors use a consistent JSON envelope so you can branch on a stable machine-readable type:

{ "error": { "type": "invalid_request_error", "message": "…" } }

Status	Type	When
400	`invalid_request_error`	The request body or query parameters failed validation.
401	`authentication_error`	The API key is missing, malformed or revoked.
404	`not_found_error`	No resource with that id exists in your organization.
409	`conflict_error`	The request conflicts with the resource's current state (e.g. resolving a resolved case).

Conventions

All timestamps are ISO 8601 in UTC.
Every resource carries an object field naming its type; list responses use { "object": "list", "data": [ … ] }.
Sandbox responses include "mode": "sandbox" and are deterministic simulations — never use them for real compliance decisions.
Requests and responses are always application/json.

Need something that isn't covered here? Contact support or request a demo.