Provider API reference

Overview

DALP exposes tenant-scoped endpoints for Sumsub, ComplyAdvantage, Elliptic, Jumio, Middesk, Onfido, Persona, Trulioo, and Veriff. Use these endpoints to configure providers, map subjects, receive webhook events, and query monitoring history.

Each compliance provider connects an external verification system to DALP claim topics, status records, and webhook delivery. You call the same API surface for all supported providers; the provider kind determines which credential shape, topic names, and webhook authentication method apply.

All endpoint paths below are relative to your 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 begins. Verify that your chosen provider kind supports the topic before you call the create endpoint.

Roles

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

• admin
• systemManager
• complianceManager

To provision a provider or change trusted-issuer topic state, your account needs 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

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 changes affect only the selected topic webhook row. Policy changes also update the provider identity's trusted-issuer topic set.

Pause and resume are operational controls you use to start and stop intake. They keep the provider's OnchainID identity, signing EOA, and trusted-issuer registration unchanged. Revoke and reactivate are policy controls that change the topics the provider identity can attest.

Reactivation preserves the existing webhook row, webhook id, and URL token. Calling Reactivate on an already active topic webhook returns the current row without any state change. Secret rotation keeps the topic status unchanged and stages a pending secret with the requested grace window. The platform requires wallet confirmation before accepting the new signing material.

Provider endpoints

Create provider request

POST /compliance/providers accepts:

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

Create conflicts

A POST /compliance/providers request is rejected when an active or paused provider already serves the same provider kind and topic in the active organisation. DALP returns public error ID DALP-0501 for COMPLIANCE_INVALID_STATE_TRANSITION with HTTP 409. No second provider is created, and no credentials are stored.

A failed or pending provider does not cause a DALP-0501 create conflict. To continue an interrupted provisioning attempt, call POST /compliance/providers/{providerId}/retry-provisioning on the existing failed or pending record rather than creating a new provider.

To replace a live provider for a kind and topic, you must revoke the existing provider first, then create the new one:

1. Find the live provider with GET /compliance/providers and note its id.
2. Revoke it with POST /compliance/providers/{providerId}/revoke.
3. Submit the POST /compliance/providers create request again.

A revoked provider does not block re-creation. Re-creating a provider for the same kind and topic after revoking the previous one returns a new provider record with its own id. The platform reuses the existing on-chain issuer identity and signing address rather than provisioning new ones. The revoked record stays in place for audit. To restore the revoked record itself instead of creating a new one, reactivate it at the topic-webhook level as described in Webhook lifecycle.

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. Their verifiers do not consult an allowlist. Jumio supports only basic_auth_ip_allowlist. Sending the default hmac shape for Jumio is rejected, and creation requires a non-empty webhookIpAllowlist.

The three Sumsub provider kinds each use a distinct credential shape. The base KYC kind uses appToken and secretKey; the two monitoring kinds add webhookSigningSecret and levelName. Shapes follow in order.

Sumsub (KYC) credentials:

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

The AML and KYT kinds extend this shape with monitoring-specific fields: both replace appToken with apiToken and add webhookSigningSecret and levelName. The AML shape:

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

Sumsub KYT uses the same shape with a KYT-specific level name:

{
  "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.

The remaining monitoring providers (Elliptic and ComplyAdvantage) and identity providers (Jumio onward) use the shapes below. Elliptic and ComplyAdvantage require only API credentials. For Jumio, you also supply a region and auth fields. Elliptic credentials:

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

ComplyAdvantage adds a webhookSigningSecret to its API token credential. ComplyAdvantage credentials:

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

Jumio credentials:

{
  "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 and the remaining identity-verification providers (Onfido, Persona, Trulioo, Veriff) each require a webhookSigningSecret. Use the shapes below for the provider you are configuring. Middesk credentials:

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

Onfido credentials (regions: us, eu, ca):

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

Persona, Trulioo, and Veriff each include a webhookSigningSecret alongside their primary API credentials. Persona also requires an inquiryTemplateId. Persona credentials:

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

Trulioo and Veriff use apiKey and apiSecret in place of an apiToken, each paired with a webhookSigningSecret. Trulioo credentials, followed by Veriff credentials:

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

Veriff uses the same shape with its own API key material:

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

Provider response fields

A provider read response returns a single object with nested topics. List responses return the same fields plus 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: pending, active, paused, and failed rows. Pass includeRevoked=true for an audit view that adds revoked topic rows.

Subject endpoints

Choose the subject endpoint that matches how your provider starts the verification flow for your subjects:

• 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 matching that exact value. The default is not a portable identifier for Jumio or Onfido.

For Jumio, pass applicantHints.level as the tenant's workflow definition key (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.

Middesk requires 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 in the request.

For Onfido, pass applicantHints.level (the active workflow id), applicantHints.firstName, and applicantHints.lastName. DALP forwards optional email, phone number, redirect URLs, and locale, then maps the returned applicant id to the external subject id.

Onfido supports both knowYourCustomer and knowYourBusiness topics. Choose the correct topicName when creating the provider to match the subject type you intend to verify.

For Persona, pass applicantHints.inquiryTemplateId or configure inquiryTemplateId on the provider record. If both are present, the hint overrides the record value. DALP creates the inquiry and stores the returned inquiry id as the external subject id. The platform may return the hosted inquiry URL in redirectUrl for client-side redirect. Pass applicantHints.fields to pre-populate Persona inquiry fields.

For Veriff, pass applicantHints.person to pre-fill hosted session person data and applicantHints.callbackUrl when an explicit callback URL is needed. DALP stores vendorData as the external subject id and returns the hosted session URL in redirectUrl.

Trulioo requires applicantHints.countryCode and applicantHints.demographics. DALP forwards the demographics object to DataVerify as DataFields.PersonInfo and stores the returned CustomerReferenceID as the external subject id. Trulioo does not return a hosted redirect URL. Verification happens on the Trulioo side with no client-side redirect.

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. Additional topics each 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

DALP resolves the topic webhook before reading the request body or verifying the provider signature. Paused and failed webhooks return their public error ID without storing a provider event. The named outcome in each row is the DALP classification behind the public response your provider receives.

Use pause to stop DALP from accepting events for a topic without revoking the provider's trusted-issuer registration. If intake returns DALP-0491 for COMPLIANCE_PROVIDER_PAUSED, resume the topic webhook before asking the external provider to resend events. If intake returns DALP-0492 for COMPLIANCE_PROVIDER_FAILED, repair or reprovision the provider before retrying webhook processing.

Monitoring fields

The monitoring endpoint returns paginated rows. Each row includes:

See also

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