# Compliance provider API reference Source: https://docs.settlemint.com/docs/developer-guides/compliance/compliance-provider-api-reference Reference for DALP compliance-provider integration endpoints, subject mapping endpoints, webhook headers, statuses, and monitoring fields. DALP exposes tenant-scoped endpoints for [Sumsub](https://docs.sumsub.com/), [ComplyAdvantage](https://docs.complyadvantage.com/), [Elliptic](https://developers.elliptic.co/), [Jumio](https://documentation.jumio.ai/docs/developer-resources/API/), [Middesk](https://docs.middesk.com/), [Onfido](https://documentation.onfido.com/api/3.1.0/), [Persona](https://docs.withpersona.com/api-introduction), [Trulioo](https://developer.trulioo.com/), [Veriff](https://devdocs.veriff.com/apidocs/veriff-public-api-guides), and other configured compliance-provider integration setup, subject mapping, webhook intake, and monitoring history. All endpoint paths below are relative to the versioned API base path. Webhook paths are relative to the platform origin. ## Provider kinds [#provider-kinds] | Provider kind | Current use | | ----------------- | ---------------------------------------------------------------------------------------- | | `sumsub` | Identity verdicts and applicant-on-hold monitoring alerts for configured identity topics | | `sumsub-aml` | AML / watchlist monitoring alerts on existing Sumsub applicants | | `sumsub-kyt` | KYT transaction and wallet monitoring for both entity and wallet subjects | | `complyadvantage` | AML and sanctions search monitoring with categorical alert severity | | `elliptic` | Wallet monitoring alerts for wallet-monitoring topics | | `jumio` | Identity-verification verdicts for the `knowYourCustomer` topic | | `middesk` | KYB verdicts for the `knowYourCustomer` topic | | `onfido` | Workflow Studio and classic API identity-verification verdicts for `knowYourCustomer` | | `persona` | Inquiry verdicts for the `knowYourCustomer` topic | | `trulioo` | DataVerify KYC/KYB verdicts for the `knowYourCustomer` topic | | `veriff` | Hosted KYC session verdicts for the `knowYourCustomer` topic | ## Roles [#roles] Compliance-provider read and manage operations require one of these system roles on the active organisation: * `admin` * `systemManager` * `complianceManager` ## Integration statuses [#integration-statuses] | Status | Meaning | | --------- | ---------------------------------------------------------------- | | `pending` | Provisioning or trusted-issuer registration is still in progress | | `active` | The integration can receive and process provider webhooks | | `paused` | Intake is paused by an operator | | `failed` | Provisioning failed and can be retried | | `revoked` | The integration has been revoked | ## Integration endpoints [#integration-endpoints] | Method | Path | Purpose | | ------ | ----------------------------------------------------------------- | -------------------------------------------- | | GET | `/compliance/integrations` | List tenant compliance-provider integrations | | POST | `/compliance/integrations` | Create and provision an integration | | GET | `/compliance/integrations/{integrationId}` | Read one integration | | POST | `/compliance/integrations/validate-credentials` | Validate write-only provider credentials | | POST | `/compliance/integrations/{integrationId}/pause` | Pause intake | | POST | `/compliance/integrations/{integrationId}/resume` | Resume a paused integration | | POST | `/compliance/integrations/{integrationId}/retry-provisioning` | Retry idempotent provisioning | | POST | `/compliance/integrations/{integrationId}/revoke` | Revoke the integration | | PATCH | `/compliance/integrations/{integrationId}/policy` | Update the revocation severity threshold | | POST | `/compliance/integrations/{integrationId}/rotate-secret` | Stage a new webhook signing secret | | POST | `/compliance/integrations/{integrationId}/promote-secret` | Promote the pending signing secret | | POST | `/compliance/integrations/{integrationId}/cancel-secret-rotation` | Discard a pending signing secret | | GET | `/compliance/integrations/{integrationId}/health` | Read integration health | | GET | `/compliance/integrations/{integrationId}/monitoring` | List monitoring alerts | | POST | `/compliance/subjects/transactions/register` | Register a Sumsub KYT transaction | ## Create integration request [#create-integration-request] `POST /compliance/integrations` accepts: | Field | Type | Notes | | ----------------------------- | ----------------------------------- | -------------------------------------------------------------------------- | | `providerKind` | Provider kind | Selects the provider adapter | | `credentials` | object | Provider-specific write-only API credentials | | `topicName` | claim topic name | One integration maps to one claim topic | | `webhookSigningSecret` | string | Secret used to verify inbound provider webhooks | | `webhookAuthMode` | `hmac` or `basic_auth_ip_allowlist` | Defaults to `hmac` for HMAC providers; Jumio resolves to IP allowlisting | | `webhookIpAllowlist` | string array, optional | Required and non-empty when the resolved mode is `basic_auth_ip_allowlist` | | `revocationSeverityThreshold` | integer from `0` through `100` | Defaults to `80` | 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 integrations because their webhook verifiers do not consult an allowlist. Jumio always resolves to `basic_auth_ip_allowlist`, whether the request omits `webhookAuthMode` or supplies the default `hmac`. Jumio creation requires a non-empty `webhookIpAllowlist`. Sumsub credentials use: ```json { "providerKind": "sumsub", "credentials": { "appToken": "...", "secretKey": "..." } } ``` Sumsub AML credentials use: ```json { "providerKind": "sumsub-aml", "credentials": { "apiToken": "...", "secretKey": "...", "webhookSigningSecret": "...", "levelName": "aml-monitoring-level" } } ``` Sumsub KYT credentials use: ```json { "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: ```json { "providerKind": "elliptic", "credentials": { "apiKey": "...", "apiSecret": "..." } } ``` ComplyAdvantage credentials use: ```json { "providerKind": "complyadvantage", "credentials": { "apiToken": "...", "webhookSigningSecret": "..." } } ``` Jumio credentials use: ```json { "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 integration `webhookSigningSecret`; `credentials.basicAuthCredentials` is provider credential material, not the callback verifier secret. Middesk credentials use: ```json { "providerKind": "middesk", "credentials": { "apiKey": "...", "webhookSigningSecret": "..." } } ``` Onfido credentials use: ```json { "providerKind": "onfido", "credentials": { "apiToken": "...", "webhookSigningSecret": "...", "region": "eu" } } ``` Onfido regions are `us`, `eu`, and `ca`. Persona credentials use: ```json { "providerKind": "persona", "credentials": { "apiToken": "...", "webhookSigningSecret": "...", "inquiryTemplateId": "itmpl_..." } } ``` Trulioo credentials use: ```json { "providerKind": "trulioo", "credentials": { "apiKey": "...", "apiSecret": "...", "webhookSigningSecret": "..." } } ``` Veriff credentials use: ```json { "providerKind": "veriff", "credentials": { "apiKey": "...", "apiSecret": "...", "webhookSigningSecret": "..." } } ``` ## Integration response fields [#integration-response-fields] | Field | Meaning | | ----------------------------- | --------------------------------------------------- | | `id` | Integration identifier | | `providerKind` | Provider kind | | `topicName` | Configured claim topic name | | `topicId` | Claim topic ID as a digit string | | `status` | Current integration status | | `statusExplanation` | Human-readable status details | | `issuerEoaAddress` | Provider issuer EOA registered as trusted issuer | | `webhookUrlToken` | URL token used in the provider webhook URL | | `revocationSeverityThreshold` | Severity threshold for monitoring-driven revocation | | `pendingSecretExpiresAt` | Expiry for the pending webhook signing secret | | `lastActivity` | Latest verdict or alert activity | | `lastHealthCheck` | Last stored credential/secret health result | | `createdAt` / `updatedAt` | Integration timestamps | ## Subject endpoints [#subject-endpoints] | Method | Path | Provider | Purpose | | ------ | --------------------------------------- | --------------- | ------------------------------------------- | | POST | `/compliance/subjects/create-applicant` | Sumsub | Create and map a Sumsub applicant | | POST | `/compliance/subjects/create-applicant` | Jumio | Create and map a Jumio applicant | | POST | `/compliance/subjects/create-applicant` | Middesk | Create and map a Middesk business | | POST | `/compliance/subjects/create-applicant` | Onfido | Create and map an Onfido applicant | | POST | `/compliance/subjects/create-applicant` | Persona | Create and map a Persona inquiry | | POST | `/compliance/subjects/create-applicant` | Trulioo | Run DataVerify and map a Trulioo subject | | POST | `/compliance/subjects/create-applicant` | Veriff | Create and map a hosted Veriff session | | POST | `/compliance/subjects/register-wallet` | ComplyAdvantage | Register and map a monitored entity search | | POST | `/compliance/subjects/register-wallet` | Elliptic | Register and map an Elliptic wallet subject | `create-applicant` accepts: | Field | Type | Notes | | ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------- | | `integrationId` | UUID | Must identify an active Surface-A integration | | `identityAddress` | Ethereum address | DALP identity address in the active system | | `applicantHints.externalUserId` | string, optional | External subject identifier; defaults to the identity address | | `applicantHints.level` | string, optional | Provider workflow, level, or configuration selector | | `applicantHints.name` / `businessName` | string, Middesk only | Business name | | `applicantHints.tin` | string, Middesk only | Business tax identifier | | `applicantHints.addresses` | array, Middesk only | Business addresses | | `applicantHints.firstName` / `first_name` | string, Onfido only | Applicant first name | | `applicantHints.lastName` / `last_name` | string, Onfido only | Applicant last name | | `applicantHints.inquiryTemplateId` / `inquiry_template_id` | string, Persona only | Persona inquiry template override | | `applicantHints.fields` | object, Persona only | Persona inquiry fields | | `applicantHints.countryCode` | string, Trulioo only | DataVerify country code | | `applicantHints.demographics` | object, Trulioo only | DataVerify `DataFields.PersonInfo` input | | `applicantHints.person` | object, Veriff only | Hosted session person prefill | | `applicantHints.callbackUrl` | string, Veriff only | Veriff callback URL | `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 from Onfido, and pass `applicantHints.firstName` and `applicantHints.lastName`. DALP forwards optional email, phone number, redirect URLs, and locale. DALP also maps the returned Onfido applicant id when it differs from the external subject id. For Persona, pass `applicantHints.inquiryTemplateId` or configure `inquiryTemplateId` on the integration. 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. This adapter 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 either an Elliptic wallet mapping or a ComplyAdvantage entity-search mapping: | Field | Type | Notes | | ------------------------- | ---------------------- | ----------------------------------------------------------------------- | | `integrationId` | UUID | Must identify an active Surface-B integration | | `walletAddress` | Ethereum address | Elliptic only; wallet already registered to a DALP identity | | `identityAddress` | Ethereum address | ComplyAdvantage only; DALP identity to bind to the search | | `subjectHints.searchTerm` | string | ComplyAdvantage search term | | `subjectHints.clientRef` | string, optional | ComplyAdvantage client reference; defaults to `identityAddress` | | `subjectHints.entityType` | string, optional | ComplyAdvantage entity type; defaults to `person` | | `subjectHints.types` | string array, optional | ComplyAdvantage screening list types; defaults to `sanction`, `warning` | `register-wallet` returns `externalId` and the resolved `identityAddress`. ## Webhook paths [#webhook-paths] Provider dashboards send webhook events to: ```text /api/webhooks/compliance/// ``` 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 [#webhook-signatures] | Provider | Headers | Accepted digest | | --------------- | ------------------------------------------ | ---------------------------------------------------------------------- | | Sumsub | `x-payload-digest`, `x-payload-digest-alg` | `HMAC_SHA1_HEX`, `HMAC_SHA256_HEX`, or `HMAC_SHA512_HEX` over raw body | | ComplyAdvantage | `x-complyadvantage-signature` | HMAC-SHA256 hex over raw body | | Elliptic | `x-elliptic-signature` | HMAC-SHA256 hex over raw body, with optional `sha256=` prefix | | Jumio | `Authorization` | Basic Auth credentials plus configured source IP allowlist | | Middesk | `x-middesk-signature-256` | HMAC-SHA256 hex over raw body | | Onfido | `x-sha2-signature` | HMAC-SHA256 hex over raw body | | Persona | `persona-signature` | HMAC-SHA256 hex over `${timestamp}.${rawBody}` | | Trulioo | `x-trulioo-signature` | HMAC-SHA256 hex over raw body | | Veriff | `x-hmac-signature` | HMAC-SHA256 hex over raw body | 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 [#webhook-processing-outcomes] | Condition | Behaviour | | -------------------------------------------------- | ---------------------------------------------------------------- | | Signature invalid | Request is rejected | | Body exceeds 64 KiB | Request is rejected as too large | | New event is outside the five-minute replay window | Request is rejected | | Duplicate completed event | Event is treated as replayed | | Retryable claim processing failure | Request returns retry behaviour so the provider can resend | | Subject is unmapped | Event is recorded for audit, but no on-chain claim effect occurs | ## Monitoring fields [#monitoring-fields] The monitoring endpoint returns paginated rows with: | Field | Meaning | | ----------------- | ---------------------------------------------------------- | | `id` | Monitoring row ID | | `providerEventId` | Provider event identifier | | `subjectAddress` | DALP subject address when resolved | | `topicName` | Claim topic when available | | `severity` | Normalised severity from `0` through `100`, when available | | `outcome` | Processing outcome | | `rawPayload` | Original provider payload retained for audit | | `processedAt` | Processing timestamp when completed | | `createdAt` | Row creation timestamp | ## See also [#see-also] * [Onboard a compliance provider](/docs/developer-guides/compliance/onboarding-a-provider) * [Map compliance-provider subjects](/docs/developer-guides/compliance/compliance-provider-subjects) * [How compliance provider intake works](/docs/architecture/integrations/compliance-providers)