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.

For provider setup in the dapp, see Onboard a compliance provider.

Prerequisites

• API access for a user with admin, systemManager, or complianceManager on the active organisation.
• An active compliance-provider integration.
• The integration ID from the dapp integration detail page or the integration list endpoint.
• A DALP identity or wallet that is already registered in the active system identity registry.

Map a Sumsub applicant

Use this path when the provider integration 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 '{
    "integrationId": "11111111-1111-1111-1111-111111111111",
    "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 integration 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 '{
    "integrationId": "22222222-2222-2222-2222-222222222222",
    "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 integration 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 '{
    "integrationId": "33333333-3333-3333-3333-333333333333",
    "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 integration 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 '{
    "integrationId": "44444444-4444-4444-4444-444444444444",
    "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. create-applicant requires a Surface-A integration. register-wallet requires a Surface-B integration. transactions/register is only available for Sumsub KYT integrations.
• Inactive integration. The integration 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