Create or Update User

Create or update a user and their personal data by user locator. If the user doesn’t exist, they will be created.

API scope required: users.create

PUT /2025-06-09/users/{userLocator}

Create or Update User

cURL

curl --request PUT \
  --url https://staging.crossmint.com/api/2025-06-09/users/{userLocator} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "userDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-15",
    "countryOfResidence": "US"
  },
  "kycData": {
    "nationality": "US",
    "addressOfResidence": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "New York",
      "stateOrRegion": "NY",
      "postalCode": "10001"
    },
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "identityDocument": {
      "type": "ssn",
      "number": "123-45-6789",
      "issuingCountryCode": "US"
    }
  },
  "verificationHistory": {
    "idVerificationTimestamp": "2024-01-15T10:30:00Z",
    "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
  },
  "dueDiligence": {
    "employmentStatus": "full-time",
    "sourceOfFunds": "salary-disbursement",
    "industry": "financial-institution",
    "estimatedYearlyIncome": "income-50k-100k",
    "expectedYearlyTxVolume": "volume-25k-75k"
  }
}
'

import requests

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

payload = {
    "userDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-01-15",
        "countryOfResidence": "US"
    },
    "kycData": {
        "nationality": "US",
        "addressOfResidence": {
            "line1": "123 Main Street",
            "line2": "Apt 4B",
            "city": "New York",
            "stateOrRegion": "NY",
            "postalCode": "10001"
        },
        "email": "[e-mail]",
        "phoneNumber": "[phone]",
        "identityDocument": {
            "type": "ssn",
            "number": "123-45-6789",
            "issuingCountryCode": "US"
        }
    },
    "verificationHistory": {
        "idVerificationTimestamp": "2024-01-15T10:30:00Z",
        "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
    },
    "dueDiligence": {
        "employmentStatus": "full-time",
        "sourceOfFunds": "salary-disbursement",
        "industry": "financial-institution",
        "estimatedYearlyIncome": "income-50k-100k",
        "expectedYearlyTxVolume": "volume-25k-75k"
    }
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

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-01-15',
      countryOfResidence: 'US'
    },
    kycData: {
      nationality: 'US',
      addressOfResidence: {
        line1: '123 Main Street',
        line2: 'Apt 4B',
        city: 'New York',
        stateOrRegion: 'NY',
        postalCode: '10001'
      },
      email: '[e-mail]',
      phoneNumber: '[phone]',
      identityDocument: {type: 'ssn', number: '123-45-6789', issuingCountryCode: 'US'}
    },
    verificationHistory: {
      idVerificationTimestamp: '2024-01-15T10:30:00Z',
      livenessVerificationTimestamp: '2024-01-15T10:32:00Z'
    },
    dueDiligence: {
      employmentStatus: 'full-time',
      sourceOfFunds: 'salary-disbursement',
      industry: 'financial-institution',
      estimatedYearlyIncome: 'income-50k-100k',
      expectedYearlyTxVolume: 'volume-25k-75k'
    }
  })
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.crossmint.com/api/2025-06-09/users/{userLocator}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'userDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe',
        'dateOfBirth' => '1990-01-15',
        'countryOfResidence' => 'US'
    ],
    'kycData' => [
        'nationality' => 'US',
        'addressOfResidence' => [
                'line1' => '123 Main Street',
                'line2' => 'Apt 4B',
                'city' => 'New York',
                'stateOrRegion' => 'NY',
                'postalCode' => '10001'
        ],
        'email' => '[e-mail]',
        'phoneNumber' => '[phone]',
        'identityDocument' => [
                'type' => 'ssn',
                'number' => '123-45-6789',
                'issuingCountryCode' => 'US'
        ]
    ],
    'verificationHistory' => [
        'idVerificationTimestamp' => '2024-01-15T10:30:00Z',
        'livenessVerificationTimestamp' => '2024-01-15T10:32:00Z'
    ],
    'dueDiligence' => [
        'employmentStatus' => 'full-time',
        'sourceOfFunds' => 'salary-disbursement',
        'industry' => 'financial-institution',
        'estimatedYearlyIncome' => 'income-50k-100k',
        'expectedYearlyTxVolume' => 'volume-25k-75k'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"userDetails\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"countryOfResidence\": \"US\"\n  },\n  \"kycData\": {\n    \"nationality\": \"US\",\n    \"addressOfResidence\": {\n      \"line1\": \"123 Main Street\",\n      \"line2\": \"Apt 4B\",\n      \"city\": \"New York\",\n      \"stateOrRegion\": \"NY\",\n      \"postalCode\": \"10001\"\n    },\n    \"email\": \"[e-mail]\",\n    \"phoneNumber\": \"[phone]\",\n    \"identityDocument\": {\n      \"type\": \"ssn\",\n      \"number\": \"123-45-6789\",\n      \"issuingCountryCode\": \"US\"\n    }\n  },\n  \"verificationHistory\": {\n    \"idVerificationTimestamp\": \"2024-01-15T10:30:00Z\",\n    \"livenessVerificationTimestamp\": \"2024-01-15T10:32:00Z\"\n  },\n  \"dueDiligence\": {\n    \"employmentStatus\": \"full-time\",\n    \"sourceOfFunds\": \"salary-disbursement\",\n    \"industry\": \"financial-institution\",\n    \"estimatedYearlyIncome\": \"income-50k-100k\",\n    \"expectedYearlyTxVolume\": \"volume-25k-75k\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://staging.crossmint.com/api/2025-06-09/users/{userLocator}")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userDetails\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"countryOfResidence\": \"US\"\n  },\n  \"kycData\": {\n    \"nationality\": \"US\",\n    \"addressOfResidence\": {\n      \"line1\": \"123 Main Street\",\n      \"line2\": \"Apt 4B\",\n      \"city\": \"New York\",\n      \"stateOrRegion\": \"NY\",\n      \"postalCode\": \"10001\"\n    },\n    \"email\": \"[e-mail]\",\n    \"phoneNumber\": \"[phone]\",\n    \"identityDocument\": {\n      \"type\": \"ssn\",\n      \"number\": \"123-45-6789\",\n      \"issuingCountryCode\": \"US\"\n    }\n  },\n  \"verificationHistory\": {\n    \"idVerificationTimestamp\": \"2024-01-15T10:30:00Z\",\n    \"livenessVerificationTimestamp\": \"2024-01-15T10:32:00Z\"\n  },\n  \"dueDiligence\": {\n    \"employmentStatus\": \"full-time\",\n    \"sourceOfFunds\": \"salary-disbursement\",\n    \"industry\": \"financial-institution\",\n    \"estimatedYearlyIncome\": \"income-50k-100k\",\n    \"expectedYearlyTxVolume\": \"volume-25k-75k\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging.crossmint.com/api/2025-06-09/users/{userLocator}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userDetails\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"countryOfResidence\": \"US\"\n  },\n  \"kycData\": {\n    \"nationality\": \"US\",\n    \"addressOfResidence\": {\n      \"line1\": \"123 Main Street\",\n      \"line2\": \"Apt 4B\",\n      \"city\": \"New York\",\n      \"stateOrRegion\": \"NY\",\n      \"postalCode\": \"10001\"\n    },\n    \"email\": \"[e-mail]\",\n    \"phoneNumber\": \"[phone]\",\n    \"identityDocument\": {\n      \"type\": \"ssn\",\n      \"number\": \"123-45-6789\",\n      \"issuingCountryCode\": \"US\"\n    }\n  },\n  \"verificationHistory\": {\n    \"idVerificationTimestamp\": \"2024-01-15T10:30:00Z\",\n    \"livenessVerificationTimestamp\": \"2024-01-15T10:32:00Z\"\n  },\n  \"dueDiligence\": {\n    \"employmentStatus\": \"full-time\",\n    \"sourceOfFunds\": \"salary-disbursement\",\n    \"industry\": \"financial-institution\",\n    \"estimatedYearlyIncome\": \"income-50k-100k\",\n    \"expectedYearlyTxVolume\": \"volume-25k-75k\"\n  }\n}"

response = http.request(request)
puts response.read_body

200

{
  "userDetails": true,
  "kycData": false,
  "dueDiligence": false,
  "verificationHistory": false,
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "userId": "usr_1234567890",
  "legalDocuments": {
    "type": "crossmint-privacy-policy",
    "acceptedAt": "2023-01-01T00:00:00.000Z",
    "isValidVersion": true
  }
}

{
  "userDetails": true,
  "kycData": false,
  "dueDiligence": false,
  "verificationHistory": false,
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "userId": "usr_1234567890",
  "legalDocuments": {
    "type": "crossmint-privacy-policy",
    "acceptedAt": "2023-01-01T00:00:00.000Z",
    "isValidVersion": true
  }
}

Headers

X-API-KEY · string · required

API key required for authentication

Path Parameters

userLocator · string · required

A user locator can be of the format:

• email:<email>
• userId:<userId>
• phoneNumber:<phoneNumber>
• twitter:<handle>
• x:<handle>

Body

application/json

userDetails · object · required

Optional user details including name, date of birth, and country of residence

Show child attributes

Example:

{
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-15",
  "countryOfResidence": "US"
}

kycData · object · required

Optional KYC data for identity verification

Show child attributes

Example:

{
  "nationality": "US",
  "addressOfResidence": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "New York",
    "stateOrRegion": "NY",
    "postalCode": "10001"
  },
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "identityDocument": {
    "type": "ssn",
    "number": "123-45-6789",
    "issuingCountryCode": "US"
  }
}

verificationHistory · object · required

Optional verification timestamps.

Show child attributes

Example:

{
  "idVerificationTimestamp": "2024-01-15T10:30:00Z",
  "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
}

dueDiligence · object

Optional due diligence information for compliance purposes

Option 1

Option 2

Show child attributes

Example:

{
  "employmentStatus": "full-time",
  "sourceOfFunds": "salary-disbursement",
  "industry": "financial-institution",
  "estimatedYearlyIncome": "income-50k-100k",
  "expectedYearlyTxVolume": "volume-25k-75k"
}

Response

200

application/json

User updated

userDetails · boolean · required

Whether user details have been provided

Example:

true

kycData · boolean · required

Whether KYC data has been provided

Example:

false

dueDiligence · boolean · required

Whether due diligence data has been provided

Example:

false

verificationHistory · boolean · required

Whether verification history has been provided

Example:

false

email · string

User's email address

Example:

"[e-mail]"

phoneNumber · string

User's phone number

Example:

"[phone]"

userId · string

Unique user identifier

Example:

"usr_1234567890"

legalDocuments · object[]

List of accepted legal documents

Show child attributes

Example:

{
  "type": "crossmint-privacy-policy",
  "acceptedAt": "2023-01-01T00:00:00.000Z",
  "isValidVersion": true
}