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

# Create a new user

<Warning>
  **v1 (legacy).** This page documents the API before the v2 update. The v1
  format is not enabled for new accounts and must be enabled on your account by
  your account manager. New integrations should use the
  [current documentation](/introduction). To update an existing integration,
  follow the [migration guide](/migration).
</Warning>


## OpenAPI

````yaml v1/api-reference/users-docs.json POST /api/users
openapi: 3.0.0
info:
  version: v1.0.0
  title: Users API (legacy v1)
  description: API for managing users in the Rio platform
servers:
  - url: https://app.sandbox.rio.trade
security:
  - apiKeyAuth: []
paths:
  /api/users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createUserSchema'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createUserResponseSchema'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorizedSchema'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notFoundErrorSchema'
          description: Not Found
components:
  schemas:
    createUserSchema:
      type: object
      required:
        - country
        - email
        - phoneNumber
        - userType
        - address
      properties:
        country:
          type: string
          description: Country
          enum:
            - MX
            - PE
            - CO
          example: MX
        businessName:
          type: string
          description: Business name (required for business users).
          example: My Business Inc.
        firstName:
          type: string
          description: First name (required for individual users only).
          example: John
        middleName:
          type: string
          description: Middle name (for individual users only).
          example: Michael
        lastName:
          type: string
          description: Last name (required for individual users).
          example: Doe
        secondLastName:
          type: string
          description: Second last name (for individual users only).
          example: Smith
        email:
          type: string
          description: User's email address.
          format: email
          example: john.doe@example.com
        phoneNumber:
          type: string
          description: User's phone number.
          example: '+526589562354'
        userType:
          type: string
          description: Type of user.
          enum:
            - business
            - individual
          example: individual
        address:
          type: object
          required:
            - street1
            - city
            - state
            - postalCode
            - country
          properties:
            street1:
              type: string
              description: Primary street address.
              example: 123 Main St
            street2:
              type: string
              description: Secondary street address (optional).
              example: Apt 4B
            city:
              type: string
              description: City name.
              example: Mexico City
            state:
              type: string
              description: State or province.
              example: CDMX
            postalCode:
              type: string
              description: Postal code.
              example: '12345'
            country:
              type: string
              description: Country code (2 characters).
              minLength: 2
              maxLength: 2
              example: MX
        additionalInformation:
          type: object
          description: Additional information about the user (optional).
          additionalProperties: true
        brokerId:
          type: string
          description: ID of the broker (optional).
          format: mongoId
          example: 655f4084b96e4fb76f5a0e6e
    createUserResponseSchema:
      type: object
      properties:
        userId:
          type: string
          description: ID of the created user.
          example: 66562bc04fe8bf83c577c178
    unauthorizedSchema:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: number
                example: 19
              message:
                type: string
                example: Not authorized
    notFoundErrorSchema:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
                example: 1
              message:
                type: string
                example: User not found
            required:
              - code
              - message
      required:
        - errors
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.