Skip to main content
The KYC Connector is an ingestion layer between third-party KYC providers and Uphold’s platform. Instead of manually mapping provider-specific payloads to Uphold’s KYC model, you create an ingestion and the KYC Connector handles extraction and submission on your behalf. The KYC Connector covers four processes: profile, address, identity, and proofOfAddress. Any remaining required processes (e.g. customerDueDiligence, taxDetails) must still be completed via the REST API.

​
Prerequisites

  • API client credentials with permission to create users and create ingestions.
  • Your Sumsub account must be configured for KYC data sharing. Contact your Account Manager to coordinate the setup.

​
The flow

​
Create the user

The user creation step is identical to the REST API approach: fetch the applicable Terms of Service, display them to the user, and call Create User:
GET /core/terms-of-service?type=general&country={country}
POST /core/users
The X-Uphold-User-Ip user context header is mandatory when creating a user.

​
Collect KYC data

Your existing KYC provider flow requires no changes. Once the user completes verification and the applicant is approved, generate a share token from your backend. This token authorizes Uphold to copy the applicant’s KYC data from your provider account.
After the applicant is approved in Sumsub, use the Sumsub API to generate a share token for the applicant.

​
Create an ingestion

Call Create ingestion with the share token and the list of KYC processes you want to ingest.
POST /kyc-connector/sumsub/ingestions
{
  "shareToken": "_act-sbx-jwt-eyJhbGciOiJub25lIn0.eyJqdGkiOiJ0ZXN0IiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbSJ9.",
  "processes": [
    "identity",
    "proof-of-address"
  ]
}
A successful response returns an ingestion object with details about the ingestion and its initial status:
Response
{
  "ingestion": {
    "id": "019b2184-1ca9-7dd6-b7a5-ec242def68b0",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "queued",
    "processes": [
      "identity",
      "proof-of-address"
    ],
    "provider": "sumsub",
    "parameters": {
      "shareToken": "_act-sbx-jwt-eyJhbGciOiJub25lIn0.eyJqdGkiOiJ0ZXN0IiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbSJ9."
    },
    "createdAt": "2026-01-15T14:23:01.819Z",
    "updatedAt": "2026-01-15T14:23:01.819Z"
  }
}

​
Monitor the ingestion

Prefer webhooks for real-time updates, or fall back to polling if webhooks are not feasible.
When the ingestion reaches finished, inspect the result field for each process. A completed result means the data was successfully extracted and submitted to Uphold — it does not mean the KYC process itself has been verified. Always confirm KYC process statuses using Get KYC Overview.

​
Complete onboarding process

Once the ingestion finishes, the KYC Connector has submitted only the processes it supports (profile, address, identity, proofOfAddress). Use Get KYC Overview to confirm which processes are now ok and identify what still needs to be collected.Any remaining required processes (e.g. customerDueDiligence, taxDetails) must still be completed.

Via REST API

Check required processes and prompt the user to submit any outstanding ones. Call the relevant endpoints to submit the data and update process statuses until all are ok.

Via KYC Widget

Embed the KYC Widget to let the user complete the remaining processes through a pre-built UI.

​
Check capabilities

Always check if the required capabilities for the user’s intended activities are unlocked before allowing them to transact. Call List capabilities to check restrictions and requirements for each capability.
GET /core/capabilities
The response includes the list of capabilities with any outstanding requirements or restrictions.
Response
{
  "capabilities": [
    {
      "key": "crypto-deposits",
      "enabled": true,
      "requirements": [],
      "restrictions": []
    },
    {
      "key": "crypto-withdrawals",
      "enabled": true,
      "requirements": [
        "user-must-submit-identity"
      ],
      "restrictions": []
    }
  ]
}
The user is now onboarded and ready to transact.