API reference

Cases

Applicant verification: creation, submission, sessions, links, checks, ownership graph, reports and decisions.

List cases

GET/v1/cases

Scopes: cases:read

Filters combine with AND. A cursor is bound to the filter it was issued for; another filter with that cursor is 400. Invalid filter value is 400 schema_validation_failed.

Parameters

Field	Type	Required
`cursor`query	`string`	no
`limit`query	`integer`	no
`state`queryOnly cases in this state.	`enum: created, collecting, submitted, processing, action_required, manual_review, approved, rejected, ...`	no
`applicant_type`queryOnly cases of applicants of this type.	`enum: person, company`	no
`country`queryOnly cases whose country_context.document_issuer_country or customer_jurisdiction equals this code.	`string`	no
`reference`queryOnly cases of the applicant with this external_id (exact match).	`string`	no
`created_from`queryCreated at or after this time.	`string (date-time)`	no
`created_to`queryCreated before this time.	`string (date-time)`	no

Responses

200CaseList
400
401
403
404
409
412
413
415
422
428
429
503

Create a case

POST/v1/cases

Scopes: cases:write
Required header: Idempotency-Key

Request body`CaseCreate`

Field	Type	Required
`applicant_id`	`string (uuid)`	yes
`purpose`	`string`	yes
`policy_version_id`	`string (uuid)`	yes
`country_context`	`CountryContext`	yes
`parent_case_id`	`string (uuid)`	no
`related_party_processing_context_id`Approved processing context for related person cases of this company case: purpose and region of the company case, published policy without company checks. Related cases (invitations and createRelatedPartyCase) are created in it; without it they are refused. Allowed only for a company applicant.	`string (uuid)`	no
`metadata`	`Metadata`	no
`processing_context_id`	`string (uuid)`	yes

Responses

201Case
400
401
403
404
409
412
413
415
422
428
429
503

Error codesconfiguration_error

Get a case

GET/v1/cases/{case_id}

Scopes: cases:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Responses

200Case
400
401
403
404
409
412
413
415
422
428
429
503

Submit a case

POST/v1/cases/{case_id}/submit

Scopes: cases:submit
Required header: Idempotency-Key
Required header: If-Match

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`CaseSubmit`

Field	Type	Required
`evidence_ids`	`array of string (uuid)`	yes
`consent_record_ids`	`array of string (uuid)`	yes
`graph_version`	`integer`	no
`input_manifest_sha256`	`string`	yes
`basis_record_id`	`string (uuid)`	yes

Responses

202Case
400
401
403
404
409
412
413
415
422
428
429
503

Cancel a case

POST/v1/cases/{case_id}/cancel

Scopes: cases:cancel
Required header: Idempotency-Key
Required header: If-Match

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`ReasonAction`

Field	Type	Required
`reason_code`	`string`	yes
`note`	`string`	no

Responses

200Case
400
401
403
404
409
412
413
415
422
428
429
503

List case sessions

GET/v1/cases/{case_id}/sessions

Scopes: sessions:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200SessionList
400
401
403
404
409
412
413
415
422
428
429
503

Create an applicant session

POST/v1/cases/{case_id}/sessions

Scopes: sessions:write
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`SessionCreate`

Field	Type	Required
`channel`	`enum: hosted, iframe, native_ios, native_android`	yes
`locale`	`string`	yes
`allowed_origin`	`string (uri)`	no
`return_url`	`string (uri)`	no
`broker_client_id`Tenant broker credential (BrokerBearer of kind tenant_broker with sessions:renew in the same tenant and region) bound to an iframe session at issuance; only this broker can renew the session with its refresh token. Without it the iframe session lasts until the access token expires. Not allowed for other channels.	`string (uuid)`	no

Responses

201SessionIssued
400
401
403
404
409
412
413
415
422
428
429
503

Error codesconfiguration_error

List case links

GET/v1/cases/{case_id}/hosted-links

Scopes: sessions:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200HostedLinkSummaryList
400
401
403
404
409
412
413
415
422
428
429
503

Create a verification link

POST/v1/cases/{case_id}/hosted-links

Scopes: sessions:write
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`HostedLinkCreate`

Field	Type	Required
`locale`	`string`	yes
`return_url`	`string (uri)`	no
`expires_in_seconds`	`integer`	no

Responses

201HostedLink
400
401
403
404
409
412
413
415
422
428
429
503

Error codesconfiguration_error

List case checks

GET/v1/cases/{case_id}/checks

Scopes: checks:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200CheckResultList
400
401
403
404
409
412
413
415
422
428
429
503

Authorize a file upload

POST/v1/cases/{case_id}/uploads

Scopes: evidence:write
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`UploadAuthorize`

Field	Type	Required
`kind`	`enum: document_front, document_back, passport_data_page, face_video, face_image, nfc_transcript, corporate_document, address_document, ...`	yes
`content_type`	`string`	yes
`byte_count`	`integer`	yes
`sha256`	`string`	yes
`capture_attempt_id`	`string (uuid)`	no
`document_profile_id`	`string`	no

Responses

201UploadAuthorization
400
401
403
404
409
412
413
415
422
428
429
503

Error codesconfiguration_errorcase_upload_quota_exceeded

Complete a file upload

POST/v1/cases/{case_id}/uploads/complete

Scopes: evidence:write
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`UploadComplete`

Field	Type	Required
`upload_id`	`string (uuid)`	yes
`sha256`	`string`	yes
`byte_count`	`integer`	yes

Responses

202Evidence
400
401
403
404
409
412
413
415
422
428
429
503

List case evidence

GET/v1/cases/{case_id}/evidence

Scopes: evidence:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200EvidenceList
400
401
403
404
409
412
413
415
422
428
429
503

Get the ownership graph

GET/v1/cases/{case_id}/graph

Scopes: kyb:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Responses

200Graph
400
401
403
404
409
412
413
415
422
428
429
503

Replace graph nodes

PUT/v1/cases/{case_id}/graph/nodes

Scopes: kyb:write
Required header: If-Match

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`GraphNodesUpdate`

Field	Type	Required
`nodes`	`array of EntityInput`	yes
`reason_code`	`string`	yes

Responses

200Graph
400
401
403
404
409
412
413
415
422
428
429
503

Create a relationship

POST/v1/cases/{case_id}/graph/relationships

Scopes: kyb:write
Required header: Idempotency-Key
Required header: If-Match

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`RelationshipCreate`

Field	Type	Required
`from_entity_id`	`string (uuid)`	yes
`to_entity_id`	`string (uuid)`	yes
`role`	`enum: shareholder, claimed_ubo, director, representative, trustee, settlor, protector, beneficiary, ...`	yes
`economic_share_percent`	`oneOf`	no
`voting_share_percent`	`oneOf`	no
`control_description`	`string`	no
`effective_from`	`string (date)`	no
`effective_to`	`string (date)`	no
`evidence_ids`	`array of string (uuid)`	yes
`share_class`	`string`	no
`denominator_basis`	`enum: total_issued_equity, class_issued_equity, total_voting_rights, class_voting_rights, other, unknown`	yes
`assertion_status`	`enum: claimed, unknown`	yes
`source_reference`	`string`	no
`conflicting_assertion_ids`	`array of string (uuid)`	no
`lower_share_percent`	`oneOf`	no
`upper_share_percent`	`oneOf`	no

Responses

201Relationship
400
401
403
404
409
412
413
415
422
428
429
503

Remove a relationship

DELETE/v1/cases/{case_id}/graph/relationships/{relationship_id}

Scopes: kyb:write
Required header: If-Match

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`relationship_id`path	`string (uuid)`	yes

Responses

204
400
401
403
404
409
412
413
415
422
428
429
503

List case reports

GET/v1/cases/{case_id}/reports

Scopes: reports:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200ReportList
400
401
403
404
409
412
413
415
422
428
429
503

Create a report

POST/v1/cases/{case_id}/reports

Scopes: reports:write
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`ReportCreate`

Field	Type	Required
`format`	`enum: json, pdf, both`	yes
`locale`	`string`	yes
`include_evidence_index`	`boolean`	yes

Responses

202Report
400
401
403
404
409
412
413
415
422
428
429
503

List case decisions

GET/v1/cases/{case_id}/decisions

Scopes: decisions:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200DecisionList
400
401
403
404
409
412
413
415
422
428
429
503

Issue appeal access

POST/v1/cases/{case_id}/appeal-access

Scopes: appeals:issue
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`AppealAccessCreate`

Field	Type	Required
`channel`	`enum: email, sms, copy_link`	yes
`recipient`	`string`	no
`locale`	`string`	yes
`basis_profile_id`	`string (uuid)`	yes

Responses

201AppealAccess
400
401
403
404
409
412
413
415
422
428
429
503

Register processing basis evidence

POST/v1/cases/{case_id}/processing-basis

Scopes: basis:write
Required header: Idempotency-Key

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`ExternalBasisEvidence`

Field	Type	Required
`profile_id`	`string (uuid)`	yes
`notice_id`	`string (uuid)`	yes
`notice_version`	`string`	yes
`subject_reference`	`string (uuid)`	yes
`event_at`	`string (date-time)`	yes
`evidence_ids`	`array of string (uuid)`	yes
`attestation_format`	`enum: contractual_record, signed_assertion`	yes
`attestation_sha256`	`string`	yes
`purpose`	`string`	yes
`basis_type`	`enum: customer_contract, customer_obligation`	no
`obligation_ref`	`string`	no
`obligation_data_categories`	`array of string`	no

Responses

201ConsentRecord
400
401
403
404
409
412
413
415
422
428
429
503

List related parties

GET/v1/cases/{case_id}/related-parties

Scopes: kyb:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200RelatedPartyList
400
401
403
404
409
412
413
415
422
428
429
503

Create a related party case

POST/v1/cases/{case_id}/related-parties

Scopes: kyb:write
Required header: Idempotency-Key

B2B creation of a related person case for a graph node and role required by the case KYB profile. A non-final related case of the same node and role is returned instead of a new one; a related case that ended without approval is replaced. The case must have related_party_processing_context_id.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`RelatedPartyCreate`

Field	Type	Required
`entity_id`	`string (uuid)`	yes
`role`	`enum: ubo, director, representative, controller`	yes

Responses

201RelatedParty
400
401
403
404
409
412
413
415
422
428
429
503

Search company candidates

POST/v1/cases/{case_id}/company-search

Scopes: kyb:write
Required header: Idempotency-Key

B2B registry search for a company case: the same rules as applicant capture. The server searches the registry source of the case KYB profile for the country; every candidate record is kept as case evidence (provenance source_retrieval); a name search only yields candidates.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`CompanySearch`

Field	Type	Required
`country`	`string`	yes
`name_query`	`string`	no
`registration_number`	`string`	no
`source_id`Optional. Without it the server searches the first registry source permitted by the case KYB profile for the country; a supplied source must be permitted by the profile for that country, otherwise the search answers not_supported.	`string`	no

Responses

200CompanyCandidates
400
401
403
404
409
412
413
415
422
428
429
503

Select a company candidate

POST/v1/cases/{case_id}/company-selection

Scopes: kyb:write
Required header: Idempotency-Key
Required header: If-Match

B2B selection of a registry record found by searchCaseCompanyCandidates: identity resolution with alternatives of the same search, the record enters the case input set, the previous selection leaves it. If-Match is the case ETag.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`CompanySelection`

Field	Type	Required
`candidate_id`	`string (uuid)`	yes
`candidate_evidence_id`	`string (uuid)`	yes

Responses

200CaseCompany
400
401
403
404
409
412
413
415
422
428
429
503

Get the case company

GET/v1/cases/{case_id}/company

Scopes: kyb:read

Organization of a company case with assertions, identity resolution, field decisions and mandatory conflicts. ETag is the case version.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Responses

200CaseCompany
400
401
403
404
409
412
413
415
422
428
429
503

Export the ownership graph

POST/v1/cases/{case_id}/graph/export

Scopes: kyb:read
Required header: Idempotency-Key

Export of the ownership graph with personal data masked by role; see GraphExport. The export is a read with an audit record; Idempotency-Key repeats return the same export.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`GraphExportRequest`

Field	Type	Required
`reason_code`Purpose of the export recorded in the audit trail.	`string`	yes

Responses

200GraphExport
400
401
403
404
409
412
413
415
422
428
429
503

List case notices

GET/v1/cases/{case_id}/notices

Scopes: cases:read

Notices (all versions and locales) of the basis profile and purpose of the case processing context: the notice_id and notice_version a client records with registerExternalBasisEvidence.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`locale`query	`string`	no
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200NoticeList
400
401
403
404
409
412
413
415
422
428
429
503

List outcome reports

GET/v1/cases/{case_id}/outcome-reports

Scopes: cases:read

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200CaseOutcomeReportList
400
401
403
404
409
412
413
415
422
428
429
503

Report a case outcome

POST/v1/cases/{case_id}/outcome-reports

Scopes: cases:write
Required header: Idempotency-Key

Records an outcome confirmed after the decision. The decision must belong to the case and be final; the report is immutable and audited. Decisions and reports are not changed.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes

Request body`CaseOutcomeReportCreate`

Field	Type	Required
`decision_id`	`string (uuid)`	yes
`outcome`	`enum: confirmed_fraud, confirmed_legitimate`	yes
`category`	`enum: document_forgery, impersonation, synthetic_identity, account_takeover, presentation_attack, money_mule, other`	yes
`reason_code`	`string`	yes
`confirmed_at`	`string (date-time)`	yes

Responses

201CaseOutcomeReport
400
401
403
404
409
412
413
415
422
428
429
503

List case transitions

GET/v1/cases/{case_id}/transitions

Scopes: cases:read

State transitions of the case, newest first. Reason codes and actor types only; no personal data.

Parameters

Field	Type	Required
`case_id`path	`string (uuid)`	yes
`cursor`query	`string`	no
`limit`query	`integer`	no

Responses

200CaseTransitionList
400
401
403
404
409
412
413
415
422
428
429
503

Cases

List cases

Parameters

Responses

Create a case

Request bodyCaseCreate

Responses

Get a case

Parameters

Responses

Submit a case

Parameters

Request bodyCaseSubmit

Responses

Cancel a case

Parameters

Request bodyReasonAction

Responses

List case sessions

Parameters

Responses

Create an applicant session

Parameters

Request bodySessionCreate

Responses

List case links

Parameters

Responses

Create a verification link

Parameters

Request bodyHostedLinkCreate

Responses

List case checks

Parameters

Responses

Authorize a file upload

Parameters

Request bodyUploadAuthorize

Responses

Complete a file upload

Parameters

Request bodyUploadComplete

Responses

List case evidence

Parameters

Responses

Get the ownership graph

Parameters

Responses

Replace graph nodes

Parameters

Request bodyGraphNodesUpdate

Responses

Create a relationship

Parameters

Request bodyRelationshipCreate

Responses

Remove a relationship

Parameters

Responses

List case reports

Parameters

Responses

Create a report

Parameters

Request bodyReportCreate

Responses

List case decisions

Parameters

Responses

Issue appeal access

Parameters

Request bodyAppealAccessCreate

Responses

Register processing basis evidence

Parameters

Request bodyExternalBasisEvidence

Responses

List related parties

Parameters

Request body`CaseCreate`

Request body`CaseSubmit`

Request body`ReasonAction`

Request body`SessionCreate`

Request body`HostedLinkCreate`

Request body`UploadAuthorize`

Request body`UploadComplete`

Request body`GraphNodesUpdate`

Request body`RelationshipCreate`

Request body`ReportCreate`

Request body`AppealAccessCreate`

Request body`ExternalBasisEvidence`

Request body`RelatedPartyCreate`

Request body`CompanySearch`

Request body`CompanySelection`

Request body`GraphExportRequest`

Request body`CaseOutcomeReportCreate`