API reference

A single REST API for KYC, KYB and AML verification. Authenticate with a project API key as a bearer token (or the x-api-key header). Base path /api/v1.

Quickstart (TypeScript SDK)

import { MudbaseIdentity } from "@mudbase/identity";

const mi = new MudbaseIdentity({ apiKey: process.env.MUDBASE_IDENTITY_KEY! });

// Create a session and redirect the user to the hosted flow
const session = await mi.sessions.create({ workflowId });
redirect(session.url);

// Read the authoritative decision (or handle it from a signed webhook)
const decision = await mi.sessions.getDecision(session.sessionId);

The full machine-readable spec is at /api/openapi.

Endpoints

POST/api/v1/sessionsscope: sessions:write

Create a verification session

Starts a verification and returns a first-party link (`url`) that redirects the end user to the hosted flow for 30 minutes. Provider faults use the statuses below; retry guidance is in the Errors and retries section of the API reference.

GET/api/v1/sessionsscope: sessions:read

List verification sessions

Returns cached sessions for the key's project, newest first.

GET/api/v1/sessions/{sessionId}scope: decisions:read

Get a session decision

Returns the authoritative decision (status, modules, extracted results) for a session the key owns.

Errors and retries

When the verification service cannot complete a request, the API answers with one of the statuses below and a fixed message. Provider detail is never returned. Provider-fault responses carry a requestId field, also sent as the X-Request-Id header. Quote it when you contact support.

Status	Meaning	Retry
400	The request body failed validation.	No. Fix the request.
401, 403	The API key is missing, invalid, or lacks the scope.	No. Fix the key or its scopes.
404	The workflow is unknown to the verification service or not published.	No. Publish the workflow, then use its id.
422	The verification service rejected the request as invalid.	No. Change the request first.
429	Too many requests, from this API or from the verification service.	Yes. Wait for `Retry-After`, then back off exponentially.
502	The verification service failed or could not be reached.	Only if a duplicate is acceptable. Sessions have no Idempotency-Key support, so a failed create can leave a provider session that is not listed here, and a retry can create a second one. Reads (GET) are safe to retry with backoff.
503	Verification is not configured for this project.	No, until it is configured.

Webhooks

Subscribe an endpoint in the console to receive events when a verification changes. Verify the X-Signature-V2 HMAC over the raw body, enforce the timestamp window, and process event_id idempotently. The SDK ships verifyWebhook() for this.