Register User Data

Ideal for companies that have verified users through their own identity verification (IDV) provider.

Companies can compliantly pass user KYC data to Crossmint, enabling seamless USDC onramp purchase flows. If you prefer to have individual users provide their KYC data client-side, Crossmint supports that as well. See the React Quickstart for that approach.

How It Works

Crossmint relies on your company running KYC, ID verification, and liveness checks with your own IDV provider (such as Persona or Sumsub). You then share the full KYC data with Crossmint via API. In order to complete orders, Crossmint runs sanction and PEP (Politically Exposed Persons) screens, and performs ongoing monitoring to ensure compliance.

Register User with Full KYC Data

To register a user’s KYC data with Crossmint, make a PUT request to the users endpoint with the full KYC payload. Use Crossmint API key with scope users.create.

const userLocator = "userId:johnd-123";

const options = {
  method: 'PUT',
  headers: {
    'X-API-KEY': '<x-api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userDetails: {
      firstName: "John",
      lastName: "Doe",
      dateOfBirth: "1990-05-15",
      countryOfResidence: "DE",
    }
    kycData: {
      addressOfResidence: {
        line1: "123 Hauptstrasse",
        line2: "Apt 5",
        city: "Berlin",
        postalCode: "10115"
      },
      email: "[email protected]"
      identityDocument: {
        type: "passport",
        number: "AS12321",
        image: {
          frontImg: "<base 64 encoded file (10mb limit)>",
          backImg: "<base 64 encoded file (10mb limit)>"
        }
      }
    },
    dueDiligence: {
      employmentStatus: "full time",
      sourceOfFunds: "employment income", 
      industry: "Money Service Business"
    }, 
    enhancedDueDiligence: {
      proofOfIncome: "<base 64 encoded file (10mb limit)>",
      proofOfAddress: "<base 64 encoded file (10mb limit)>"
    }, 
    verificationHistory: {
      idVerificationTimestamp: "2024-11-15T10:35:00Z",
      livenessVerificationTimestamp: "2024-11-15T10:35:00Z"
    }
  })
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

User Data Fields

userDetails

object

required

Basis user details

Show properties

userDetails.firstName

string

required

User’s first name

userDetails.lastName

string

required

User’s last name

userDetails.dateOfBirth

string

required

User’s date of birth in YYYY-MM-DD format

userDetails.countryOfResidence

string

required

User’s country of residence code in ISO 3166-1 alpha-2 format (e.g., “US”, “GB”, “DE”)

kycData

object

User’s KYC data

Show properties

kycData.addressOfResidence

object

required

User’s residential address information.

Show properties

addressOfResidence.line1

string

required

Street address

addressOfResidence.line2

string

Apartment or suite number

addressOfResidence.city

string

required

City name

addressOfResidence.state

string

State name (if US)

addressOfResidence.postalCode

string

required

Postal/ZIP code

kycData.email

string

required

User’s email address

kycData.identityDocument

object

required

User’s identity document

Show properties

identityDocument.type

string

required

Document type (e.g., passport, SSN, ID)

identityDocument.number

string

required

Document number

identityDocument.image

object

required

Document’s front and back image

Show properties

image.frontImg

string

required

Base 64 encoded file (10mb limit)

image.backImg

string

required

Base 64 encoded file (10mb limit)

dueDiligence

object

User’s employment information

Show properties

dueDiligence.employmentStatus

string

required

Status of employment. Allowed values: contractual, full time, part time, retired, self employed, student, unemployed

dueDiligence.sourceOfFunds

string

required

Source of funds. Allowed values: employment income, investments gains, business dividends & profits, real estate, inheritance, savings & personal funds, loan disbursement, government benefits, Other

dueDiligence.industry

string

required

Industry working in. Allowed values: Accommodation Food Services, Administrative Support Waste Management Remediation Services, Adult Entertainment, Agriculture Forestry Fishing Hunting, Arts Entertainment Recreation, Auctions, Automobiles, Blockchain, Construction, Crypto, E Commerce, Educational Services, Export Import, Finance Insurance, Financial Institution, Hedge Fund, Health Care Social Assistance, Information, Insurance, Investment, Management Of Companies Enterprises, Manufacturing, Market Maker, Mining, Money Service Business, Non Profit, Precious Metals, Professional Scientific Technical Services, Public Administration, Real Estate Rental Leasing, Registered Investment Advisor, Retail Trade, Shell Bank, Stock Issuer, Student, Transportation Warehousing, Travel Transport, Unemployed, Utilities, Wholesale Trade, Other Services

enhancedDueDiligence

object

User’s proof of income and proof of address documentation

Show properties

enhancedDueDiligence.proofOfIncome

string

required

Document proving user’s income

enhancedDueDiligence.proofOfAddress

string

required

Document proving user’s residential address

verificationHistory

object

Verification results from your IDV provider

Show properties

verificationHistory.idVerificationTimestamp

string

required

ISO 8601 timestamp of ID verification

verificationHistory.livenessVerificationTimestamp

string

required

ISO 8601 timestamp of liveness verification

Create an Onramp Order

Once the user is registered with their KYC data, you can create an onramp order. The order will use the registered KYC data for compliance checks.

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<x-api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      walletAddress: "<recipient-user-wallet-address>"
    },
    payment: {
      method: "card",
      receiptEmail: "[email protected]"
    },
    lineItems: {
      tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      executionParameters: {
        mode: "exact-in",
        amount: "1"
      }
    }
  })
};

fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Order Responses

Success: Full KYC Data Present

When all required KYC data has been provided and validated, the order moves to the payment phase:

{
  "clientSecret": "...",
  "order": {
    "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [...],
    "quote": {...},
    "payment": {
      "method": "card",
      "currency": "usd",
      "status": "awaiting-payment"
    }
  }
}

Success: Additional KYC Inquiry

When full KYC data is present but Crossmint needs to run additional compliance checks, the order enters a processing state. This typically resolves within a few seconds as Crossmint runs the appropriate checks:

{
  "clientSecret": "...",
  "order": {
    "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [...],
    "quote": {...},
    "payment": {
      "method": "card",
      "currency": "usd",
      "status": "processing-kyc-verification"
    }
  }
}

Error: Missing KYC Data

If no user personal data is provided, or if the data is insufficient, the order will fail:

{
  "error": true,
  "message": "Required full KYC user data is missing to complete the order"
}

Introduction

Onramp

Treasury Wallet

Regulated Transfers

How It Works

Register User with Full KYC Data

User Data Fields

Create an Onramp Order

Order Responses

Success: Full KYC Data Present

Success: Additional KYC Inquiry

Error: Missing KYC Data

Next Steps

React Quickstart

Onramp Overview

Introduction

Onramp

Treasury Wallet

Regulated Transfers

​How It Works

​Register User with Full KYC Data

​User Data Fields

​Create an Onramp Order

​Order Responses

​Success: Full KYC Data Present

​Success: Additional KYC Inquiry

​Error: Missing KYC Data

​Next Steps

React Quickstart

Onramp Overview

How It Works

Register User with Full KYC Data

User Data Fields

Create an Onramp Order

Order Responses

Success: Full KYC Data Present

Success: Additional KYC Inquiry

Error: Missing KYC Data

Next Steps