> ## Documentation Index > Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt > Use this file to discover all available pages before exploring further. # 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` ## OpenAPI ````yaml put /2025-06-09/users/{userLocator} openapi: 3.0.0 info: title: Crossmint Users API description: Crossmint Users API version: 1.0.0 contact: name: Crossmint Support url: https://www.crossmint.com email: support@crossmint.com servers: - url: https://staging.crossmint.com/api description: Staging environment (testnets) - url: https://www.crossmint.com/api description: Production environment (mainnets) security: [] tags: [] paths: /2025-06-09/users/{userLocator}: put: tags: - Users summary: Create or Update User description: >- 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` operationId: UsersController-upsertUser-2 parameters: - name: X-API-KEY in: header description: API key required for authentication required: true schema: type: string - name: userLocator required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertUserDto' responses: '200': description: User updated content: application/json: schema: $ref: '#/components/schemas/UserResponseDto' '201': description: User created content: application/json: schema: $ref: '#/components/schemas/UserResponseDto' components: schemas: UpsertUserDto: type: object properties: userDetails: type: object properties: firstName: type: string minLength: 1 maxLength: 50 pattern: ^[\p{L}\p{M}\s'-]+$ description: User's legal first name example: John lastName: type: string minLength: 1 maxLength: 60 pattern: ^[\p{L}\p{M}\s'-]+$ description: User's legal last name example: Doe dateOfBirth: type: string minLength: 10 maxLength: 10 pattern: ^\d{4}-\d{2}-\d{2}$ description: User's date of birth in YYYY-MM-DD format example: '1990-01-15' countryOfResidence: type: string minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ description: User's country of residence in ISO 3166-1 alpha-2 format example: US required: - firstName - lastName - dateOfBirth - countryOfResidence description: >- Optional user details including name, date of birth, and country of residence example: firstName: John lastName: Doe dateOfBirth: '1990-01-15' countryOfResidence: US kycData: type: object properties: addressOfResidence: type: object properties: line1: type: string minLength: 1 description: Primary address line (street address) example: 123 Main Street line2: type: string description: Secondary address line (apartment, suite, etc.) example: Apt 4B city: type: string minLength: 1 description: City name example: New York stateOrRegion: type: string minLength: 1 description: State, province, or region example: NY postalCode: type: string minLength: 1 description: Postal or ZIP code example: '10001' required: - line1 - city - stateOrRegion - postalCode description: Physical address of residence example: line1: 123 Main Street line2: Apt 4B city: New York stateOrRegion: NY postalCode: '10001' email: type: string format: email description: User's email address, required for verification example: john.doe@example.com phoneNumber: default: '' type: string description: User's phone number, Recommended for verification example: '+1234567890' identityDocument: oneOf: - type: object properties: type: type: string enum: - id - passport description: Type of identity document example: passport number: type: string minLength: 1 description: Identity document number example: AB123456 issuingCountryCode: type: string minLength: 2 maxLength: 2 description: Issuing country code of the identity document example: ES required: - type - number - issuingCountryCode description: Identity document details example: type: passport number: AB123456 issuingCountryCode: ES - type: object properties: type: type: string enum: - ssn - passport description: >- Type of identity document for US users. SSN for US citizens, passport for non-US citizens only. example: ssn number: type: string minLength: 1 description: >- Identity document number. For SSN, must be in XXX-XX-XXXX format. example: 123-45-6789 issuingCountryCode: type: string minLength: 2 maxLength: 2 description: Issuing country code of the identity document example: US required: - type - number - issuingCountryCode description: >- Identity document details for US users. SSN for US citizens, passport for non-US citizens only. example: type: ssn number: 123-45-6789 issuingCountryCode: US required: - addressOfResidence - email - identityDocument description: Optional KYC data for identity verification example: addressOfResidence: line1: 123 Main Street line2: Apt 4B city: New York stateOrRegion: NY postalCode: '10001' email: john.doe@example.com phoneNumber: '+1234567890' identityDocument: type: passport number: AB123456 issuingCountryCode: ES dueDiligence: oneOf: - type: object properties: employmentStatus: type: string enum: - full-time - part-time - contractual - self-employed - student - retired - unemployed description: User's current employment status example: full-time sourceOfFunds: type: string enum: - salary-disbursement - business-dividends-profits - investment-returns - property-sale - inheritance-distribution - savings-personal-funds - loan-disbursement - government-benefits description: Primary source of the user's funds example: salary-disbursement industry: type: string enum: - accommodation-food-services - >- administrative-support-waste-management-remediation-services - adult-entertainment - agriculture-forestry-fishing-hunting - arts-entertainment-recreation - auctions - automobiles - professional-scientific-technical-services - blockchain - construction - crypto - e-commerce - educational-services - export-import - financial-institution - gambling - health-care-social-assistance - hedge-fund - insurance - registered-investment-advisor - investment - management-of-companies-enterprises - manufacturing - market-maker - mining - money-service-business - non-profit - drugs - precious-metals - public-administration - real-estate-rental-leasing - retail-trade - shell-bank - sto-issuer - information - transportation-warehousing - travel-transport - utilities - weapons - wholesale-trade - other-services description: Industry in which the user is employed or conducts business example: financial-institution estimatedYearlyIncome: type: string enum: - income-0-50k - income-50k-100k - income-100k-250k - income-250k-500k - income-500k-750k - income-750k-1mil - income-above-1mil description: User's estimated yearly income range in USD example: income-50k-100k required: - employmentStatus - sourceOfFunds - industry - estimatedYearlyIncome description: >- Due diligence information for US users including employment, source of funds, and estimated yearly income example: employmentStatus: full-time sourceOfFunds: salary-disbursement industry: financial-institution estimatedYearlyIncome: income-50k-100k - type: object properties: employmentStatus: type: string enum: - full-time - part-time - contractual - self-employed - student - retired - unemployed description: User's current employment status example: full-time sourceOfFunds: type: string enum: - salary-disbursement - business-dividends-profits - investment-returns - property-sale - inheritance-distribution - savings-personal-funds - loan-disbursement - government-benefits description: Primary source of the user's funds example: salary-disbursement industry: type: string enum: - accommodation-food-services - >- administrative-support-waste-management-remediation-services - adult-entertainment - agriculture-forestry-fishing-hunting - arts-entertainment-recreation - auctions - automobiles - professional-scientific-technical-services - blockchain - construction - crypto - e-commerce - educational-services - export-import - financial-institution - gambling - health-care-social-assistance - hedge-fund - insurance - registered-investment-advisor - investment - management-of-companies-enterprises - manufacturing - market-maker - mining - money-service-business - non-profit - drugs - precious-metals - public-administration - real-estate-rental-leasing - retail-trade - shell-bank - sto-issuer - information - transportation-warehousing - travel-transport - utilities - weapons - wholesale-trade - other-services description: Industry in which the user is employed or conducts business example: financial-institution required: - employmentStatus - sourceOfFunds - industry description: >- Due diligence information about the user including employment and source of funds example: employmentStatus: full-time sourceOfFunds: salary-disbursement industry: financial-institution description: Optional due diligence information for compliance purposes verificationHistory: type: object properties: idVerificationTimestamp: type: string format: date-time description: ISO 8601 timestamp of when ID verification was completed example: '2024-01-15T10:30:00Z' livenessVerificationTimestamp: type: string format: date-time description: ISO 8601 timestamp of when liveness verification was completed example: '2024-01-15T10:32:00Z' required: - idVerificationTimestamp - livenessVerificationTimestamp description: Optional verification timestamps. example: idVerificationTimestamp: '2024-01-15T10:30:00Z' livenessVerificationTimestamp: '2024-01-15T10:32:00Z' UserResponseDto: type: object properties: email: type: string description: User's email address example: john.doe@example.com phoneNumber: type: string description: User's phone number example: '+1234567890' userId: type: string description: Unique user identifier example: usr_1234567890 userDetails: type: boolean description: Whether user details have been provided example: true kycData: type: boolean description: Whether KYC data has been provided example: false dueDiligence: type: boolean description: Whether due diligence data has been provided example: false verificationHistory: type: boolean description: Whether verification history has been provided example: false legalDocuments: type: array items: type: object properties: type: type: string enum: - crossmint-privacy-policy - crossmint-terms-of-service description: The type of the legal document example: crossmint-privacy-policy acceptedAt: type: string description: ISO 8601 timestamp of when the document was accepted example: '2023-01-01T00:00:00.000Z' isValidVersion: type: boolean description: >- Indicates whether the signed version of the document is not outdated example: true required: - type - acceptedAt - isValidVersion description: List of accepted legal documents example: - type: crossmint-privacy-policy acceptedAt: '2023-01-01T00:00:00.000Z' isValidVersion: true required: - userDetails - kycData - dueDiligence - verificationHistory description: Response schema indicating which user data fields have been populated example: email: john.doe@example.com phoneNumber: '+1234567890' userId: usr_1234567890 userDetails: true kycData: false dueDiligence: false verificationHistory: false ````