Compliance provider API reference

Overview

DALP exposes tenant-scoped endpoints for Sumsub, ComplyAdvantage, Elliptic, Jumio, Middesk, Onfido, Persona, Trulioo, Veriff, and configured compliance-provider setup, subject mapping, webhook intake, and monitoring history.

Compliance providers connect external verification systems to DALP claim topics, subject mappings, status records, and webhooks.

All endpoint paths below are relative to the versioned API base path. Webhook paths are relative to the platform origin.

Provider kinds

A provider can only be created or extended for the topic names listed for its provider kind. DALP rejects unsupported provider-topic pairs before provisioning.

Roles

Compliance-provider read and operational management endpoints require one of these system roles on the active organisation:

• admin
• systemManager
• complianceManager

Provisioning or changing trusted-issuer topic state requires the claim-policy permission, exposed through the claimPolicyManager role. That applies to provider creation, provider revocation, adding a topic webhook, revoking a topic webhook, and reactivating a revoked topic webhook.

Provider statuses

Webhook lifecycle actions

Each provider topic has its own webhook row. A topic webhook status controls DALP intake for that one topic. It does not change the provider-level status, pause the external provider dashboard, or update the external provider's case-management state.

Operational actions change only the selected topic webhook row. Policy actions also change the provider identity's trusted-issuer topic set.

Pause and resume are operational controls for intake. They keep the provider's OnchainID identity, signing EOA, and trusted-issuer registration unchanged. Revoke and reactivate are policy controls because they change the topics that the provider identity can attest. Reactivation preserves the existing webhook row, webhook id, and URL token. If you call Reactivate on an already active topic webhook, DALP returns the current row without changing its state. Secret rotation keeps the topic status unchanged and creates a pending secret with the requested grace window; it also requires wallet confirmation before DALP accepts the new signing material.

Provider endpoints

Create provider request

POST /compliance/providers accepts:

Use POST /compliance/providers/{providerId}/webhooks when an existing multi-topic provider needs another supported topic. The body uses the same topic fields as firstTopic, plus a webhookSigningSecret; the added topic reuses the provider identity and updates the trusted-issuer topic set for that provider.

Webhook authentication is resolved against the selected provider. Sumsub, Elliptic, ComplyAdvantage, Sumsub AML, Sumsub KYT, Middesk, Onfido, Persona, Trulioo, and Veriff use hmac. Creation rejects a non-empty webhookIpAllowlist for those providers because their webhook verifiers do not consult an allowlist. Jumio supports only basic_auth_ip_allowlist; sending the default hmac shape is rejected. Jumio creation requires a non-empty webhookIpAllowlist.

Sumsub credentials use:

{
  "providerKind": "sumsub",
  "credentials": {
    "appToken": "...",
    "secretKey": "..."
  }
}

Sumsub AML credentials use:

{
  "providerKind": "sumsub-aml",
  "credentials": {
    "apiToken": "...",
    "secretKey": "...",
    "webhookSigningSecret": "...",
    "levelName": "aml-monitoring-level"
  }
}

Sumsub KYT credentials use:

{
  "providerKind": "sumsub-kyt",
  "credentials": {
    "apiToken": "...",
    "secretKey": "...",
    "webhookSigningSecret": "...",
    "levelName": "kyt-monitoring-level"
  }
}

Sumsub KYT supports both entity and wallet subject mapping: the applicant id anchors the entity subject, while txn.info.address is treated as the tenant wallet and txn.counterparty.address as the other side of the monitored transaction.

Elliptic credentials use:

{
  "providerKind": "elliptic",
  "credentials": {
    "apiKey": "...",
    "apiSecret": "..."
  }
}

ComplyAdvantage credentials use:

{
  "providerKind": "complyadvantage",
  "credentials": {
    "apiToken": "...",
    "webhookSigningSecret": "..."
  }
}

Jumio credentials use:

{
  "providerKind": "jumio",
  "credentials": {
    "apiToken": "...",
    "apiSecret": "...",
    "region": "eu-1",
    "basicAuthCredentials": "..."
  },
  "webhookSigningSecret": "jumio-callback-basic-auth-secret",
  "webhookAuthMode": "basic_auth_ip_allowlist",
  "webhookIpAllowlist": ["203.0.113.10"]
}

Jumio regions are amer-1, eu-1, and sg-1. Jumio uses callback Basic Auth plus an IP allowlist instead of HMAC-only webhook authentication. The Basic Auth credential configured in the Jumio callback must match the provider webhookSigningSecret; credentials.basicAuthCredentials is provider credential material, not the callback verifier secret.

Middesk credentials use:

{
  "providerKind": "middesk",
  "credentials": {
    "apiKey": "...",
    "webhookSigningSecret": "..."
  }
}

Onfido credentials use:

{
  "providerKind": "onfido",
  "credentials": {
    "apiToken": "...",
    "webhookSigningSecret": "...",
    "region": "eu"
  }
}

Onfido regions are us, eu, and ca.

Persona credentials use:

{
  "providerKind": "persona",
  "credentials": {
    "apiToken": "...",
    "webhookSigningSecret": "...",
    "inquiryTemplateId": "itmpl_..."
  }
}

Trulioo credentials use:

{
  "providerKind": "trulioo",
  "credentials": {
    "apiKey": "...",
    "apiSecret": "...",
    "webhookSigningSecret": "..."
  }
}

Veriff credentials use:

{
  "providerKind": "veriff",
  "credentials": {
    "apiKey": "...",
    "apiSecret": "...",
    "webhookSigningSecret": "..."
  }
}

Provider response fields

Provider read responses return a single provider object with nested topics. Provider list responses return the same provider fields, the nested topics array, and topicsCount, activeTopicsCount, and revokedTopicsCount so dashboards can show active and audit counts separately.

Each topics row includes providerId, topicName, topicId, its own webhookUrlToken, status, revocationSeverityThreshold, notificationChannels, lastActivity, createdAt, and updatedAt. Read responses include non-revoked topics by default, including pending, active, paused, and failed topic rows. Pass includeRevoked=true when building an audit view that must include revoked topic rows.

Subject endpoints

Use the subject endpoint that matches how the provider starts verification:

• create-applicant creates or starts a provider-hosted applicant, inquiry, session, or business verification for Sumsub, Sumsub AML, Jumio, Middesk, Onfido, Persona, Trulioo, and Veriff.
• register-wallet registers an existing DALP identity or wallet with a continuous-monitoring provider for ComplyAdvantage, Elliptic, and Sumsub KYT.
• Sumsub KYT transaction monitoring uses register-wallet to bind the monitored wallet or applicant to a DALP identity, then POST /compliance/subjects/transactions/register to register each monitored transaction.

create-applicant accepts:

create-applicant returns externalId and may return redirectUrl. When applicantHints.level is omitted, DALP forwards its default level value to providers that need a selector. Use that omission only when the provider tenant has a real workflow or configuration with that exact value. The default is not a portable Jumio or Onfido workflow identifier.

For Jumio, pass applicantHints.level as the tenant's workflow definition key, such as the numeric key or label configured in Jumio. DALP uses applicantHints.externalUserId, or the identity address when omitted, as the external subject id and may return a hosted web URL as redirectUrl.

For Middesk, pass applicantHints.name or businessName, applicantHints.tin, and at least one address in applicantHints.addresses. DALP stores Middesk external_id, falling back to the external subject id supplied in the request.

For Onfido, pass applicantHints.level as the active workflow id. Also pass applicantHints.firstName and applicantHints.lastName. DALP forwards optional email, phone number, redirect URLs, and locale. If Onfido returns a different applicant id, DALP maps that id to the external subject id.

For Persona, pass applicantHints.inquiryTemplateId or configure inquiryTemplateId on the provider. DALP creates an inquiry and stores the returned Persona inquiry id as the external subject id. The response may include the hosted inquiry URL as redirectUrl.

For Trulioo, pass applicantHints.countryCode and applicantHints.demographics. DALP forwards the demographics object to DataVerify as DataFields.PersonInfo. DALP stores CustomerReferenceID as the external subject id. Trulioo does not return a hosted redirect URL.

For Veriff, pass applicantHints.person when pre-filling hosted session person data and applicantHints.callbackUrl when the session should carry an explicit Veriff callback URL. DALP stores vendorData as the external subject id and returns the hosted session URL as redirectUrl.

register-wallet accepts an Elliptic wallet mapping, a Sumsub KYT wallet mapping, or a ComplyAdvantage entity-search mapping:

register-wallet returns externalId and the resolved identityAddress. For Sumsub KYT, the returned externalId is the provider applicant id that transaction registration can later use when a transaction has no wallet address.

Webhook paths

Provider dashboards send webhook events to:

/api/webhooks/compliance/<provider>/<webhookId>/<urlToken>

Build each webhook URL from the specific topic row that should receive the provider delivery. Use topics[].providerId as <webhookId> and topics[].webhookUrlToken as <urlToken>. For the first topic those values match the provider-level webhook row; added topics have their own row identifier and token.

Current provider path segments are:

• sumsub
• sumsub-aml
• sumsub-kyt
• complyadvantage
• elliptic
• jumio
• middesk
• onfido
• persona
• trulioo
• veriff

The request body limit is 64 KiB.

Webhook signatures

If Sumsub omits x-payload-digest-alg, DALP uses HMAC_SHA256_HEX. Persona accepts space-separated signature sets during key rotation.

Trulioo DataVerify webhooks prefer the top-level TransactionId as the provider event id. Legacy deliveries without that stable id use a lower-trust composite fallback: SHA-256 over (TransactionId, RecordStatus, body_hash), where body_hash is the SHA-256 hex digest of the raw body.

ComplyAdvantage webhooks prefer the top-level id as the provider event id. Legacy deliveries without that stable id use a composite fallback: SHA-256 over (search_id, created_at).

Webhook processing outcomes

Monitoring fields

The monitoring endpoint returns paginated rows with:

See also

• Onboard a compliance provider
• Map compliance-provider subjects
• How compliance provider intake works