# Map provider subjects Source: https://docs.settlemint.com/docs/developers/compliance/compliance-provider-subjects Developer guide for creating DALP subject mappings with provider IDs so compliance-provider webhooks can issue or revoke claims for known identities. Subject mapping connects a provider applicant, search, wallet, or monitored transaction to a DALP identity. After you create a mapping, provider webhooks can issue or revoke claims for the correct on-chain identity. Use this guide after the provider integration exists and before webhook events arrive; you will need the provider ID and an active DALP identity for each subject. For provider setup in the Console, see [Onboard a compliance provider](/docs/developers/compliance/onboarding-a-provider). For the complete provider and field reference, see [Compliance provider API reference](/docs/developers/compliance/compliance-provider-api-reference). ## Prerequisites [#prerequisites] * API access for a user with `admin`, `systemManager`, or `complianceManager` on the active organisation. * An active compliance-provider integration for the claim topic you want the provider to affect. * The provider ID from the Console provider detail page or the provider list endpoint. * A DALP identity or wallet already registered in the system identity registry. ## Choose the subject path [#choose-the-subject-path] Pick the endpoint based on how the provider identifies the subject. | Use case | Providers | Endpoint | | ------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------- | | Hosted applicant, inquiry, session, or business verification | Sumsub, Sumsub AML, Jumio, Middesk, Onfido, Persona, Trulioo, Veriff | `POST /api/v2/compliance/subjects/create-applicant` | | Wallet or monitored entity binding | ComplyAdvantage, Elliptic, Sumsub KYT | `POST /api/v2/compliance/subjects/register-wallet` | | Individual KYT transaction registration | Sumsub KYT | `POST /api/v2/compliance/subjects/transactions/register` | `create-applicant` maps a DALP identity to a provider-hosted subject. `register-wallet` maps a wallet or monitored entity. For Sumsub KYT, register the wallet first, then register the transaction. ## Map a Sumsub applicant [#map-a-sumsub-applicant] Use this path when the provider kind is `sumsub`. The request creates a Sumsub applicant and stores the subject mapping for the DALP identity. You receive a redirect URL to send the investor to the Sumsub verification flow. ```bash curl -X POST "https://your-platform.example.com/api/v2/compliance/subjects/create-applicant" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "providerId": "11111111-1111-1111-1111-111111111111", "topicName": "knowYourCustomer", "identityAddress": "0x1111111111111111111111111111111111111111", "applicantHints": { "externalUserId": "investor-123", "level": "basic-kyc-level" } }' ``` Response: ```json { "data": { "externalId": "sumsub-external-user-id", "redirectUrl": "https://..." }, "links": { "self": "/v2/compliance/subjects/create-applicant" } } ``` DALP validates that the identity belongs to the active system's identity registry before it stores the mapping. DALP records the Sumsub external ID. When Sumsub returns a different applicant ID, DALP stores that applicant ID as an alternate mapping because Sumsub webhooks may use either identifier. ## Register an Elliptic wallet [#register-an-elliptic-wallet] Use this path when the provider kind is `elliptic`. The request registers the wallet with Elliptic and stores the wallet-to-identity mapping in DALP. ```bash curl -X POST "https://your-platform.example.com/api/v2/compliance/subjects/register-wallet" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "providerId": "22222222-2222-2222-2222-222222222222", "topicName": "antiMoneyLaundering", "walletAddress": "0x2222222222222222222222222222222222222222" }' ``` Response: ```json { "data": { "externalId": "elliptic-subject-id", "identityAddress": "0x3333333333333333333333333333333333333333" }, "links": { "self": "/v2/compliance/subjects/register-wallet" } } ``` DALP resolves the wallet's on-chain identity before writing the subject mapping. Wallets that are not registered as DALP identities are rejected. ## Register a ComplyAdvantage entity search [#register-a-complyadvantage-entity-search] Use this path when the provider kind is `complyadvantage`. The request creates a ComplyAdvantage search and enables monitoring. DALP stores the search client reference as the external subject mapping for the DALP identity. ```bash curl -X POST "https://your-platform.example.com/api/v2/compliance/subjects/register-wallet" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "providerId": "33333333-3333-3333-3333-333333333333", "topicName": "antiMoneyLaundering", "identityAddress": "0x3333333333333333333333333333333333333333", "subjectHints": { "searchTerm": "Ada Lovelace", "clientRef": "investor-123", "entityType": "person", "types": ["sanction", "warning"] } }' ``` Response: ```json { "data": { "externalId": "complyadvantage-search-id", "identityAddress": "0x3333333333333333333333333333333333333333" }, "links": { "self": "/v2/compliance/subjects/register-wallet" } } ``` ComplyAdvantage is entity-level monitoring, not wallet monitoring. The subject mapping stores the provider `client_ref` against the DALP identity and leaves `walletAddress` empty. ## Register a Sumsub KYT transaction [#register-a-sumsub-kyt-transaction] Use this path when the provider kind is `sumsub-kyt`. The request registers a transaction with Sumsub KYT. DALP stores mapping rows for the returned KYT identifiers when the transaction resolves to a known identity. ```bash curl -X POST "https://your-platform.example.com/api/v2/compliance/subjects/transactions/register" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "providerId": "44444444-4444-4444-4444-444444444444", "topicName": "transactionMonitoring", "kytDataTxnId": "transfer-2026-0001", "txn": { "applicantId": "sumsub-applicant-id", "info": { "address": "0x4444444444444444444444444444444444444444" } } }' ``` Response: ```json { "data": { "kytDataTxnId": "transfer-2026-0001", "kytTxnId": "sumsub-kyt-transaction-id", "identityAddress": "0x5555555555555555555555555555555555555555" }, "links": { "self": "/v2/compliance/subjects/transactions/register" } } ``` If `txn.info.address` is present, DALP resolves that wallet strictly against the active system's identity registry. If the wallet is unknown, DALP does not fall back to `applicantId`, so the transaction is not mapped to the wrong identity. When the request omits `txn.info.address` and includes `txn.applicantId`, DALP can reuse the existing applicant mapping created by `register-wallet`. If an identity is resolved, DALP stores mappings for both returned KYT identifiers so later Sumsub KYT webhooks can resolve the same identity. If no identity is resolved, the response omits `identityAddress` and no subject mapping is written for that transaction. ## Handle provider events after mapping [#handle-provider-events-after-mapping] After the subject is mapped, provider webhooks can affect the configured claim topic: * Sumsub approved applicant-review events issue claims. * Sumsub rejected applicant-review events revoke claims. * Sumsub applicant-on-hold events appear in monitoring history. * ComplyAdvantage search monitoring events appear in monitoring history and can revoke claims when severity meets the integration threshold. * Elliptic wallet alerts appear in monitoring history and can revoke claims when severity meets the integration threshold. Map the subject before provider webhook delivery. DALP records unmapped events for audit. No on-chain claim effect is created. DALP does not automatically replay the same delivered provider event after mapping. ## Common errors [#common-errors] Wrong provider kind: use `create-applicant` for hosted verification providers, `register-wallet` for wallet or monitored-entity providers, and `transactions/register` only for Sumsub KYT transaction screening. Inactive provider: the provider must be active before subject mapping produces claim effects. Activate the integration in the Console, then retry. If the provider status is pending, wait for the Console to confirm the integration is live before creating subject mappings. Wallet not registered: register the wallet as a DALP identity first, then call `register-wallet`. Provider credential failure: check the integration credentials and provider account status in the Console. Errors from the provider are visible in the integration event log. Duplicate or conflicting subject mapping: a provider subject can belong to only one DALP identity. Confirm the subject belongs to the correct identity before retrying. ## See also [#see-also] * [Sumsub developer documentation](https://docs.sumsub.com/) * [Elliptic developer documentation](https://developers.elliptic.co/) * [Compliance provider API reference](/docs/developers/compliance/compliance-provider-api-reference) * [Onboard a compliance provider](/docs/developers/compliance/onboarding-a-provider) * [How compliance provider intake works](/docs/architects/integrations/compliance-providers)