---
title: "Create user"
method: POST
path: "/core/users"
tags: ["Users"]
---

# Create user

`POST /core/users`

## Request

- Base URL: `https://api.enterprise.sandbox.uphold.com`
- URL: `https://api.enterprise.sandbox.uphold.com/core/users`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `/core/oauth2/token` scopes: `core.users:create`
- TypeScript: <https://skmtc.dev/uphold/apis/core-api/docs/core/users/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new user.

## Headers

- `X-Uphold-User-Ip` union
  - string, ipv4
  - string, ipv6
- `X-Uphold-User-Agent` string
- `X-Uphold-User-Origin` string
- `X-Uphold-User-Country` string
- `X-Uphold-User-Subdivision` string
- `X-Uphold-User-City` string

## Request body

- union
  - object
    - `type` 'individual', required: The type of the user.
    - `email` string, email, required: The email address.
    - `termsOfService` 'general-us-hq' | 'general-gb-fca' | 'general-pt-bop' | 'general-lt-fcs' | 'general-bs-scb', required: The general terms of service the user agreed to.
    - `phone` object: The phone number.
      - `number` string, required: The E.164 formatted phone number.
      - `country` string, required: The country code of the phone number. It must be a ISO alpha-2 code that is used to disambiguate phone numbers with the same dialing code.
    - `fullName` string: The full legal name.
    - `birthdate` string, date: The date of birth.
    - `primaryCitizenship` string, required: The citizenship country.
    - `address` object, required: The address of residency.
      - `country` string, required: The country of the address.
      - `subdivision` string: The subdivision of the address.
      - `city` string: The city of the address.
      - `line1` string: The first line of the address.
      - `line2` string: The second line of the address.
      - `postalCode` string: The postal code of the address.
    - `metadata` Metadata
  - object
    - `type` 'individual', required: The type of the user.
    - `email` string, email, required: The email address.
    - `termsOfService` 'general-us-hq' | 'general-gb-fca' | 'general-pt-bop' | 'general-lt-fcs' | 'general-bs-scb', required: The general terms of service the user agreed to.
    - `citizenshipCountry` string, required: The citizenship country.
    - `country` string, required: The country of residency.
    - `subdivision` string: The subdivision of residency.
    - `metadata` Metadata
  - object
    - `type` 'business', required: The type of the user.
    - `email` string, email, required: The email address.
    - `termsOfService` 'general-us-hq' | 'general-gb-fca' | 'general-pt-bop' | 'general-lt-fcs' | 'general-bs-scb', required: The general terms of service the user agreed to.
    - `legalEntityType` 'government-entity' | 'non-profit' | 'partnership' | 'private-limited-company' | 'public-company' | 'sole-proprietor', required: Business legal form/classification.
    - `legalEntityName` string: The full legal entity name.
    - `formationDate` string, date: The date of the business formation.
    - `industry` union
      - union
        - union: The industry classification of the business. Allowed `subSector` values depend on the selected `sector`.
          - object
            - `sector` 'financial-institutions-and-money-services', required
            - `subSector` 'money-transmitters' | 'remittance-services' | 'vasp-casp' | 'payment-processors' | 'fx-providers' | 'other-regulated-nbfi'
          - object
            - `sector` 'crypto-services-and-products', required
            - `subSector` 'exchanges' | 'custodial-wallet-providers' | 'non-custodial-wallet-providers' | 'miners' | 'nft-platforms' | 'defi-projects'
          - object
            - `sector` 'personal-investment-vehicles', required
            - `subSector` 'private-trusts' | 'roth-ira' | 'llc-spe-for-holding-assets'
          - object
            - `sector` 'family-offices-and-investment-funds', required
            - `subSector` 'family-offices' | 'pooled-investment-vehicles' | 'private-investment-funds'
          - object
            - `sector` 'professional-services', required
            - `subSector` 'law-firms' | 'accounting-firms' | 'consultants' | 'company-formation-or-secretarial-services'
          - object
            - `sector` 'technology-and-software', required
            - `subSector` 'it-services' | 'saas' | 'gaming-studios' | 'cybersecurity' | 'data-analytics' | 'ai-firms'
          - object
            - `sector` 'ecommerce-and-retail', required
            - `subSector` 'online-marketplaces' | 'merchants' | 'wholesalers' | 'direct-to-consumer-retailers'
          - object
            - `sector` 'real-estate-and-property-management', required
            - `subSector` 'brokerages' | 'property-developers' | 'management-companies' | 'investment-vehicles'
          - object
            - `sector` 'high-value-goods-and-luxury-dealers', required
            - `subSector` 'jewelry' | 'art' | 'precious-metals' | 'automobiles' | 'auction-houses'
        - object
          - `sector` 'other', required
          - `otherSector` string: Free-form description of the sector and sub-sector.
      - object
        - `sector` 'other', required
        - `otherSector` string: Free-form description of the sector and sub-sector.
    - `legalIds` object[]: The legal identifiers of the business, usually government-issued.
      - `type` 'tax-id' | 'registration-id', required: The type of the legal identifier.
      - `id` string, required: The legal identifier value.
      - `country` string, required: The country of the legal identifier.
    - `registrationAddress` object, required: The registration address of the business.
      - `country` string, required: The country of the address.
      - `subdivision` string: The subdivision of the address.
      - `city` string: The city of the address.
      - `line1` string: The first line of the address.
      - `line2` string: The second line of the address.
      - `postalCode` string: The postal code of the address.
    - `operatingAddress` object, required: The operating address of the business.
      - `country` string, required: The country of the address.
      - `subdivision` string: The subdivision of the address.
      - `city` string: The city of the address.
      - `line1` string: The first line of the address.
      - `line2` string: The second line of the address.
      - `postalCode` string: The postal code of the address.
    - `metadata` Metadata
  - object
    - `type` 'business', required: The type of the user.
    - `email` string, email, required: The email address.
    - `termsOfService` 'general-us-hq' | 'general-gb-fca' | 'general-pt-bop' | 'general-lt-fcs' | 'general-bs-scb', required: The general terms of service the user agreed to.
    - `legalEntityType` 'private-limited-company', required: Business legal form/classification.
    - `country` string, required: The country of residency.
    - `subdivision` string: The subdivision of residency.
    - `metadata` Metadata

## Response `201`

User created.

- object
  - `user` union, required
    - object
      - `id` string, uuid, required: The id of the user.
      - `type` 'individual', required: The type of the user.
      - `email` string, email, required: The email address.
      - `fullName` string: The full legal name.
      - `birthdate` string: The date of birth.
      - `primaryCitizenship` string, required: The citizenship country.
      - `citizenshipCountry` string: The citizenship country. Deprecated in favor of `primaryCitizenship`.
      - `address` object, required: The address of residency.
        - `country` string, required: The country of the address.
        - `subdivision` string: The subdivision of the address.
        - `city` string: The city of the address.
        - `line1` string: The first line of the address.
        - `line2` string: The second line of the address.
        - `postalCode` string: The postal code of the address.
      - `phone` object: The phone number.
        - `number` string, required: The E.164 formatted phone number.
        - `country` string, required: The country code of the phone number.
      - `createdAt` string, date-time, required: The time at which the user was created.
      - `updatedAt` string, date-time, required: The time at which the user was last updated.
    - object
      - `id` string, uuid, required: The id of the user.
      - `type` 'business', required: The type of the user.
      - `email` string, email, required: The email address.
      - `legalEntityType` 'government-entity' | 'non-profit' | 'partnership' | 'private-limited-company' | 'public-company' | 'sole-proprietor', required: Business legal form/classification.
      - `legalEntityName` string: The full legal entity name.
      - `formationDate` string, date: The date of the business formation.
      - `industry` union
        - union: The industry classification of the business. Allowed `subSector` values depend on the selected `sector`.
          - object
            - `sector` 'financial-institutions-and-money-services', required
            - `subSector` 'money-transmitters' | 'remittance-services' | 'vasp-casp' | 'payment-processors' | 'fx-providers' | 'other-regulated-nbfi'
          - object
            - `sector` 'crypto-services-and-products', required
            - `subSector` 'exchanges' | 'custodial-wallet-providers' | 'non-custodial-wallet-providers' | 'miners' | 'nft-platforms' | 'defi-projects'
          - object
            - `sector` 'personal-investment-vehicles', required
            - `subSector` 'private-trusts' | 'roth-ira' | 'llc-spe-for-holding-assets'
          - object
            - `sector` 'family-offices-and-investment-funds', required
            - `subSector` 'family-offices' | 'pooled-investment-vehicles' | 'private-investment-funds'
          - object
            - `sector` 'professional-services', required
            - `subSector` 'law-firms' | 'accounting-firms' | 'consultants' | 'company-formation-or-secretarial-services'
          - object
            - `sector` 'technology-and-software', required
            - `subSector` 'it-services' | 'saas' | 'gaming-studios' | 'cybersecurity' | 'data-analytics' | 'ai-firms'
          - object
            - `sector` 'ecommerce-and-retail', required
            - `subSector` 'online-marketplaces' | 'merchants' | 'wholesalers' | 'direct-to-consumer-retailers'
          - object
            - `sector` 'real-estate-and-property-management', required
            - `subSector` 'brokerages' | 'property-developers' | 'management-companies' | 'investment-vehicles'
          - object
            - `sector` 'high-value-goods-and-luxury-dealers', required
            - `subSector` 'jewelry' | 'art' | 'precious-metals' | 'automobiles' | 'auction-houses'
        - object
          - `sector` 'other', required
          - `otherSector` string: Free-form description of the sector and sub-sector.
      - `legalIds` object[]: The legal identifiers of the business, usually government-issued.
        - `type` 'tax-id' | 'registration-id', required: The type of the legal identifier.
        - `id` string, required: The legal identifier value.
        - `country` string, required: The country of the legal identifier.
      - `registrationAddress` object: The registration address of the business. Always available for non-legacy business users.
        - `country` string, required: The country of the address.
        - `subdivision` string: The subdivision of the address.
        - `city` string: The city of the address.
        - `line1` string: The first line of the address.
        - `line2` string: The second line of the address.
        - `postalCode` string: The postal code of the address.
      - `operatingAddress` Address, required: The address information.
        - `country` string: The country of the address.
        - `subdivision` string: The subdivision of the address.
        - `city` string: The city of the address.
        - `line1` string: The first line of the address.
        - `line2` string: The second line of the address.
        - `postalCode` string: The postal code of the address.
      - `name` string: The legal name of the business.
      - `address` object, required: The address of the business (operating address).
        - `country` string, required: The country of the address.
        - `subdivision` string: The subdivision of the address.
        - `city` string: The city of the address.
        - `line1` string: The first line of the address.
        - `line2` string: The second line of the address.
        - `postalCode` string: The postal code of the address.
      - `createdAt` string, date-time, required: The time at which the user was created.
      - `updatedAt` string, date-time, required: The time at which the user was last updated.
  - `errors` object: Additional contextual errors that occurred while processing the request.
    - `metadata` object: Error related to metadata processing.
      - `code` string, required: A short string with a brief explanation about the code reported.
      - `message` string, required: A human-readable message providing more details.
      - `details` object: Additional information about the feedback reported.

## Other responses

- `400`: Bad Request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `409`: Business logic error.
- `429`: Too Many Requests.

---

[API](https://skmtc.dev/uphold/apis/core-api.md) - [All operations](https://skmtc.dev/uphold/apis/core-api/llms.txt) - [OpenAPI document](https://skmtc.dev/uphold/apis/core-api/revisions/6c663575c57a?raw)