KYC API

Get the default KYC document retention policy for the current tenant. Returns the tenant-specific default if one exists, otherwise returns the platform-wide default.

Get KYC requirements for a specific role and vertical. This query returns the active KYC policy and all required checks (documents) that must be provided for verification.

Get a KYC application by ID

List KYC policies for the current tenant. Returns all policies visible to the current tenant, including tenant-specific policies and platform defaults. Supports filtering by vertical, role, active status, and text search on policy_key. Results are paginated.

Get a KYC policy by ID with its requirements. Returns the policy details including all associated requirements.

Get all versions of a KYC policy by its key. Returns the version history for a policy, ordered by version descending. This is useful for viewing policy changes and potentially rolling back.

List all KYC requirements defined by the current tenant. Tenant-scoped — no pagination yet because the catalog is small (typically <50 entries even for large tenants). Add pagination if real-world data shows otherwise.

List KYC document retention policies for the current tenant. Returns all retention policies visible to the current tenant, including tenant-specific policies and platform defaults. Policies are ordered by retention_days ascending.

List pending KYC applications (admin only) Returns applications filtered by status (default: Pending) with support for search by application ID or account ID. Results are paginated.

Get my KYC applications

Activate a KYC policy. This will set the specified policy as active and deactivate any other versions of the same policy key for the same tenant.

Create a KYC provider configuration for the current tenant. # Authorization Requires TenantAdmin or PlatformAdmin role.

Apply the persisted AI OCR fields onto a KYC application + source document. Admin-only. Returns the updated application alongside the list of fields actually written (existing non-empty values are preserved). The mutation refuses when OCR confidence is below 0.50 — admins should re-run OCR or fill manually in that case.

Approve a KYC application (admin only)

Attach (or upsert) a KYC requirement onto a policy with overrides. Calling this with an existing (policy, requirement) pair updates the junction in place rather than erroring.

Create a new KYC application. The application starts in DRAFT status, allowing documents to be uploaded. For third-party providers (e.g., Sumsub), a provider session is returned with an access token for the provider's web SDK.

Create a new KYC policy and (optionally) attach existing tenant-scoped requirements via the policy_requirement junction. If active is true and the policy key already has an active version, the existing active version will be deactivated.

Create a new tenant-scoped KYC requirement.

Create a new retention policy for the current tenant. Retention policies define how long KYC documents should be kept. If is_default is true, any existing default policy for this tenant will be unset.

Deactivate a KYC policy. This will mark the specified policy as inactive. Note: This does not delete the policy, it can be reactivated later.

Delete a KYC requirement. Returns true if the requirement was deleted, false if it didn't exist. Errors out if any taxi service class still references the requirement — the admin should detach it from those classes first.

Delete a retention policy (soft delete). This sets the policy's active status to false rather than physically deleting the record. Existing references to this policy will continue to work. Returns true if the policy was deleted, false if it was not found.

Detach a requirement from a policy. Idempotent.

Run AI OCR against one KYC document image. Admin-only. Returns the persisted OCR row. Subsequent calls overwrite the row in place — the only history lives in ai_call_log.

Reject a KYC application (admin only)

Submit a KYC application for verification. This transitions an application from DRAFT to PENDING status. Before calling this mutation, ensure all required documents have been uploaded using the uploadKycDocument mutation. This mutation will validate that: - The application is in DRAFT status - All mandatory requirements have been fulfilled with uploaded documents - The application belongs to the authenticated user After successful submission: - For third-party providers (Sumsub, Onfido): verification happens automatically and the provider will call back via webhook when complete - For manual verification: the application is queued for admin review

Update a KYC policy's fields. Only the provided fields will be updated.

Update a KYC requirement's display name.

Update an existing retention policy. Only the fields provided in the input will be updated. If is_default is set to true, any existing default policy for this tenant will be unset.

Upload a document for a KYC application in DRAFT status. This mutation attaches a document to an application. The application must be in DRAFT status. You can call this multiple times to upload different documents. After uploading all required documents, call submitKycForVerification to transition the application to PENDING status. The returned document includes an upload field that can be used to fetch the file's downloadUrl via federation with the upload service.