Map compliance-provider subjects

Subject mapping connects a provider applicant, search, wallet, or monitored transaction to a DALP identity. After 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.

For provider setup in the dapp, 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 dapp provider detail page or the provider list endpoint.
• A DALP identity or wallet that is already registered in the active system identity registry.

Choose the subject path

Pick the endpoint from the way the provider identifies the subject:

create-applicant binds an existing DALP identity to a provider-hosted verification subject. register-wallet binds an existing wallet or monitored entity to a DALP identity. Sumsub KYT uses both: bind the monitored wallet first, then register the transaction that should be screened.

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.

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 stores 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 can be used for claim effects.
• Wallet not registered. Register the wallet as a DALP identity before calling register-wallet.
• Provider credential failure. Check the integration credentials and provider account status.
• Duplicate or conflicting subject mapping. Confirm the provider subject belongs to the same DALP identity before retrying.

See also

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