> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create user
> Create a new user.
export const RestEndpointSubjects = ({subjects = []}) => {
const subjectToIconMap = {
'client': 'browser',
'user:individual': 'user',
'user:business': 'briefcase'
};
if (subjects.length === 0) {
return null;
}
return <>
{subjects.map(subject =>
{subject}
)}
;
};
**Create user** registers a new user with their identity and compliance information.
Users must read and agree with the [general Terms of Service](../terms-of-service/introduction#general-terms) associated with their country of residence, and you must provide it in the `termsOfService` field of the request.
You can optionally include custom [entity metadata](../../entity-metadata) in the `metadata` field to store your own business data (e.g., external IDs, settings, tracking parameters). If not provided during creation, you can add it later using [Set metadata](../metadata/set-metadata) endpoint.
The `X-Uphold-User-Ip` [user context](../../headers#user-context) header is **mandatory** to record the user's IP when accepting the Terms of Service.
## OpenAPI
````yaml _media/specs/core-openapi.mintlify.json post /core/users
openapi: 3.1.0
info:
version: 0.1.0
title: Core API
description: >-
The Core API provides essential building blocks that empower businesses to
embed financial services into their applications.
contact:
name: Uphold API Team
email: developers@uphold.com
url: https://developer.uphold.com
servers:
- url: https://api.enterprise.sandbox.uphold.com
description: Sandbox
- url: https://api.enterprise.uphold.com
description: Production
security:
- OAuth2: []
tags:
- name: Authentication
description: Authentication.
- name: Countries
description: Countries.
- name: Users
description: Users.
- name: KYC
description: Individual User's KYC.
- name: KYB
description: Business User's KYB.
- name: Capabilities
description: User capabilities.
- name: Terms of service
description: User terms of service.
- name: Files
description: Files.
- name: Assets
description: Assets, networks and rails.
- name: Accounts
description: Accounts.
- name: External accounts
description: External accounts.
- name: Transactions
description: Transactions.
- name: Portfolio
description: Portfolio.
- name: Statements
description: Statements.
- name: Metadata
description: Metadata.
- name: Webhooks
description: Webhooks.
paths:
/core/users:
post:
tags:
- Users
summary: Create user
description: Create a new user.
operationId: core.create-user
requestBody:
$ref: '#/components/requestBodies/create-user-request-body'
responses:
'201':
$ref: '#/components/responses/create-user-response'
'409':
$ref: '#/components/responses/create-user-conflict-response'
security:
- OAuth2:
- core.users:create
components:
requestBodies:
create-user-request-body:
content:
application/json:
schema:
type: object
properties:
type:
description: The type of the user.
type: string
default: individual
discriminator:
propertyName: type
mapping:
individual:
$ref: '#/components/schemas/create-user-type-individual'
business:
$ref: '#/components/schemas/create-user-type-business'
oneOf:
- $ref: '#/components/schemas/create-user-type-individual'
title: Individual
- $ref: '#/components/schemas/create-user-type-business'
title: Business
required:
- type
examples:
Create Individual User:
value:
type: individual
email: john.doe@uphold.com
termsOfService: general-gb-fca
country: GB
subdivision: GB-MAN
citizenshipCountry: GB
metadata:
externalId: 123
Create Business User:
value:
type: business
email: acme-corp@uphold.com
termsOfService: general-gb-fca
country: GB
subdivision: GB-MAN
legalEntityType: private-limited-company
metadata:
externalId: 123
responses:
create-user-response:
description: User created.
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/user'
errors:
description: >-
Additional contextual errors that occurred while processing
the request.
type: object
properties:
metadata:
allOf:
- $ref: '#/components/schemas/error'
- description: Error related to metadata processing.
required:
- user
examples:
Individual User Created:
value:
user:
id: cd21b26d-35d2-408a-9201-b8fdbef7a604
type: individual
email: john.doe@uphold.com
citizenshipCountry: GB
address:
country: GB
subdivision: GB-MAN
createdAt: '2024-03-13T20:20:39.000Z'
updatedAt: '2024-03-13T20:20:39.000Z'
Business User Created:
value:
user:
id: 4237b7f2-4658-4183-ab56-b2fc4ecd7b7f
type: business
email: acme-corp@uphold.com
address:
country: GB
subdivision: GB-MAN
createdAt: '2024-03-13T20:20:39.000Z'
updatedAt: '2024-03-13T20:20:39.000Z'
User Created With Metadata Error:
value:
user:
id: cd21b26d-35d2-408a-9201-b8fdbef7a604
type: individual
email: john.doe@uphold.com
citizenshipCountry: GB
address:
country: GB
subdivision: GB-MAN
createdAt: '2024-03-13T20:20:39.000Z'
updatedAt: '2024-03-13T20:20:39.000Z'
errors:
metadata:
code: content_too_large
message: >-
The entity metadata size is greater than maximum size
limit
details:
threshold:
unit: characters
limit: 1024
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
create-user-conflict-response:
description: Business logic error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Citizenship Country Not Supported:
value:
code: country_not_supported
message: The country is not supported
details:
context: body
property: citizenshipCountry
Country Not Supported:
value:
code: country_not_supported
message: The country is not supported
details:
context: body
property: country
Email Incorrect or Disallowed:
value:
code: email_incorrect_or_disallowed
message: The email is incorrect or disallowed
Email Already Exists:
value:
code: email_already_exists
message: The provided email is already in use by another user
Invalid Partner Onboarded At:
value:
code: date_invalid
message: The date must be in the past
details:
context: body
property: partnerOnboardedAt
rule: difference-greater-than-threshold
threshold:
limit: 0
Missing User Context:
value:
code: operation_not_allowed
message: Request not allowed due to missing user context
details:
reasons:
- missing-user-ip-header
Subdivision Not Supported:
value:
code: subdivision_not_supported
message: The subdivision is not supported
details:
context: body
property: subdivision
Subdivision Required For Country:
value:
code: subdivision_required
message: The subdivision is required for the selected country
details:
context: body
property: subdivision
Terms Of Service Mismatch:
value:
code: terms_of_service_mismatch
message: >-
The terms of service passed in the request does not match the
one that should have been accepted
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
schemas:
create-user-type-individual:
type: object
properties:
type:
description: The type of the user.
type: string
enum:
- individual
email:
description: The email address.
type: string
format: email
maxLength: 254
country:
allOf:
- $ref: '#/components/schemas/country-code-for-request'
- description: The country of residency.
subdivision:
allOf:
- $ref: '#/components/schemas/subdivision-code-for-request'
- description: The subdivision of residency.
citizenshipCountry:
allOf:
- $ref: '#/components/schemas/country-code-for-request'
- description: The citizenship country.
termsOfService:
allOf:
- $ref: '#/components/schemas/terms-of-service-code-general'
- description: The general terms of service the user agreed to.
partnerOnboardedAt:
description: The date and time when the user was onboarded by the partner.
type: string
format: date-time
deprecated: true
required:
- type
- email
- country
- citizenshipCountry
- termsOfService
create-user-type-business:
type: object
properties:
type:
description: The type of the user.
type: string
enum:
- business
email:
description: The email address.
type: string
format: email
maxLength: 255
country:
allOf:
- $ref: '#/components/schemas/country-code-for-request'
- description: The country of residency.
subdivision:
allOf:
- $ref: '#/components/schemas/subdivision-code-for-request'
- description: The subdivision of residency.
legalEntityType:
type: string
description: Business legal form/classification
enum:
- government-entity
- non-profit
- partnership
- private-limited-company
- public-company
- sole-proprietor
termsOfService:
allOf:
- $ref: '#/components/schemas/terms-of-service-code-general'
- description: The general terms of service the user agreed to.
partnerOnboardedAt:
description: The date and time when the user was onboarded by the partner.
type: string
format: date-time
deprecated: true
required:
- type
- email
- country
- legalEntityType
- termsOfService
user:
type: object
discriminator:
propertyName: type
mapping:
individual:
$ref: '#/components/schemas/user-type-individual'
business:
$ref: '#/components/schemas/user-type-business'
oneOf:
- $ref: '#/components/schemas/user-type-individual'
title: Individual
- $ref: '#/components/schemas/user-type-business'
title: Business
error:
description: The error information.
type: object
properties:
code:
description: >-
A short string with a brief explanation about the error code
reported.
type: string
message:
description: A human-readable message providing more details about the error.
type: string
details:
description: Additional information about the error reported.
type: object
additionalProperties: true
required:
- code
- message
country-code-for-request:
type: string
pattern: ^[A-Z]{2}$
subdivision-code-for-request:
type: string
pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$
terms-of-service-code-general:
type: string
enum:
- general-us-hq
- general-gb-fca
- general-pt-bop
- general-lt-fcs
- general-bs-scb
user-type-individual:
type: object
properties:
id:
description: The id of the user.
type: string
format: uuid
type:
description: The type of the user.
type: string
enum:
- individual
email:
description: The email address.
type: string
format: email
fullName:
description: The full legal name.
type: string
birthdate:
description: The date of birth.
type: string
citizenshipCountry:
description: The citizenship country.
type: string
address:
allOf:
- $ref: '#/components/schemas/address'
- type: object
required:
- country
partnerOnboardedAt:
description: The date and time when the user was onboarded by the partner.
type: string
format: date-time
deprecated: true
createdAt:
description: The time at which the user was created.
type: string
format: date-time
updatedAt:
description: The time at which the user was last updated.
type: string
format: date-time
required:
- id
- type
- email
- citizenshipCountry
- address
- createdAt
- updatedAt
user-type-business:
type: object
properties:
id:
description: The id of the user.
type: string
format: uuid
type:
description: The type of the user.
type: string
enum:
- business
name:
description: The legal name of the business.
type: string
email:
description: The email address.
type: string
format: email
address:
allOf:
- $ref: '#/components/schemas/address'
- type: object
required:
- country
partnerOnboardedAt:
description: The date and time when the user was onboarded by the partner.
type: string
format: date-time
deprecated: true
createdAt:
description: The time at which the user was created.
type: string
format: date-time
updatedAt:
description: The time at which the user was last updated.
type: string
format: date-time
required:
- id
- type
- email
- createdAt
- updatedAt
address:
description: The address information.
type: object
properties:
country:
description: The country of the address.
type: string
subdivision:
description: The subdivision of the address.
type: string
city:
description: The city of the address.
type: string
line1:
description: The first line of the address.
type: string
line2:
description: The second line of the address.
type: string
postalCode:
description: The postal code of the address.
type: string
securitySchemes:
OAuth2:
type: oauth2
description: OAuth 2.0 authentication.
flows:
clientCredentials:
tokenUrl: /core/oauth2/token
scopes:
core.users:act-on-behalf-of: Grants access to act on behalf of a user
core.users:create: Grants access to create users
core.users:read: Grants access to view users
core.users:delete: Grants access to delete users
core.users.metadata:read: Grants access to view user metadata
core.users.metadata:write: Grants access to modify user metadata
core.kyc:read: Grants access to view KYC processes
core.kyc.profile:update: Grants access to update profile KYC process
core.kyc.address:update: Grants access to update address KYC process
core.kyc.email:update: Grants access to update email KYC process
core.kyc.phone:update: Grants access to update phone KYC process
core.kyc.identity:update: Grants access to update identity KYC process
core.kyc.proof-of-address:update: Grants access to update proof-of-address KYC process
core.kyc.customer-due-diligence:update: Grants access to update customer due diligence KYC process
core.kyc.enhanced-due-diligence:update: Grants access to update enhanced due diligence KYC process
core.kyc.crypto-risk-assessment:update: Grants access to update crypto risk assessment KYC process
core.kyc.self-categorization-statement:update: Grants access to update self-categorization statement KYC process
core.kyc.tax-details:update: Grants access to update tax details KYC process
core.capabilities:read: Grants access to view user capabilities
core.terms-of-service:read: Grants access to view terms of service
core.terms-of-service:accept: Grants access to accept terms of service
core.files:create: Grants access to create files
core.files:read: Grants access to view files
core.files.metadata:read: Grants access to view files metadata
core.files.metadata:write: Grants access to modify files metadata
core.accounts:create: Grants access to create accounts
core.accounts:read: Grants access to view accounts
core.accounts:update: Grants access to update accounts
core.accounts:archive: Grants access to archive accounts
core.accounts:deposit-method: >-
Grants access to deposit method needed for depositing into
accounts
core.accounts:use-test-helpers: Grants access to test helpers of accounts
core.accounts.metadata:read: Grants access to view accounts metadata
core.accounts.metadata:write: Grants access to modify accounts metadata
core.assets:use-test-helpers: Grants access to test helpers of assets
core.external-accounts:create: Grants access to create external accounts
core.external-accounts:read: Grants access to view external accounts
core.external-accounts:update: Grants access to update external accounts
core.external-accounts:delete: Grants access to delete external accounts
core.external-accounts.metadata:read: Grants access to view external accounts metadata
core.external-accounts.metadata:write: Grants access to modify external accounts metadata
core.transactions:create: Grants access to commit quotes
core.transactions:read: Grants access to view transactions
core.transactions.metadata:read: Grants access to view transactions metadata
core.transactions.metadata:write: Grants access to modify transactions metadata
core.transactions.requests-for-information:read: Grants access to view transactions requests for information
core.transactions.requests-for-information:update: Grants access to update transactions requests for information
core.portfolio:read: >-
Grants access to view portfolio overview, performance, and
historical balance
core.statements:read: Grants access to read statements
core.webhooks:management-link: Grants access to create webhook management links
````