Map provider subjects

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. For the complete provider and field reference, see Compliance provider API reference.

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

Pick the endpoint based on how the provider identifies the subject.

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

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.

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:

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

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.

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:

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

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.

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:

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

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.

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:

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

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

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

• Sumsub developer documentation
• Elliptic developer documentation
• Compliance provider API reference
• Onboard a compliance provider
• How compliance provider intake works