{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Crossmint Docs","colors":{"primary":"#36b37e","light":"#87ff8f","dark":"#001d01"},"logo":{"light":"https://mintcdn.com/crossmint/a8gPOTKEuVFcSfC3/logo/crossmint-light.png?fit=max\u0026auto=format\u0026n=a8gPOTKEuVFcSfC3\u0026q=85\u0026s=8c2671e4c8f7da6956e1508bd68c2928","dark":"https://mintcdn.com/crossmint/a8gPOTKEuVFcSfC3/logo/crossmint-dark.png?fit=max\u0026auto=format\u0026n=a8gPOTKEuVFcSfC3\u0026q=85\u0026s=272ecc17664d17b9ff24471758ff80b2"},"favicon":"https://mintcdn.com/crossmint/xq66q9GV6z6jjj95/favicon.png?fit=max\u0026auto=format\u0026n=xq66q9GV6z6jjj95\u0026q=85\u0026s=00fb89ddf6ba5b1022b9307039c08006","api":{"openapi":["api-reference/_open-api/MintingAPIs.json","api-reference/_open-api/AdminAPIs.json","api-reference/_open-api/VerifiableCredentialsAPIs.json","api-reference/_open-api/Wallets.json"],"examples":{"prefill":true}},"background":{"color":{"dark":"#090b0c"}},"navbar":{"links":[{"href":"https://www.crossmint.com/contact","label":"Support"},{"href":"https://staging.crossmint.com/console","label":"Staging Console"}],"primary":{"type":"button","label":"Console","href":"https://www.crossmint.com/console"}},"footer":{"socials":{"website":"https://www.crossmint.com","twitter":"https://x.com/crossmint","github":"https://github.com/crossmint"}},"integrations":{"ga4":{"measurementId":"G-CP5EDD6GVT"},"posthog":{"apiKey":"phc_tfgodwfjuO9v3Nw0tIWJNzACoi2opL7X2Ly0Mg2UCTz","apiHost":"https://eu.i.posthog.com","sessionRecording":false}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"crossmint","hasAudioNarration":false,"actualSubdomain":"crossmint","customDomains":["docs.crossmint.com"],"gitSource":{"type":"github","owner":"paella-labs","repo":"crossbit-main","deployBranch":"main","contentDirectory":"apps/crossmint-mintlify-docs/src","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"edits":true,"issues":true,"contextualFeedback":{"allowEmail":true},"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"REMOVE_BRANDING":{"status":"ENABLED"},"CONTEXTUAL_FEEDBACK":{"status":"ENABLED"},"CODE_SNIPPET_FEEDBACK":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6affa021b76003e4de6c0056","clientVersion":"0.0.4248","searchFilterCounts":[{"language":"default","tag":"Embedded Finance","count":1125},{"language":"default","tag":"API Reference","count":1094},{"language":"default","tag":"Wallets","count":871},{"language":"default","tag":"Kotlin SDK","count":427},{"language":"default","tag":"Swift SDK","count":237},{"language":"default","tag":"Checkout","count":196},{"language":"default","tag":"Classes","count":182},{"language":"default","tag":"Data Classes","count":182},{"language":"default","tag":"Typescript SDK","count":156},{"language":"default","tag":"Guides","count":135}]},"assistantConfig":{"enableAskAiButton":true,"enableStarterQuestions":false,"enableAskAiSearchBar":false,"deflection":{"enabled":true,"type":"link","url":"https://www.crossmint.com/contact/sales"}},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":".tab-container [data-component-part=\"tabs-list\"]{flex-wrap:wrap;overflow:visible;row-gap:0.25rem}.tab-container [data-component-part=\"tabs-list\"]>li{white-space:nowrap}.nav-dropdown-item,.nav-dropdown-item *{font-weight:500!important;color:rgb(75, 85, 99)!important}.nav-dropdown-item:hover,.nav-dropdown-item:hover *{color:rgb(31, 41, 55)!important}.dark .nav-dropdown-item,.dark .nav-dropdown-item *{color:rgb(156, 163, 175)!important}.dark .nav-dropdown-item:hover,.dark .nav-dropdown-item:hover *{color:rgb(209, 213, 219)!important}#header .eyebrow[data-product]::before{content:attr(data-product) \" / \";white-space:pre;color:rgb(107, 114, 128)}.dark #header .eyebrow[data-product]::before{color:rgb(156, 163, 175)}"}]}
{"page":{"pagePath":"api-reference/users/upsert-user","slug":"/api-reference/users/upsert-user","pageMetadata":{"openapi":"api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}","title":"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.\n\n**API scope required**: `users.create`","href":"/api-reference/users/upsert-user"},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create or update a user and their personal data by user locator. If the user doesn’t exist, they will be created.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"API scope required\"\n }), \": \", _jsx(_components.code, {\n children: \"users.create\"\n })]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"openapi":"api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}","title":"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.\n\n**API scope required**: `users.create`","href":"/api-reference/users/upsert-user"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/_mintlify/custom/crossmint/d1c432d03c0c4224/scripts/dd.js","/_mintlify/custom/crossmint/7fc8d54052d3edb0/scripts/hubspot.js","/_mintlify/custom/crossmint/109da5a016f21918/scripts/product-breadcrumb.js"],"openApiReferenceData":{"operation":{"description":"Create or update a user and their personal data by user locator. If the user doesn't exist, they will be created.\n\n**API scope required**: `users.create`","operationId":"users.upsert","parameters":["57958ae4-4bfe-4c24-8d23-944c0559916d"],"requestBody":"24428f15-18a5-4500-9438-3c63b2e22b2b","responses":{"200":"31e49521-89ef-4180-bc9e-ce6019b67246","201":"5ec984bf-113e-4869-8e85-725371da061e"},"security":["80beb2ea-b8ee-493f-8588-217448718a55"],"summary":"Create or Update User","tags":["Users"],"method":"put","type":"path","servers":["6b623d87-f9d6-4061-b2e9-f38de7501e68","04fd49ba-e38c-4101-82b6-f5e8c12c7a9c"],"path":"/2025-06-09/users/{userLocator}","baseUrlOptions":["https://staging.crossmint.com/api","https://www.crossmint.com/api"],"title":"Create or Update User","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated","prefillPlaygroundWithExample":true,"prefillPlaygroundExamples":[{"body.dueDiligence.oneOf.0.employmentStatus":"full-time","body.dueDiligence.oneOf.0.industry":"financial-institution","body.dueDiligence.oneOf.0.sourceOfFunds":"salary-disbursement","body.dueDiligence.oneOf.0.expectedYearlyTxVolume":"volume-0-25k","body.kycData.addressOfResidence.city":"Berlin","body.kycData.addressOfResidence.line1":"123 Hauptstrasse","body.kycData.addressOfResidence.postalCode":"10115","body.kycData.addressOfResidence.stateOrRegion":"Berlin","body.kycData.addressOfResidence.line2":"Apt 5","body.kycData.email":"johnd@example.com","body.kycData.identityDocument.oneOf.0.issuingCountryCode":"DE","body.kycData.identityDocument.oneOf.0.number":"AS12321","body.kycData.identityDocument.oneOf.0.type":"passport","body.kycData.ipAddresses.items.0":"203.0.113.1","body.kycData.nationality":"DE","body.userDetails.countryOfResidence":"DE","body.userDetails.dateOfBirth":"1995-01-01","body.userDetails.firstName":"John","body.userDetails.lastName":"Doe"},{"body.kycData.addressOfResidence.city":"Berlin","body.kycData.addressOfResidence.line1":"123 Hauptstrasse","body.kycData.addressOfResidence.postalCode":"10115","body.kycData.addressOfResidence.stateOrRegion":"Berlin","body.kycData.addressOfResidence.line2":"Apt 5","body.kycData.email":"johnd@example.com","body.kycData.identityDocument.oneOf.0.issuingCountryCode":"DE","body.kycData.identityDocument.oneOf.0.number":"AS12321","body.kycData.identityDocument.oneOf.0.type":"passport","body.kycData.ipAddresses.items.0":"203.0.113.1","body.kycData.nationality":"DE","body.userDetails.countryOfResidence":"DE","body.userDetails.dateOfBirth":"1995-01-01","body.userDetails.firstName":"John","body.userDetails.lastName":"Doe"},{"body.userDetails.countryOfResidence":"DE","body.userDetails.dateOfBirth":"1995-01-01","body.userDetails.firstName":"John","body.userDetails.lastName":"Doe"},{"body.dueDiligence.oneOf.1.employmentStatus":"full-time","body.dueDiligence.oneOf.1.estimatedYearlyIncome":"income-50k-100k","body.dueDiligence.oneOf.1.industry":"financial-institution","body.dueDiligence.oneOf.1.sourceOfFunds":"salary-disbursement","body.dueDiligence.oneOf.1.expectedYearlyTxVolume":"volume-0-25k","body.kycData.addressOfResidence.city":"New York","body.kycData.addressOfResidence.line1":"123 Main Street","body.kycData.addressOfResidence.postalCode":"10001","body.kycData.addressOfResidence.stateOrRegion":"NY","body.kycData.addressOfResidence.line2":"Apt 4B","body.kycData.email":"jane.doe@example.com","body.kycData.identityDocument.oneOf.1.issuingCountryCode":"US","body.kycData.identityDocument.oneOf.1.number":"123-45-6789","body.kycData.identityDocument.oneOf.1.type":"ssn","body.kycData.ipAddresses.items.0":"203.0.113.1","body.kycData.nationality":"US","body.kycData.phoneNumber":"+12125550123","body.userDetails.countryOfResidence":"US","body.userDetails.dateOfBirth":"1990-01-15","body.userDetails.firstName":"Jane","body.userDetails.lastName":"Doe"}]},"dependencies":{"parameters":{"57958ae4-4bfe-4c24-8d23-944c0559916d":{"description":"A user locator can be of the format:\n- `email:\u003cemail>`\n- `userId:\u003cuserId>`\n- `phoneNumber:\u003cphoneNumber>`\n- `twitter:\u003chandle>`\n- `x:\u003chandle>`","in":"path","name":"userLocator","required":true,"schema":{"examples":["email:user@example.com","userId:507f1f77bcf86cd799439011","userId:did:example:cm4lr5piw0h6t1bjho0onryql","phoneNumber:+12125551234","twitter:johndoe","x:@johndoe"],"type":"string","isRequired":true,"description":"A user locator can be of the format:\n- `email:\u003cemail>`\n- `userId:\u003cuserId>`\n- `phoneNumber:\u003cphoneNumber>`\n- `twitter:\u003chandle>`\n- `x:\u003chandle>`","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"content":{"application/json":{"examples":{"Full KYC":{"title":"Full KYC","summary":"Full KYC","description":"Add `dueDiligence` to the KYC data, for full KYC. Full KYC also needs an identity document and a selfie upload.","value":{"dueDiligence":{"employmentStatus":"full-time","expectedYearlyTxVolume":"volume-0-25k","industry":"financial-institution","sourceOfFunds":"salary-disbursement"},"kycData":{"addressOfResidence":{"city":"Berlin","line1":"123 Hauptstrasse","line2":"Apt 5","postalCode":"10115","stateOrRegion":"Berlin"},"email":"johnd@example.com","identityDocument":{"issuingCountryCode":"DE","number":"AS12321","type":"passport"},"ipAddresses":["203.0.113.1"],"nationality":"DE"},"userDetails":{"countryOfResidence":"DE","dateOfBirth":"1995-01-01","firstName":"John","lastName":"Doe"}}},"Light KYC":{"title":"Light KYC","summary":"Light KYC","description":"Add KYC data: nationality, address, email, identity document and IP addresses.","value":{"kycData":{"addressOfResidence":{"city":"Berlin","line1":"123 Hauptstrasse","line2":"Apt 5","postalCode":"10115","stateOrRegion":"Berlin"},"email":"johnd@example.com","identityDocument":{"issuingCountryCode":"DE","number":"AS12321","type":"passport"},"ipAddresses":["203.0.113.1"],"nationality":"DE"},"userDetails":{"countryOfResidence":"DE","dateOfBirth":"1995-01-01","firstName":"John","lastName":"Doe"}}},"Minimal Personal Data":{"title":"Minimal Personal Data","summary":"Minimal Personal Data","description":"Register the name, date of birth and country of residence of a user.","value":{"userDetails":{"countryOfResidence":"DE","dateOfBirth":"1995-01-01","firstName":"John","lastName":"Doe"}}},"US Resident":{"title":"US Resident","summary":"US Resident","description":"Full KYC for a US resident. A US resident needs a US state code, a phone number and an SSN as `identityDocument`. `dueDiligence` also needs `estimatedYearlyIncome`.","value":{"dueDiligence":{"employmentStatus":"full-time","estimatedYearlyIncome":"income-50k-100k","expectedYearlyTxVolume":"volume-0-25k","industry":"financial-institution","sourceOfFunds":"salary-disbursement"},"kycData":{"addressOfResidence":{"city":"New York","line1":"123 Main Street","line2":"Apt 4B","postalCode":"10001","stateOrRegion":"NY"},"email":"jane.doe@example.com","identityDocument":{"issuingCountryCode":"US","number":"123-45-6789","type":"ssn"},"ipAddresses":["203.0.113.1"],"nationality":"US","phoneNumber":"+12125550123"},"userDetails":{"countryOfResidence":"US","dateOfBirth":"1990-01-15","firstName":"Jane","lastName":"Doe"}}}},"schema":{"properties":{"dueDiligence":{"oneOf":[{"type":"object","title":"Non-US residents","description":"Optional due diligence information for compliance purposes","required":["employmentStatus","industry","sourceOfFunds"],"example":{"employmentStatus":"full-time","expectedYearlyTxVolume":"volume-25k-75k","industry":"financial-institution","sourceOfFunds":"salary-disbursement"},"properties":{"employmentStatus":{"description":"User's current employment status","enum":["contractual","full-time","part-time","retired","self-employed","student","unemployed"],"examples":["full-time"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.0.employmentStatus","typeLabel":"enum\u003cstring>"},"industry":{"description":"Industry in which the user is employed or conducts business","enum":["accommodation-food-services","administrative-support-waste-management-remediation-services","adult-entertainment","agriculture-forestry-fishing-hunting","arts-entertainment-recreation","auctions","automobiles","blockchain","construction","crypto","drugs","e-commerce","educational-services","export-import","financial-institution","gambling","health-care-social-assistance","hedge-fund","information","insurance","investment","management-of-companies-enterprises","manufacturing","market-maker","mining","money-service-business","non-profit","other-services","precious-metals","professional-scientific-technical-services","public-administration","real-estate-rental-leasing","registered-investment-advisor","retail-trade","shell-bank","sto-issuer","transportation-warehousing","travel-transport","utilities","weapons","wholesale-trade"],"examples":["financial-institution"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.0.industry","typeLabel":"enum\u003cstring>"},"sourceOfFunds":{"description":"Primary source of the user's funds","enum":["business-dividends-profits","government-benefits","inheritance-distribution","investment-returns","loan-disbursement","property-sale","salary-disbursement","savings-personal-funds"],"examples":["salary-disbursement"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.0.sourceOfFunds","typeLabel":"enum\u003cstring>"},"expectedYearlyTxVolume":{"default":"volume-0-25k","description":"User's expected yearly transaction volume range in USD","enum":["volume-0-25k","volume-25k-75k","volume-75k-150k","volume-above-150k"],"examples":["volume-25k-75k"],"type":"string","uniqueKey":"dueDiligence.oneOf.0.expectedYearlyTxVolume","typeLabel":"enum\u003cstring>"}},"uniqueKey":"dueDiligence.oneOf.0","typeLabel":"Non-US residents · object"},{"type":"object","title":"US residents","description":"Optional due diligence information for compliance purposes","required":["employmentStatus","estimatedYearlyIncome","industry","sourceOfFunds"],"example":{"employmentStatus":"full-time","estimatedYearlyIncome":"income-50k-100k","expectedYearlyTxVolume":"volume-25k-75k","industry":"financial-institution","sourceOfFunds":"salary-disbursement"},"properties":{"employmentStatus":{"description":"User's current employment status","enum":["contractual","full-time","part-time","retired","self-employed","student","unemployed"],"examples":["full-time"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.1.employmentStatus","typeLabel":"enum\u003cstring>"},"estimatedYearlyIncome":{"description":"User's estimated yearly income range in USD","enum":["income-0-50k","income-100k-250k","income-250k-500k","income-500k-750k","income-50k-100k","income-750k-1mil","income-above-1mil"],"examples":["income-50k-100k"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.1.estimatedYearlyIncome","typeLabel":"enum\u003cstring>"},"industry":{"description":"Industry in which the user is employed or conducts business","enum":["accommodation-food-services","administrative-support-waste-management-remediation-services","adult-entertainment","agriculture-forestry-fishing-hunting","arts-entertainment-recreation","auctions","automobiles","blockchain","construction","crypto","drugs","e-commerce","educational-services","export-import","financial-institution","gambling","health-care-social-assistance","hedge-fund","information","insurance","investment","management-of-companies-enterprises","manufacturing","market-maker","mining","money-service-business","non-profit","other-services","precious-metals","professional-scientific-technical-services","public-administration","real-estate-rental-leasing","registered-investment-advisor","retail-trade","shell-bank","sto-issuer","transportation-warehousing","travel-transport","utilities","weapons","wholesale-trade"],"examples":["financial-institution"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.1.industry","typeLabel":"enum\u003cstring>"},"sourceOfFunds":{"description":"Primary source of the user's funds","enum":["business-dividends-profits","government-benefits","inheritance-distribution","investment-returns","loan-disbursement","property-sale","salary-disbursement","savings-personal-funds"],"examples":["salary-disbursement"],"type":"string","isRequired":true,"uniqueKey":"dueDiligence.oneOf.1.sourceOfFunds","typeLabel":"enum\u003cstring>"},"expectedYearlyTxVolume":{"default":"volume-0-25k","description":"User's expected yearly transaction volume range in USD","enum":["volume-0-25k","volume-25k-75k","volume-75k-150k","volume-above-150k"],"examples":["volume-25k-75k"],"type":"string","uniqueKey":"dueDiligence.oneOf.1.expectedYearlyTxVolume","typeLabel":"enum\u003cstring>"}},"uniqueKey":"dueDiligence.oneOf.1","typeLabel":"US residents · object"}],"uniqueKey":"dueDiligence","typeLabel":"Non-US residents · object | US residents · object"},"kycData":{"description":"Optional KYC data for identity verification","examples":[{"addressOfResidence":{"city":"New York","line1":"123 Main Street","line2":"Apt 4B","postalCode":"10001","stateOrRegion":"NY"},"email":"john.doe@example.com","identityDocument":{"issuingCountryCode":"US","number":"123-45-6789","type":"ssn"},"nationality":"US","phoneNumber":"+1234567890"}],"properties":{"addressOfResidence":{"description":"Physical address of residence","examples":[{"city":"New York","line1":"123 Main Street","line2":"Apt 4B","postalCode":"10001","stateOrRegion":"NY"}],"properties":{"city":{"description":"City name","examples":["New York"],"maxLength":50,"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.addressOfResidence.city","typeLabel":"string"},"line1":{"description":"Primary address line (street address)","examples":["123 Main Street"],"maxLength":200,"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.addressOfResidence.line1","typeLabel":"string"},"postalCode":{"description":"Postal or ZIP code","examples":["10001"],"maxLength":20,"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.addressOfResidence.postalCode","typeLabel":"string"},"stateOrRegion":{"description":"State, province, or region","examples":["NY"],"maxLength":50,"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.addressOfResidence.stateOrRegion","typeLabel":"string"},"line2":{"description":"Secondary address line (apartment, suite, etc.)","examples":["Apt 4B"],"maxLength":60,"type":"string","uniqueKey":"kycData.addressOfResidence.line2","typeLabel":"string"}},"required":["city","line1","postalCode","stateOrRegion"],"type":"object","isRequired":true,"uniqueKey":"kycData.addressOfResidence","typeLabel":"object"},"email":{"description":"User's email address, required for verification","examples":["john.doe@example.com"],"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","type":"string","isRequired":true,"uniqueKey":"kycData.email","typeLabel":"string\u003cemail>"},"identityDocument":{"oneOf":[{"type":"object","title":"EU/EEA residents","description":"Identity document. The accepted types depend on the user's country of residence and on the document's issuing country; select the option matching their residency.","required":["issuingCountryCode","number","type"],"example":{"issuingCountryCode":"ES","number":"AB123456","type":"passport"},"properties":{"issuingCountryCode":{"description":"Issuing country code of the identity document","examples":["ES"],"maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$","type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.0.issuingCountryCode","typeLabel":"string"},"number":{"description":"Identity document number","examples":["AB123456"],"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.0.number","typeLabel":"string"},"type":{"description":"Type of identity document for EU/EEA residents: passport, or id issued by an EU/EEA country or Switzerland (CH). Spain (ES) and Germany (DE) residents can also use a residency-permit issued by their country of residence. Spain (ES) residents cannot use a passport issued by Spain.","enum":["id","passport","residency-permit"],"examples":["passport"],"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.0.type","typeLabel":"enum\u003cstring>"}},"uniqueKey":"kycData.identityDocument.oneOf.0","typeLabel":"EU/EEA residents · object"},{"type":"object","title":"US residents","description":"Identity document. The accepted types depend on the user's country of residence and on the document's issuing country; select the option matching their residency.","required":["issuingCountryCode","number","type"],"example":{"issuingCountryCode":"US","number":"123-45-6789","type":"ssn"},"properties":{"issuingCountryCode":{"description":"Issuing country code of the identity document","examples":["US"],"maxLength":2,"minLength":2,"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.1.issuingCountryCode","typeLabel":"string"},"number":{"description":"Identity document number. For SSN, must be in XXX-XX-XXXX format.","examples":["123-45-6789"],"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.1.number","typeLabel":"string"},"type":{"description":"Type of identity document for US residents. Only SSN is accepted.","enum":["ssn"],"examples":["ssn"],"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.1.type","typeLabel":"enum\u003cstring>"}},"uniqueKey":"kycData.identityDocument.oneOf.1","typeLabel":"US residents · object"},{"type":"object","title":"Non-EU/EEA, non-US residents","description":"Identity document. The accepted types depend on the user's country of residence and on the document's issuing country; select the option matching their residency.","required":["issuingCountryCode","number","type"],"example":{"issuingCountryCode":"BR","number":"AB123456","type":"passport"},"properties":{"issuingCountryCode":{"description":"Issuing country code of the identity document","examples":["BR"],"maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$","type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.2.issuingCountryCode","typeLabel":"string"},"number":{"description":"Identity document number","examples":["AB123456"],"minLength":1,"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.2.number","typeLabel":"string"},"type":{"description":"Type of identity document for non-EU/EEA and non-US residents: passport, or id issued by an EU/EEA country or Switzerland (CH). Mexico (MX), Colombia (CO), Argentina (AR) and Canada (CA) residents can also use an id issued by their country of residence.","enum":["id","passport"],"examples":["passport"],"type":"string","isRequired":true,"uniqueKey":"kycData.identityDocument.oneOf.2.type","typeLabel":"enum\u003cstring>"}},"uniqueKey":"kycData.identityDocument.oneOf.2","typeLabel":"Non-EU/EEA, non-US residents · object"}],"uniqueKey":"kycData.identityDocument","typeLabel":"EU/EEA residents · object | US residents · object | Non-EU/EEA, non-US residents · object"},"ipAddresses":{"default":[],"items":{"type":"string","uniqueKey":"kycData.ipAddresses.items.[INDEX]","typeLabel":"string"},"type":"array","uniqueKey":"kycData.ipAddresses","typeLabel":"string[]"},"nationality":{"description":"User's nationality in ISO 3166-1 alpha-2 format","examples":["US"],"maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$","type":"string","uniqueKey":"kycData.nationality","typeLabel":"string"},"phoneNumber":{"default":"","description":"User's phone number. Required for US residents","examples":["+1234567890"],"type":"string","uniqueKey":"kycData.phoneNumber","typeLabel":"string"}},"required":["addressOfResidence","email"],"type":"object","uniqueKey":"kycData","typeLabel":"object"},"userDetails":{"description":"Optional user details including name, date of birth, and country of residence","examples":[{"countryOfResidence":"US","dateOfBirth":"1990-01-15","firstName":"John","lastName":"Doe"}],"properties":{"countryOfResidence":{"description":"User's country of residence in ISO 3166-1 alpha-2 format","examples":["US"],"maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$","type":"string","isRequired":true,"uniqueKey":"userDetails.countryOfResidence","typeLabel":"string"},"dateOfBirth":{"description":"User's date of birth in YYYY-MM-DD format","examples":["1990-01-15"],"maxLength":10,"minLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string","isRequired":true,"uniqueKey":"userDetails.dateOfBirth","typeLabel":"string"},"firstName":{"type":"string","description":"User's legal first name","maxLength":50,"minLength":1,"pattern":"^[\\p{L}\\p{M}\\s'.-]+$","example":"John","isRequired":true,"uniqueKey":"userDetails.firstName","typeLabel":"string"},"lastName":{"type":"string","description":"User's legal last name","maxLength":60,"minLength":1,"pattern":"^[\\p{L}\\p{M}\\s'.-]+$","example":"Doe","isRequired":true,"uniqueKey":"userDetails.lastName","typeLabel":"string"}},"required":["countryOfResidence","dateOfBirth","firstName","lastName"],"type":"object","uniqueKey":"userDetails","typeLabel":"object"},"verificationHistory":{"description":"Optional verification timestamps.","examples":[{"idVerificationTimestamp":"2024-01-15T10:30:00Z","livenessVerificationTimestamp":"2024-01-15T10:32:00Z"}],"properties":{"idVerificationTimestamp":{"description":"ISO 8601 timestamp of when ID verification was completed","example":"2024-01-15T10:30:00.000Z","examples":["2024-01-15T10:30:00Z"],"format":"date-time","type":"string","isRequired":true,"uniqueKey":"verificationHistory.idVerificationTimestamp","typeLabel":"string\u003cdate-time>"},"livenessVerificationTimestamp":{"description":"ISO 8601 timestamp of when liveness verification was completed","example":"2024-01-15T10:30:00.000Z","examples":["2024-01-15T10:32:00Z"],"format":"date-time","type":"string","isRequired":true,"uniqueKey":"verificationHistory.livenessVerificationTimestamp","typeLabel":"string\u003cdate-time>"}},"required":["idVerificationTimestamp","livenessVerificationTimestamp"],"type":"object","uniqueKey":"verificationHistory","typeLabel":"object"}},"type":"object","uniqueKey":"","typeLabel":"object"},"exampleType":"examples"}},"required":true,"exampleType":"examples"},"responses":{"31e49521-89ef-4180-bc9e-ce6019b67246":{"content":{"application/json":{"schema":{"properties":{"dueDiligence":{"description":"Whether due diligence data has been provided","examples":[false],"type":"boolean","isRequired":true,"uniqueKey":"dueDiligence","typeLabel":"boolean"},"kycData":{"description":"Whether KYC data has been provided","examples":[false],"type":"boolean","isRequired":true,"uniqueKey":"kycData","typeLabel":"boolean"},"userDetails":{"description":"Whether user details have been provided","examples":[true],"type":"boolean","isRequired":true,"uniqueKey":"userDetails","typeLabel":"boolean"},"verificationHistory":{"description":"Whether verification history has been provided","examples":[false],"type":"boolean","isRequired":true,"uniqueKey":"verificationHistory","typeLabel":"boolean"},"email":{"description":"User's email address","examples":["john.doe@example.com"],"type":"string","uniqueKey":"email","typeLabel":"string"},"legalDocuments":{"description":"List of accepted legal documents","examples":[[{"acceptedAt":"2023-01-01T00:00:00.000Z","isValidVersion":true,"type":"crossmint-privacy-policy"}]],"items":{"properties":{"acceptedAt":{"description":"ISO 8601 timestamp of when the document was accepted","examples":["2023-01-01T00:00:00.000Z"],"type":"string","isRequired":true,"uniqueKey":"legalDocuments.items.[INDEX].acceptedAt","typeLabel":"string"},"isValidVersion":{"description":"Indicates whether the signed version of the document is not outdated","examples":[true],"type":"boolean","isRequired":true,"uniqueKey":"legalDocuments.items.[INDEX].isValidVersion","typeLabel":"boolean"},"type":{"description":"The type of the legal document","enum":["crossmint-privacy-policy","crossmint-terms-of-service"],"examples":["crossmint-privacy-policy"],"type":"string","isRequired":true,"uniqueKey":"legalDocuments.items.[INDEX].type","typeLabel":"enum\u003cstring>"}},"required":["acceptedAt","isValidVersion","type"],"type":"object","uniqueKey":"legalDocuments.items.[INDEX]","typeLabel":"object"},"type":"array","uniqueKey":"legalDocuments","typeLabel":"object[]"},"phoneNumber":{"description":"User's phone number","examples":["+1234567890"],"type":"string","uniqueKey":"phoneNumber","typeLabel":"string"},"userId":{"description":"Unique user identifier","examples":["usr_1234567890"],"type":"string","uniqueKey":"userId","typeLabel":"string"}},"required":["dueDiligence","kycData","userDetails","verificationHistory"],"type":"object","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"dueDiligence":false,"kycData":false,"userDetails":true,"verificationHistory":false,"email":"john.doe@example.com","legalDocuments":[{"acceptedAt":"2023-01-01T00:00:00.000Z","isValidVersion":true,"type":"crossmint-privacy-policy"}],"phoneNumber":"+1234567890","userId":"usr_1234567890"}}},"exampleType":"generated"}},"description":"User updated","exampleType":"generated"},"5ec984bf-113e-4869-8e85-725371da061e":{"content":{"application/json":{"schema":{"properties":{"dueDiligence":{"description":"Whether due diligence data has been provided","examples":[false],"type":"boolean","isRequired":true,"uniqueKey":"dueDiligence","typeLabel":"boolean"},"kycData":{"description":"Whether KYC data has been provided","examples":[false],"type":"boolean","isRequired":true,"uniqueKey":"kycData","typeLabel":"boolean"},"userDetails":{"description":"Whether user details have been provided","examples":[true],"type":"boolean","isRequired":true,"uniqueKey":"userDetails","typeLabel":"boolean"},"verificationHistory":{"description":"Whether verification history has been provided","examples":[false],"type":"boolean","isRequired":true,"uniqueKey":"verificationHistory","typeLabel":"boolean"},"email":{"description":"User's email address","examples":["john.doe@example.com"],"type":"string","uniqueKey":"email","typeLabel":"string"},"legalDocuments":{"description":"List of accepted legal documents","examples":[[{"acceptedAt":"2023-01-01T00:00:00.000Z","isValidVersion":true,"type":"crossmint-privacy-policy"}]],"items":{"properties":{"acceptedAt":{"description":"ISO 8601 timestamp of when the document was accepted","examples":["2023-01-01T00:00:00.000Z"],"type":"string","isRequired":true,"uniqueKey":"legalDocuments.items.[INDEX].acceptedAt","typeLabel":"string"},"isValidVersion":{"description":"Indicates whether the signed version of the document is not outdated","examples":[true],"type":"boolean","isRequired":true,"uniqueKey":"legalDocuments.items.[INDEX].isValidVersion","typeLabel":"boolean"},"type":{"description":"The type of the legal document","enum":["crossmint-privacy-policy","crossmint-terms-of-service"],"examples":["crossmint-privacy-policy"],"type":"string","isRequired":true,"uniqueKey":"legalDocuments.items.[INDEX].type","typeLabel":"enum\u003cstring>"}},"required":["acceptedAt","isValidVersion","type"],"type":"object","uniqueKey":"legalDocuments.items.[INDEX]","typeLabel":"object"},"type":"array","uniqueKey":"legalDocuments","typeLabel":"object[]"},"phoneNumber":{"description":"User's phone number","examples":["+1234567890"],"type":"string","uniqueKey":"phoneNumber","typeLabel":"string"},"userId":{"description":"Unique user identifier","examples":["usr_1234567890"],"type":"string","uniqueKey":"userId","typeLabel":"string"}},"required":["dueDiligence","kycData","userDetails","verificationHistory"],"type":"object","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"dueDiligence":false,"kycData":false,"userDetails":true,"verificationHistory":false,"email":"john.doe@example.com","legalDocuments":[{"acceptedAt":"2023-01-01T00:00:00.000Z","isValidVersion":true,"type":"crossmint-privacy-policy"}],"phoneNumber":"+1234567890","userId":"usr_1234567890"}}},"exampleType":"generated"}},"description":"User created","exampleType":"generated"}},"security":{"80beb2ea-b8ee-493f-8588-217448718a55":{"apiKey":{"description":"API key required for authentication","in":"header","name":"X-API-KEY","type":"apiKey","scopes":[],"schemeName":"apiKey"}}},"servers":{"6b623d87-f9d6-4061-b2e9-f38de7501e68":{"description":"Staging environment (testnets)","url":"https://staging.crossmint.com/api"},"04fd49ba-e38c-4101-82b6-f5e8c12c7a9c":{"description":"Production environment (mainnets)","url":"https://www.crossmint.com/api"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"description":"API key required for authentication","in":"header","name":"X-API-KEY","type":"apiKey","scopes":[],"schemeName":"apiKey"},"schema":{"title":"X-API-KEY","type":"string","description":"API key required for authentication","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"apiKey","name":"X-API-KEY"}],"title":"apiKey"}]},"originalFileLocation":"api-reference/_open-api/Users.json"},"subdomain":"crossmint","siteName":"Crossmint Docs","title":"Create or Update User - Crossmint Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-27T11:35:38.716Z","originalFileLocation":"api-reference/users/upsert-user.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create or update a user and their personal data by user locator. If the user doesn\u0026#x27;t exist, they will be created. API scope required: users.create\">\u003cmeta data-mint-head name=\"application-name\" content=\"Crossmint Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create or Update User - Crossmint Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create or update a user and their personal data by user locator. If the user doesn\u0026#x27;t exist, they will be created. API scope required: users.create\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Crossmint Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.crossmint.com/api-reference/users/upsert-user\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://crossmint.mintlify.site/_mintlify/api/og/v2?division=REST\u0026amp;title=Create+or+Update+User\u0026amp;description=Create+or+update+a+user+and+their+personal+data+by+user+locator.+If+the+user+doesn%27t+exist%2C+they+will+be+created.%0A%0A**API+scope+required**%3A+%60users.create%60\u0026amp;theme=b8bba0b38c114479513683ad\u0026amp;signature=954fbf3944fdb143b671ec665d80b59c31f963d4396a04231757584f0599adc9\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create or Update User - Crossmint Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create or update a user and their personal data by user locator. If the user doesn\u0026#x27;t exist, they will be created. API scope required: users.create\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://crossmint.mintlify.site/_mintlify/api/og/v2?division=REST\u0026amp;title=Create+or+Update+User\u0026amp;description=Create+or+update+a+user+and+their+personal+data+by+user+locator.+If+the+user+doesn%27t+exist%2C+they+will+be+created.%0A%0A**API+scope+required**%3A+%60users.create%60\u0026amp;theme=b8bba0b38c114479513683ad\u0026amp;signature=954fbf3944fdb143b671ec665d80b59c31f963d4396a04231757584f0599adc9\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/crossmint/-1hhMU0vchFPUD3H/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Crossmint Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#36b37e\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.crossmint.com/api-reference/users/upsert-user\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/users/upsert-user.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.crossmint.com/#organization\",\"name\":\"Crossmint Docs\",\"url\":\"https://docs.crossmint.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/crossmint/a8gPOTKEuVFcSfC3/logo/crossmint-light.png?fit=max\u0026auto=format\u0026n=a8gPOTKEuVFcSfC3\u0026q=85\u0026s=8c2671e4c8f7da6956e1508bd68c2928\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.crossmint.com#website\",\"name\":\"Crossmint Docs\",\"url\":\"https://docs.crossmint.com\",\"publisher\":{\"@id\":\"https://docs.crossmint.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.crossmint.com/api-reference/users/upsert-user#webpage\",\"url\":\"https://docs.crossmint.com/api-reference/users/upsert-user\",\"name\":\"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\",\"dateModified\":\"2026-01-27T11:35:38.716Z\",\"isPartOf\":{\"@id\":\"https://docs.crossmint.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.crossmint.com/api-reference/users/upsert-user#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.crossmint.com/api-reference/users/upsert-user#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Crossmint Docs\",\"item\":\"https://docs.crossmint.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create or Update User\",\"item\":\"https://docs.crossmint.com/api-reference/users/upsert-user\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.crossmint.com/api-reference/users/upsert-user#apireference\",\"headline\":\"Create or Update User\",\"name\":\"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\",\"url\":\"https://docs.crossmint.com/api-reference/users/upsert-user\",\"mainEntityOfPage\":{\"@id\":\"https://docs.crossmint.com/api-reference/users/upsert-user#webpage\"},\"dateModified\":\"2026-01-27T11:35:38.716Z\",\"publisher\":{\"@id\":\"https://docs.crossmint.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.crossmint.com#website\"}}]}\u003c/script>","agentPointerHref":"/api-reference/users/upsert-user.md","siteName":"Crossmint Docs","nav":{"global":null,"tabs":[{"tab":"Platform Overview","pages":[{"title":"Platform Overview","href":"/introduction/platform-overview"}]},{"tab":"Embedded Finance","menu":[{"item":"Wallets","pages":[{"title":"Wallets","href":"/wallets/overview"}]},{"item":"Onramp","pages":[{"title":"Onramp","href":"/onramp/overview"}]},{"item":"Offramp","pages":[{"title":"Offramp","href":"/offramp/overview"}]},{"item":"Checkout","pages":[{"title":"Checkout","href":"/payments/introduction"}]}],"pages":[{"title":"Embedded Finance","href":"/wallets/overview"}]},{"tab":"Money Movement","pages":[{"title":"Money Movement","href":"/stablecoin-orchestration/overview"}]},{"tab":"Agentic Payments","pages":[{"title":"Agentic Payments","href":"/agents/overview"}]},{"tab":"Identity","groups":[{"group":"Introduction","pages":[{"title":"Overview","href":"/identity/overview"}]},{"group":"Quickstarts ⚡","pages":[{"title":"Quickstart ⚡","sidebarTitle":"REST API","href":"/identity/quickstart"}]},{"group":"Guides","pages":[{"title":"Register User Data","href":"/identity/register-user-data"},{"title":"Data Requirements","href":"/identity/data-requirements"},{"title":"UI Customization","href":"/identity/ui-customization"},{"title":"Failure Reasons","description":"Reference for the machine-readable codes returned on a rejected identity verification","href":"/identity/failure-reasons"}]},{"group":"API Reference","pages":[{"group":"REST","icon":"brackets-curly","pages":[{"openapi":"api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}","title":"Create or Update User","href":"/api-reference/users/upsert-user"},{"openapi":"api-reference/_open-api/Users.json GET /2025-06-09/users/{userLocator}","title":"Get a User","description":"Get a user by its id\n\n**API scope required**: `users.read`","href":"/api-reference/users/get-user"},{"openapi":"api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}/legal-documents","title":"Accept Legal Document","href":"/api-reference/users/accept-legal-document"},{"openapi":"api-reference/_open-api/Users.json POST /2025-06-09/documents","title":"Upload a User Document","href":"/api-reference/users/upload-document"},{"openapi":"api-reference/_open-api/Users.json GET /2025-06-09/documents/{documentId}","title":"Get a User Document by ID","href":"/api-reference/users/get-document"},{"openapi":"api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}/identity-verification","title":"Trigger Identity Verification","href":"/api-reference/users/trigger-identity-verification"},{"openapi":"api-reference/_open-api/Users.json GET /2025-06-09/users/{userLocator}/identity-verification","title":"Get Identity Verification Status","href":"/api-reference/users/get-identity-verification"},{"openapi":"api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}/linked-wallets/{address}","title":"Link External Wallet to User","href":"/api-reference/users/link-wallet"},{"openapi":"api-reference/_open-api/Users.json GET /2025-06-09/users/{userLocator}/linked-wallets/{address}","title":"Get Linked External Wallet","href":"/api-reference/users/get-linked-wallet"},{"openapi":"api-reference/_open-api/Users.json DELETE /2025-06-09/users/{userLocator}/linked-wallets/{address}","title":"Unlink External Wallet from User","href":"/api-reference/users/unlink-wallet"}]}]}]},{"tab":"Others","menu":[{"item":"Tokenization","pages":[{"title":"Tokenization","href":"/tokenization/introduction"}]}],"pages":[{"title":"Others","href":"/tokenization/introduction"}]}]},"basePath":"","title":"Create or Update User - Crossmint Docs","deploymentId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","buildId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BtG4DSkw.js","snippetPresets-C1k1xDhp.js","utils-PMJoEt4Y.js","style-to-object-BY3JEAdk.js","utils-DW3Pr7Jq.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DIISLO2w.js","conditional-requirements-CFM0id0Q.js","cloneDeep-BErNCZCm.js","_Uint8Array-f0PCu9f_.js","isObject-FP1Yky1u.js","ApiExamples-OjY-8mqu.js","usePlaygroundInputsStore-B2HS2hUb.js","shallow-DVFuuIDQ.js","isEqual-DG0UKiQC.js","CodeSnippets-Cy6FBgwN.js","CodeSnippet-D1PtG8ed.js","getApiPlaygroundDisplay-Dkx2eNtL.js","Page-C8Cg25if.js","DynamicMarkdown-BvJIe00T.js","SectionHeading-B0rKYV8d.js","icon-yclzBff4.js","MethodPill-DxA11cCF.js","getPastedJson-CpkIDpMk.js","DuplicateIcon-CFCQNJ-D.js","axios-CsQoIw0U.js","Markdown-CK5C-fmV.js","AssistantPageLink-Cw134Dd-.js","dist-3xM3Qrc7.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}