Users & Compliance Quickstart

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 payouts.

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.

User locators use the userId: format, a unique identifier you choose for the user, for example userId:johnd-123.

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.Consent must be collected in your app through a compliant flow (explicit checkbox, exact wording, visible Crossmint logo, re-consent on policy updates). See Register User Data for the full consent-collection requirements.

Meeting these requirements is mandatory for sharing user KYC data with Crossmint. Only record acceptance through the API below after the user has granted consent this way. Crossmint audits data-sharing integrations for compliance with these requirements.

Once the user has accepted the privacy policy, record their acceptance using the following API call:

curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/legal-documents' \
    --header 'X-API-KEY: <your-server-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "crossmint-privacy-policy",
        "acceptedAt": "2025-10-05T14:48:00Z"
    }'

const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        type: "crossmint-privacy-policy",
        acceptedAt: "2025-10-05T14:48:00Z" // 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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/legal-documents"

payload = {
    "type": "crossmint-privacy-policy",
    "acceptedAt": "2025-10-05T14:48:00Z"  # ISO 8601 date string
}
headers = {
    "X-API-KEY": "<your-server-api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())

This call also creates a user with the specified userLocator if one does not already exist.

Register a user with Crossmint by specifying their userLocator, their personal details, and KYC data using the Create User endpoint

curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
    --header 'X-API-KEY: <your-server-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "userDetails": {
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1995-01-01",
            "countryOfResidence": "DE"
        }
    }'

const userLocator = "userId:johnd-123"; 

const options = {
    method: 'PUT',
    headers: {'X-API-KEY': '<your-server-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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

payload = {
    "userDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1995-01-01",
        "countryOfResidence": "DE"
    }
}
headers = {
    "X-API-KEY": "<your-server-api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())

Run identity verification

Once you have registered relevant user information you can trigger checks via the Trigger Identity Verification endpoint.

curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/identity-verification' \
    --header 'X-API-KEY: <your-server-api-key>'

const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {
        'X-API-KEY': '<your-server-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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/identity-verification"

headers = {
    "X-API-KEY": "<your-server-api-key>"
}

response = requests.put(url, headers=headers)

print(response.json())

The response will include the eligibility status for each verification type (regulated-transfer, onramp, onramp-light, offramp, offramp-light):

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
pending-manual-review: Verification requires manual review by Crossmint’s compliance team
verified: User has passed verification
rejected: User has failed verification

Once a product reads verified, the user can use it. A verified offramp status, for example, means the user can cash out through Offramp.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", "selfie-front"] // "proof-of-address" and "proof-of-income" may also be requested in case of Enhanced Due Diligence 
        },
        {
            "type": "onramp-light",
            "status": "requires-data",
            "missingData": ["kyc-data"] // light KYC requires less data and no document uploads
        },
        {
            "type": "offramp",
            "status": "requires-data",
            "missingData": ["kyc-data", "due-diligence", "verification-history"],
            "missingDocuments": ["id", "selfie-front"] // "proof-of-address" and "proof-of-income" may also be requested in case of Enhanced Due Diligence 
        },
        {
            "type": "offramp-light",
            "status": "requires-data",
            "missingData": ["kyc-data"] // light KYC requires less data and no document uploads
        }
    ]
}

Update user information

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.

curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
    --header 'X-API-KEY: <your-server-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "userDetails": {
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1995-01-01",
            "countryOfResidence": "DE"
        },
        "kycData": {
            "nationality": "DE",
            "addressOfResidence": {
                "line1": "123 Hauptstrasse",
                "line2": "Apt 5",
                "city": "Berlin",
                "stateOrRegion": "Berlin",
                "postalCode": "10115"
            },
            "email": "johnd@example.com",
            "identityDocument": {
                "type": "passport",
                "number": "AS12321",
                "issuingCountryCode": "DE"
            },
            "ipAddresses": ["203.0.113.1"]
        },
        "dueDiligence": {
            "employmentStatus": "full-time",
            "sourceOfFunds": "salary-disbursement",
            "industry": "financial-institution",
            "expectedYearlyTxVolume": "volume-0-25k"
        },
        "verificationHistory": {
            "idVerificationTimestamp": "2024-01-15T10:30:00Z",
            "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
        }
    }'

const userLocator = "userId:johnd-123"; 

const options = {
    method: 'PUT',
    headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        userDetails: {
            firstName: "John",
            lastName: "Doe",
            dateOfBirth: "1995-01-01",
            countryOfResidence: "DE"
        },
        kycData: {
            nationality: "DE",
            addressOfResidence: {
                line1: "123 Hauptstrasse",
                line2: "Apt 5",
                city: "Berlin",
                stateOrRegion: "Berlin",
                postalCode: "10115"
            },
            email: "johnd@example.com",
            identityDocument: {
                type: "passport",
                number: "AS12321",
                issuingCountryCode: "DE"
            },
            ipAddresses: ["203.0.113.1"]
        },
        dueDiligence: {
            employmentStatus: "full-time",
            sourceOfFunds: "salary-disbursement",
            industry: "financial-institution",
            expectedYearlyTxVolume: "volume-0-25k"
        },
        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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

payload = {
    "userDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1995-01-01",
        "countryOfResidence": "DE"
    },
    "kycData": {
        "nationality": "DE",
        "addressOfResidence": {
            "line1": "123 Hauptstrasse",
            "line2": "Apt 5",
            "city": "Berlin",
            "stateOrRegion": "Berlin",
            "postalCode": "10115"
        },
        "email": "johnd@example.com",
        "identityDocument": {
            "type": "passport",
            "number": "AS12321",
            "issuingCountryCode": "DE"
        },
        "ipAddresses": ["203.0.113.1"]
    },
    "dueDiligence": {
        "employmentStatus": "full-time",
        "sourceOfFunds": "salary-disbursement",
        "industry": "financial-institution",
        "expectedYearlyTxVolume": "volume-0-25k"
    },
    "verificationHistory": {
        "idVerificationTimestamp": "2024-01-15T10:30:00Z",
        "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
    }
}
headers = {
    "X-API-KEY": "<your-server-api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())

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.

curl --request POST \
    --url 'https://staging.crossmint.com/api/2025-06-09/documents' \
    --header 'X-API-KEY: <your-server-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "reference": {
            "userLocator": "userId:johnd-123"
        },
        "documentType": "id-passport",
        "data": "<base64-encoded-image>",
        "expiresAt": "2030-12-31"
    }'

const options = {
    method: 'POST',
    headers: {'X-API-KEY': '<your-server-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));

import requests

url = "https://staging.crossmint.com/api/2025-06-09/documents"

payload = {
    "reference": {
        "userLocator": "userId:johnd-123"
    },
    "documentType": "id-passport",
    "data": "<base64-encoded-image>",
    "expiresAt": "2030-12-31"
}
headers = {
    "X-API-KEY": "<your-server-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Supported document types:

Identity documents: id-passport, id-idcard-front, id-idcard-back, id-residency-permit (Spain residents only)
Supporting documents: proof-of-address, proof-of-income
Selfie documents: selfie-front, selfie-left, selfie-right

US residents must include kycData.phoneNumber, and provide their identity via SSN in kycData.identityDocument. No identity document upload or selfie is needed for standard on/offramp. However, if Enhanced Due Diligence (EDD) is triggered, US users must also upload a passport (id-passport) or driver’s license (id-idcard-front, id-idcard-back). Proof of income is not required for US EDD users.

Calling this endpoint again with the same userLocator and documentType will update the existing document’s registered information.

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.

curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/identity-verification' \
    --header 'X-API-KEY: <your-server-api-key>'

const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {
        'X-API-KEY': '<your-server-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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/identity-verification"

headers = {
    "X-API-KEY": "<your-server-api-key>"
}

response = requests.put(url, headers=headers)

print(response.json())

The response will include the eligibility status for each verification type (regulated-transfer, onramp, onramp-light, offramp, offramp-light):

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

Check verification status

Verification runs asynchronously. After triggering it, poll the Get Identity Verification Status endpoint until the relevant product status reads verified. It usually completes within a minute, and the transient state may be not-started or pending-review.

curl --request GET \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/identity-verification' \
    --header 'X-API-KEY: <your-server-api-key>'

const userLocator = "userId:johnd-123";

const options = {
    method: 'GET',
    headers: {
        'X-API-KEY': '<your-server-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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/identity-verification"

headers = {
    "X-API-KEY": "<your-server-api-key>"
}

response = requests.get(url, headers=headers)

print(response.json())

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:

curl --request GET \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
    --header 'X-API-KEY: <your-server-api-key>'

const userLocator = "userId:johnd-123";

const options = {
    method: 'GET',
    headers: {
        'X-API-KEY': '<your-server-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));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

headers = {
    "X-API-KEY": "<your-server-api-key>"
}

response = requests.get(url, headers=headers)

print(response.json())

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:

Create a developer account on the production console
Create a production server API key on the API Keys page with the API scopes users.create, users.read
Replace your test API key with the production key
Replace staging.crossmint.com with www.crossmint.com in the API URLs

Introduction

User Identity

User Authentication

API Reference

Quickstart ⚡

Before you start

Launching in Production

Learn More

Data Requirements

Talk to an expert

Before you start

​Launching in Production

​Learn More

Data Requirements

Talk to an expert

Launching in Production

Learn More