> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create user

> Create a new user account with personal information, address, tax residency, nationality, and employment details.



## OpenAPI

````yaml POST /users
openapi: 3.0.3
info:
  title: Wealthyhood Users API
  version: 1.0.0
  description: >
    User management endpoints for creating and managing user accounts in the
    Wealthyhood platform.


    All requests require a bearer access token with the advertised scopes, and
    must include 

    appropriate authentication headers.
servers:
  - url: https://{host}
    variables:
      host:
        default: api.wealthyhood.com
        description: Wealthyhood API host name.
security:
  - bearerAuth: []
tags:
  - name: Users
    description: Create and manage user accounts.
paths:
  /users:
    post:
      tags:
        - Users
      summary: Create a new user
      description: >
        Create a new user account with the provided information. This endpoint
        validates the user data

        and creates a new user record in the system.


        **Required fields:**

        - Email address (must be valid and unique)

        - First name

        - Last name

        - Date of birth

        - Residency country

        - Employment info (income range, employment status, sources of wealth;
        industry when required for status)


        **Optional fields:**

        - Language preference (en for English, el for Greek)

        - Address information (line1, line2, city, postal code, country code)

        - Tax residency information (country code, proof type, value)

        - Nationality (two-letter ISO country code)


        **Validation rules:**

        - If an address is provided, the `address.countryCode` must match the
        `residencyCountry` value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              basicUser:
                summary: Basic user with required fields only
                value:
                  email: john.doe@example.com
                  firstName: John
                  lastName: Doe
                  dateOfBirth: '1990-05-15'
                  residencyCountry: GR
                  language: en
                  employmentInfo:
                    incomeRangeId: '5'
                    employmentStatus: SelfEmployed
                    sourcesOfWealth:
                      - BusinessOwnership
                    industry: FinanceAndInsurance
              fullUser:
                summary: User with complete information
                value:
                  email: jane.smith@example.com
                  firstName: Jane
                  lastName: Smith
                  dateOfBirth: '1985-03-20'
                  residencyCountry: GR
                  language: el
                  nationality: GR
                  address:
                    line1: 15 Ermou Street
                    line2: Apartment 4B
                    city: Athens
                    postalCode: 10563
                    countryCode: GR
                  taxResidency:
                    countryCode: GR
                    proofType: TIN
                    value: 123456789
                  employmentInfo:
                    incomeRangeId: '5'
                    employmentStatus: SelfEmployed
                    sourcesOfWealth:
                      - BusinessOwnership
                    industry: FinanceAndInsurance
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              example:
                id: 64f0c51e7fb3fc001234a001
                email: john.doe@example.com
                firstName: John
                lastName: Doe
                dateOfBirth: '1990-05-15'
                residencyCountry: GR
                portfolios: []
                createdAt: '2024-10-03T10:30:00Z'
                updatedAt: '2024-10-03T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: User with this email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                status: 409
                error:
                  message: User with email john.doe@example.com already exists
                responseId: 3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd
components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - email
        - firstName
        - lastName
        - dateOfBirth
        - residencyCountry
        - employmentInfo
      properties:
        email:
          type: string
          format: email
          description: User's email address (must be unique)
          example: john.doe@example.com
        firstName:
          type: string
          description: User's first name
          minLength: 1
          maxLength: 100
          example: John
        lastName:
          type: string
          description: User's last name
          minLength: 1
          maxLength: 100
          example: Doe
        dateOfBirth:
          type: string
          format: date
          description: User's date of birth (YYYY-MM-DD)
          example: '1990-05-15'
        residencyCountry:
          type: string
          description: Two-letter ISO country code for user's country of residence
          pattern: ^[A-Z]{2}$
          example: GR
        language:
          type: string
          description: >-
            User's preferred language. Valid values are "en" (English) or "el"
            (Greek).
          enum:
            - en
            - el
          example: en
        address:
          type: object
          description: >-
            User's residential address. When provided, line1, city, postalCode,
            and countryCode are required.
          required:
            - line1
            - city
            - postalCode
            - countryCode
          properties:
            line1:
              type: string
              description: First line of address
              example: 15 Ermou Street
            line2:
              type: string
              description: Second line of address (optional)
              example: Apartment 4B
            city:
              type: string
              description: City or town
              example: Athens
            postalCode:
              type: string
              description: Postal or ZIP code
              example: 10563
            countryCode:
              type: string
              description: >
                Two-letter ISO country code. **Must match the `residencyCountry`
                value** when provided.

                If the address country code differs from the residency country,
                the request will be rejected with a 400 error.
              pattern: ^[A-Z]{2}$
              example: GR
        taxResidency:
          type: object
          description: >-
            Tax residency information. When provided, countryCode, proofType,
            and value are required.
          required:
            - countryCode
            - proofType
            - value
          properties:
            countryCode:
              type: string
              description: Two-letter ISO country code for tax residency
              pattern: ^[A-Z]{2}$
              example: GR
            proofType:
              type: string
              description: >-
                Type of tax identification. Valid values are "NINO" (for UK) or
                "TIN" (for all other countries).
              enum:
                - NINO
                - TIN
              example: TIN
            value:
              type: string
              description: Tax identification number
              example: 123456789
        nationality:
          type: string
          description: Two-letter ISO country code for user's nationality (citizenship)
          pattern: ^[A-Z]{2}$
          example: GR
        employmentInfo:
          $ref: '#/components/schemas/EmploymentInfoRequest'
      additionalProperties: false
    UserResponse:
      type: object
      required:
        - id
        - email
        - portfolios
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: MongoDB ObjectId of the created user
          pattern: ^[a-f0-9]{24}$
          example: 64f0c51e7fb3fc001234a001
        email:
          type: string
          format: email
          example: john.doe@example.com
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        dateOfBirth:
          type: string
          format: date
          example: '1990-05-15'
        residencyCountry:
          type: string
          example: GR
        language:
          type: string
          description: >-
            User's preferred language. Valid values are "en" (English) or "el"
            (Greek).
          enum:
            - en
            - el
          example: en
        portfolios:
          type: array
          description: Array of user's portfolios with holdings and target allocation
          items:
            $ref: '#/components/schemas/PortfolioHoldings'
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            postalCode:
              type: string
            countryCode:
              type: string
        taxResidency:
          type: object
          properties:
            countryCode:
              type: string
              description: Two-letter ISO country code for tax residency
            proofType:
              type: string
              description: >-
                Type of tax identification. Valid values are "NINO" (for UK) or
                "TIN" (for all other countries).
              enum:
                - NINO
                - TIN
            value:
              type: string
              description: Tax identification number
        nationalities:
          type: array
          description: >-
            Array of two-letter ISO country codes for user's nationality
            (citizenship)
          items:
            type: string
            pattern: ^[A-Z]{2}$
          example:
            - GR
        employmentInfo:
          type: object
          description: Employment and source of wealth information (optional)
          properties:
            incomeRangeId:
              type: string
              description: >
                ID of the income range (1-10). 1=€0-€10k | 2=€10k-€20k |
                3=€20k-€30k | 4=€30k-€50k |

                5=€50k-€75k | 6=€75k-€100k | 7=€100k-€150k | 8=€150k-€250k |
                9=€250k-€500k | 10=€500k+
            employmentStatus:
              type: string
            sourcesOfWealth:
              type: array
              items:
                type: string
            industry:
              type: string
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the user was created
          example: '2024-10-03T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the user was last updated
          example: '2024-10-03T10:30:00Z'
    ApiErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message
            description:
              type: string
              description: Additional error details
              nullable: true
        responseId:
          type: string
          format: uuid
          description: Unique identifier for this error response
      additionalProperties: false
    EmploymentInfoRequest:
      type: object
      description: >
        Employment and source of wealth information. Required on create user.

        incomeRangeId, employmentStatus, and sourcesOfWealth are required.
        Industry is required

        when employmentStatus is FullTime, PartTime, or SelfEmployed.
      required:
        - incomeRangeId
        - employmentStatus
        - sourcesOfWealth
      properties:
        incomeRangeId:
          type: string
          description: >
            ID of the income range (1-10). Valid values and their annual income
            ranges (in EUR):

            1 = €0 - €10,000 | 2 = €10,001 - €20,000 | 3 = €20,001 - €30,000 | 4
            = €30,001 - €50,000 |

            5 = €50,001 - €75,000 | 6 = €75,001 - €100,000 | 7 = €100,001 -
            €150,000 |

            8 = €150,001 - €250,000 | 9 = €250,001 - €500,000 | 10 = €500,001+
          example: '5'
        employmentStatus:
          type: string
          description: Employment status
          enum:
            - FullTime
            - PartTime
            - SelfEmployed
            - Unemployed
            - Retired
            - Student
            - NotWorkingDueToIllnessOrDisability
            - CarerOrParent
          example: SelfEmployed
        sourcesOfWealth:
          type: array
          description: At least one source of wealth required
          items:
            type: string
            enum:
              - Salary
              - Inheritance
              - Gift
              - BusinessOwnership
              - SaleOfProperty
              - GamblingOrLottery
              - PersonalSavings
              - LegalSettlement
              - SaleOfInvestments
              - Dividend
          example:
            - BusinessOwnership
        industry:
          type: string
          description: >-
            Required when employmentStatus is FullTime, PartTime, or
            SelfEmployed
          enum:
            - AgricultureForestryAndFishing
            - ArtsSportAndCreative
            - ConstructionAndEngineering
            - CryptoIndustryAndCryptocurrencies
            - CulturalArtefacts
            - DatingOrAdultIndustry
            - Education
            - EnergyAndWaterSupply
            - FinanceAndInsurance
            - GamblingOrIGamingIndustry
            - GovernmentPublicServiceAndDefence
            - HealthAndSocialWork
            - Hospitality
            - ImportAndExport
            - InformationAndCommunication
            - LegalAndRegulatory
            - Manufacturing
            - Mining
            - MoneyTransfer
            - MotorTrades
            - PreciousMetals
            - Property
            - Retail
            - ScientificAndTechnical
            - Tobacco
            - TransportAndStorage
            - Wholesale
          example: FinanceAndInsurance
      additionalProperties: false
    PortfolioHoldings:
      type: object
      description: User's portfolio with holdings, target allocation, and timestamps
      required:
        - id
        - currency
        - holdings
        - targetAllocation
      properties:
        id:
          type: string
          description: Portfolio unique identifier
          example: 64f0c51e7fb3fc001234def0
        currency:
          type: string
          description: ISO currency code for the portfolio (e.g. EUR, GBP, USD)
          example: EUR
        holdings:
          type: array
          description: Array of holdings with asset details and quantities
          items:
            type: object
            required:
              - isin
              - assetCommonId
              - quantity
            properties:
              isin:
                type: string
                description: >-
                  International Securities Identification Number (ISIN) for the
                  asset
                example: US0378331005
              assetCommonId:
                type: string
                description: Wealthyhood internal asset identifier
                example: equities_apple
              quantity:
                type: number
                format: double
                description: Number of shares/units held
                example: 12.5
        targetAllocation:
          type: array
          description: Target allocation by asset. Empty when unset.
          items:
            $ref: '#/components/schemas/TargetAllocationItem'
        createdAt:
          type: string
          format: date-time
          description: Portfolio creation timestamp
          example: '2024-03-01T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2024-07-10T12:00:00.000Z'
    TargetAllocationItem:
      type: object
      required:
        - assetCommonId
        - percentage
      properties:
        assetCommonId:
          type: string
          description: Wealthyhood internal asset identifier
        percentage:
          type: number
          format: double
          description: Target allocation percentage for the asset
      additionalProperties: false
  responses:
    BadRequestError:
      description: Validation failure or business rule violation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          examples:
            invalidEmail:
              summary: Invalid email format
              value:
                status: 400
                error:
                  message: Invalid email address format
                responseId: 3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd
            missingFields:
              summary: Missing required fields
              value:
                status: 400
                error:
                  message: 'Missing required fields: firstName, lastName'
                responseId: 3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd
            addressCountryMismatch:
              summary: Address country code mismatch
              value:
                status: 400
                error:
                  message: Address countryCode must match residencyCountry
                responseId: 3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd
    UnauthorizedError:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 401
            error:
              message: Unauthorized - Invalid or missing authentication token
            responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Auth0-issued access token that includes the scopes listed for the
        endpoint.

````