> ## 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 test user

> Create a test user with a specific status and properties for sandbox testing.

<Warning>
  These test endpoints are **only available in development and staging environments**. They are disabled in production for security reasons.
</Warning>

Create a test user account with a predefined status. This endpoint is useful for setting up test scenarios with users in various lifecycle states.

<Info>
  **B2B Test User Builder Restriction**: Only three statuses are allowed for B2B test user creation:

  * `INVESTED` - User with investments
  * `INVESTED_WITH_CASH` - User with investments and cash
  * `INVESTED_WITH_SAVINGS` - User with investments and savings
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.sandbox.wealthyhood.com/test/users' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
    -d '{
      "email": "test.user@example.com",
      "status": "INVESTED_WITH_CASH",
      "props": {
        "firstName": "John",
        "lastName": "Doe"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sandbox.wealthyhood.com/test/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({
      email: 'test.user@example.com',
      status: 'INVESTED_WITH_CASH',
      props: {
        firstName: 'John',
        lastName: 'Doe'
      }
    })
  });

  const { user } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "user": {
      "_id": "64f0c51e7fb3fc001234abcd",
      "email": "test.user@example.com",
      "status": "INVESTED_WITH_CASH",
      "currency": "EUR",
      "portfolios": [...]
    }
  }
  ```
</ResponseExample>

## Request body

<ParamField body="email" type="string" required>
  Email address for the test user. Must be a valid email format.
</ParamField>

<ParamField body="status" type="string" required>
  User status. Must be one of the allowed statuses for B2B test user builder. Use `GET /test/help/statuses` to retrieve the list of valid status values.

  Allowed statuses:

  * `INVESTED` - User with investments
  * `INVESTED_WITH_CASH` - User with investments and cash
  * `INVESTED_WITH_SAVINGS` - User with investments and savings
</ParamField>

<ParamField body="props" type="object">
  Optional user properties to override defaults. If omitted, random values are used for firstName and lastName.
</ParamField>

<ParamField body="props.firstName" type="string">
  First name for the test user. Must be 1-100 characters. Optional.
</ParamField>

<ParamField body="props.lastName" type="string">
  Last name for the test user. Must be 1-100 characters. Optional.
</ParamField>

<Tip>
  Use the [Get available statuses](/api-reference/test/get-available-statuses) endpoint to see all available user status options.
</Tip>


## OpenAPI

````yaml POST /test/users
openapi: 3.0.3
info:
  title: Wealthyhood Test API
  version: 1.0.0
  description: >
    Test endpoints for sandbox environments. These endpoints allow you to create
    test users, simulate deposits,

    send test app notifications, and manage test data.


    **Important**: These endpoints are only available in development and staging
    environments. They are disabled in production for security reasons.


    All requests require a bearer token.
servers:
  - url: https://{host}
    variables:
      host:
        default: api.sandbox.wealthyhood.com
        description: Wealthyhood API host name (sandbox environment).
security:
  - bearerAuth: []
tags:
  - name: Test
    description: Test endpoints for sandbox environments.
paths:
  /test/users:
    post:
      tags:
        - Test
      summary: Create test user
      description: >
        Create a test user account with a specific status and optional
        properties. Useful for setting up test scenarios with users in various
        lifecycle states.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - status
              properties:
                email:
                  type: string
                  format: email
                  description: Email address for the test user
                  example: test.user@example.com
                status:
                  type: string
                  enum:
                    - INVESTED
                    - INVESTED_WITH_CASH
                    - INVESTED_WITH_SAVINGS
                    - FULL_USER_NBG
                  description: >-
                    User status. Must be one of the allowed statuses for B2B
                    test user builder.
                  example: INVESTED_WITH_CASH
                props:
                  type: object
                  description: >-
                    Optional user properties to override defaults (e.g.
                    firstName, lastName).
                  properties:
                    firstName:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: >-
                        First name for the test user. If omitted, a random value
                        is generated.
                      example: John
                    lastName:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: >-
                        Last name for the test user. If omitted, a random value
                        is generated.
                      example: Doe
            examples:
              withProps:
                summary: Request with custom firstName and lastName
                value:
                  email: test.user@example.com
                  status: INVESTED_WITH_CASH
                  props:
                    firstName: John
                    lastName: Doe
              minimal:
                summary: Minimal request (email and status only)
                value:
                  email: test.user@example.com
                  status: INVESTED_WITH_CASH
      responses:
        '200':
          description: Test user created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/TestUser'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
components:
  schemas:
    TestUser:
      type: object
      description: Test user object with populated portfolios
      properties:
        _id:
          type: string
          example: 64f0c51e7fb3fc001234abcd
        email:
          type: string
          format: email
          example: test.user@example.com
        status:
          type: string
          enum:
            - INVESTED
            - INVESTED_WITH_CASH
            - INVESTED_WITH_SAVINGS
            - FULL_USER_NBG
          example: INVESTED_WITH_CASH
        currency:
          type: string
          example: EUR
        portfolios:
          type: array
          description: User portfolios
          items:
            type: object
            properties:
              id:
                type: string
                description: Portfolio unique identifier
                example: 64f0c51e7fb3fc001234def0
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          example: Invalid amount
        code:
          type: string
          example: BAD_REQUEST
  responses:
    BadRequestError:
      description: Bad request – invalid parameters or malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid amount
            code: BAD_REQUEST
    UnauthorizedError:
      description: Unauthorized – missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Authentication required
            code: UNAUTHORIZED
    ForbiddenError:
      description: >-
        Forbidden – valid credentials but insufficient permissions or endpoint
        not available in this environment.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Endpoint not available in production
            code: FORBIDDEN
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````