Skip to main content

Before you start

Set up your project and get an API key.
Enterprise feature. Contact us for access.
 This quickstart guide walks you through registering a user, uploading documents, and fetching document details using Crossmint’s APIs. These steps enable your users to access regulated products like onramp, offramp, and regulated transfers.
1

User accepts Crossmint's Privacy Policy

Before sharing any user KYC data with Crossmint, you must ensure your users have accepted Crossmint’s Privacy Policy. This is a prerequisite for companies sharing their customer’s KYC data with Crossmint.
Once the user has accepted the privacy policy, record their acceptance using the following API call:
const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        type: "crossmint-privacy-policy",
        acceptedAt: "2025-10-05T14:48:00" // ISO 8601 date string
    })
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/legal-documents`, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
This call also creates a user with the specified userLocator if one does not already exist.
2

Register user information

Register a user with Crossmint by specifying their userLocator, their personal details, and KYC data using the Create User endpoint
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: "1995-01-01",
            countryOfResidence: "DE"
        }
    })
};

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));
3

Run identity verification

Once you have registered relevant user information you can trigger checks via the Trigger Identity Verification endpoint.
const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {
        'X-API-KEY': '<x-api-key>'
    }
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/identity-verification`, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
The response will include the eligibility status for each verification type (regulated-transfer, onramp, offramp):
  • not-started: Verification has not been initiated
  • pending-privacy-policy: User has not yet accepted Crossmint’s Privacy Policy
  • requires-data: Additional user data or documents are needed
  • pending-review: Verification is in progress
  • verified: User has passed verification
  • rejected: User has failed verification
If any of them return requires-data, you must aggregate the missingData and missingDocuments arrays from those specific eligibility objects. Then, update the user’s information using the Update User endpoint and/or upload additional documents using the Upload Document endpoint, and finally re-trigger the verification.
{
    "eligibility": [
        {
            "type": "regulated-transfer",
            "status": "pending-review" // or "verified"
        },
        {
            "type": "onramp",
            "status": "requires-data",
            "missingData": ["kyc-data", "due-diligence", "verification-history"],
            "missingDocuments": ["id"] // "proof-of-address" and "proof-of-income" requested in case of additional due diligence required 
        },
        {
            "type": "offramp",
            "status": "requires-data",
            "missingData": ["kyc-data", "due-diligence", "verification-history"],
            "missingDocuments": ["id"] // "proof-of-address" and "proof-of-income" requested in case of additional due diligence required 
        }
    ]
}
4

Update user information

Register additional user information with Crossmint so the user can access onramp and offramp services.
Calling this endpoint again with the same userLocator will update the existing user’s information. The endpoint is not additive so specify all relevant user information when updating the user.
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: "1995-01-01",
            countryOfResidence: "DE"
        },
        kycData: {
            addressOfResidence: {
                line1: "123 Hauptstrasse",
                line2: "Apt 5",
                city: "Berlin",
                stateOrRegion: "Brandenburg",
                postalCode: "10115"
            },
            email: "johnd@example.com",
            identityDocument: {
                type: "passport",
                number: "AS12321",
                issuingCountryCode: "GR"
            }
        },
        dueDiligence: {
            employmentStatus: "full-time",
            sourceOfFunds: "employment-income",
            industry: "finance-insurance"
        },
        verificationHistory: {
            idVerificationTimestamp: "2024-01-15T10:30:00Z",
            livenessVerificationTimestamp: "2024-01-15T10:32: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));
5

Upload a document

Upload identity or supporting documents for the user using the Upload Document endpoint. Documents are associated with the user via their userLocator.
const options = {
    method: 'POST',
    headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        reference: {
            userLocator: "userId:johnd-123"
        },
        documentType: "id-passport",
        data: "<base64-encoded-image>",
        expiresAt: "2030-12-31"
    })
};

fetch('https://staging.crossmint.com/api/2025-06-09/documents', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
Supported document types:
  • Identity documents: id-ssn, id-passport, id-idcard-front, id-idcard-back
  • Supporting documents: proof-of-address, proof-of-income
Calling this endpoint again with the same userLocator and documentType will update the existing document’s registered information.
6

Run identity verification

Once you have registered the user’s information and uploaded the required documents, trigger the KYC verification process using the Trigger Identity Verification endpoint.
const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {
        'X-API-KEY': '<x-api-key>'
    }
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/identity-verification`, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
The response will include the eligibility status for each verification type (regulated-transfer, onramp, offramp):
{
    "eligibility": [
        {
            "type": "regulated-transfer",
            "status": "verified"
        },
        {
            "type": "onramp",
            "status": "pending-review"
        },
        {
            "type": "offramp",
            "status": "pending-review"
        }
    ]
}
7

Check verification status

After triggering the identity verification, the process usually completes within a few seconds. You can check the current status using the Get Identity Verification Status endpoint.
const userLocator = "userId:johnd-123";

const options = {
    method: 'GET',
    headers: {
        'X-API-KEY': '<x-api-key>'
    }
};

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

Fetch user information

You can fetch a user’s information at any time to see their current status, including when they last accepted valid legal documents. Use the Get User endpoint to retrieve this information:
const userLocator = "userId:johnd-123";

const options = {
    method: 'GET',
    headers: {
        'X-API-KEY': '<x-api-key>'
    }
};

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));
The response includes the legalDocuments array, which shows the status of legal document acceptances:
{
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "userId": "usr_1234567890",
    "userDetails": true,
    "kycData": false,
    "dueDiligence": false,
    "verificationHistory": false,
    "legalDocuments": [
        {
            "type": "crossmint-privacy-policy",
            "acceptedAt": "2024-01-15T10:30:00Z",
            "validVersion": true
        }
    ]
}
The validVersion field indicates whether the user has accepted the current version of the legal document. If validVersion is false, you should prompt the user to accept the updated terms.

​
Launching in Production

For production, the steps are almost identical, but some changes are required:
  1. Create a developer account on the production console
  2. Create a production server API key on the API Keys page with the API scopes users.create, users.read
  3. Replace your test API key with the production key
  4. Replace staging.crossmint.com with www.crossmint.com in the API URLs

​
Learn More

Data Requirements

See what data is required for each activity and region.

Talk to an expert

Contact the Crossmint sales team for support.