Import User KYC Data

If your platform already verifies your users, share that data with Crossmint so they skip in-flow verification and are ready to cash out. This guide covers passing that data and confirming the user is verified. For how verification works in depth, see KYC & Compliance.

The user KYC API must be enabled for your project. If calls return "project not configured to support the users KYC endpoints", contact sales to enable it.

Register and verify the user

Each call uses a userId: locator, where <USER_ID> is a unique identifier you choose for the user and reuse across the calls below.

User KYC verification flow: record privacy policy, create user with KYC data, trigger verification, poll until verified

Record privacy policy acceptance

Before sharing any user KYC data with Crossmint, the user must accept Crossmint’s Privacy Policy in your app. Consent must be collected with an explicit checkbox and specific wording — see Register User Data for the exact consent-collection requirements. Only once the user has accepted, record their consent:

curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>/legal-documents' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "crossmint-privacy-policy", "acceptedAt": "2026-01-01T00:00:00.000Z" }'

Example response

{
  "acceptedAt": "2026-01-01T00:00:00.000Z"
}

Create the user with KYC data

Send the user’s details along with the KYC data you already hold.

curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userDetails": {
      "firstName": "Alice",
      "lastName": "Smith",
      "dateOfBirth": "1990-01-15",
      "countryOfResidence": "US"
    },
    "kycData": {
      "email": "alice@example.com",
      "phoneNumber": "+13055551234",
      "nationality": "US",
      "addressOfResidence": {
        "line1": "701 S Miami Ave",
        "city": "Miami",
        "postalCode": "33156",
        "stateOrRegion": "FL"
      },
      "identityDocument": {
        "type": "ssn",
        "number": "123-45-6789",
        "issuingCountryCode": "US"
      },
      "ipAddresses": ["203.0.113.1"]
    },
    "verificationHistory": {
      "idVerificationTimestamp": "2026-01-01T00:00:00.000Z",
      "livenessVerificationTimestamp": "2026-01-01T00:00:00.000Z"
    }
  }'

The booleans in the response show which sections were stored.

US residents: include kycData.phoneNumber (required), and provide identity via SSN in kycData.identityDocument (no document upload is needed for standard offramp). The dueDiligence object is not required for standard US offramp in most states — include it only where required (see Data Requirements) or for Enhanced Due Diligence, which adds document checks.

Example response

{
  "userId": "<USER_ID>",
  "userDetails": true,
  "kycData": true,
  "dueDiligence": false,
  "verificationHistory": true
}

Trigger verification

Trigger verification so Crossmint runs its compliance checks against the data you provided.

curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>/identity-verification' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'

The response returns the eligibility status per product, starting at pending-review.

Example response

{
  "eligibility": [
    { "type": "onramp", "status": "pending-review" },
    { "type": "onramp-light", "status": "pending-review" },
    { "type": "offramp", "status": "pending-review" },
    { "type": "offramp-light", "status": "pending-review" },
    { "type": "regulated-transfer", "status": "pending-review" }
  ]
}

Poll until verified

Verification is asynchronous. Poll until the offramp eligibility reads verified. Only a verified user can save a payment method or create an order.

curl -X GET 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>/identity-verification' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'

Example response

{
  "eligibility": [
    { "type": "onramp", "status": "verified" },
    { "type": "onramp-light", "status": "verified" },
    { "type": "offramp", "status": "verified" },
    { "type": "offramp-light", "status": "verified" },
    { "type": "regulated-transfer", "status": "verified" }
  ]
}

The exact fields required vary by region. See the Identity data requirements for the full list, and the Identity quickstart for uploading documents when a region requires them.

The account holder name on the user’s saved bank account must match this verified identity. Offramp supports first-party payouts only.

Register and verify the user

Next steps

Collect Bank Accounts

Quickstart

​Register and verify the user

​Next steps

Collect Bank Accounts

Quickstart

Register and verify the user

Next steps