> ## 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 by link

<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/link
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/link:
    post:
      summary: Create a new user by link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createUserByLinkSchema'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createUserByLinkResponseSchema'
          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:
    createUserByLinkSchema:
      type: object
      required:
        - country
        - userType
        - email
      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
        userType:
          type: string
          description: Type of user.
          enum:
            - business
            - individual
          example: individual
        brokerId:
          type: string
          description: ID of the broker (optional).
          format: mongoId
          example: 655f4084b96e4fb76f5a0e6e
    createUserByLinkResponseSchema:
      type: object
      properties:
        userId:
          type: string
          description: ID of the created user.
          example: 66562bc04fe8bf83c577c178
        onboardingLink:
          type: string
          description: Link for user onboarding verification.
          example: https://verification.example.com/session/123
    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.