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

# Create User

Creates a new user under your partner account. Each user must have a unique email address within the scope of the partner. After creation, initiate KYC verification before the user can transact.

***

## Important Notes

* Each `externalUserId` (if provided) must be unique per partner. Reuse will cause a conflict.
* Creating a user does **not** initiate KYC — use the [KYC verification link](/reference/userpartnercontrollerv2_createverificationlink) endpoint next.
* Set `type` to `INDIVIDUAL` for personal accounts or `BUSINESS` for corporate accounts. Business users use [KYB verification](/reference/userpartnercontrollerv2_generatekybverificationlink) instead of KYC.
* Store the returned `userId` — you'll need it for all subsequent API calls for this user.

***

## Use Cases

* **User onboarding**: Create users ahead of any financial operation.
* **CRM syncing**: Use `externalUserId` to map Capa users to your internal user model.
* **Business registration**: Set `type` to `BUSINESS` for corporate flows.

***

## Error Codes

### Common Errors

| HTTP Status | Code                   | Message                            |
| ----------- | ---------------------- | ---------------------------------- |
| 401         | `UNAUTHORIZED`         | "API Key is missing"               |
| 401         | `UNAUTHORIZED`         | "Invalid API Key format"           |
| 401         | `UNAUTHORIZED`         | "Invalid API Key"                  |
| 403         | `INVALID_PARTNER_FLOW` | "The partner has an invalid flow." |

### Endpoint-Specific Errors

| HTTP Status | Code                       | Message                                                                         |
| ----------- | -------------------------- | ------------------------------------------------------------------------------- |
| 400         | `INVALID_USER_INPUT_ERROR` | "Invalid User Input" (validation errors for type, email, externalUserId, alias) |
| 400         | `BAD_REQUEST`              | "Provided email {email} is not valid"                                           |
| 500         | `INTERNAL_SERVER_ERROR`    | "User creation failed"                                                          |


## OpenAPI

````yaml reference/openapi/UserPartnerControllerV2_createUser.json POST /api/partner/v2/users
openapi: 3.0.0
info:
  title: Capa Partner API - V2
  description: >-
    Partner API for integrating cryptocurrency on-ramp and off-ramp services
    using Capa's infrastructure. Enable your users to seamlessly convert between
    fiat and crypto.
  version: v2
  contact: {}
servers:
  - url: https://staging-api.capa.fi
  - url: https://production-api.capa.fi
security: []
paths:
  /api/partner/v2/users:
    post:
      tags:
        - users
      operationId: UserPartnerControllerV2_createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  description: The type of user.
                  example: INDIVIDUAL or BUSINESS
                  enum:
                    - INDIVIDUAL
                    - BUSINESS
                  type: string
                email:
                  type: string
                  description: The email of the user.
                  example: money@capa.fi
                externalUserId:
                  type: string
                  description: The external user id of the user.
                alias:
                  type: string
                  description: An optional alias or display name for the user.
              required:
                - type
                - email
              x-readme-ref-name: CreatePartnerUserBody
      responses:
        '201':
          description: >-
            User created successfully. Returns the user details, including the
            generated user id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      userId:
                        type: string
                        description: The user's ID.
                        example: 9486244c-ff7d-4c22-9984-797179d7deaa
                    required:
                      - userId
                    x-readme-ref-name: CreatePartnerUserHttpResponse
              example:
                success: true
                data:
                  userId: 9486244c-ff7d-4c22-9984-797179d7deaa
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INVALID_USER_INPUT_ERROR:
                  value:
                    success: false
                    code: INVALID_USER_INPUT_ERROR
                    message: Invalid User Input
                BAD_REQUEST:
                  value:
                    success: false
                    code: BAD_REQUEST
                    message: Provided email {email} is not valid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: API Key is missing
                UNAUTHORIZED_2:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Invalid API Key format
                UNAUTHORIZED_3:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Invalid API Key
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: INTERNAL_SERVER_ERROR
                message: Internal server error
      security:
        - PartnerApiKey: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: Optional per-field validation details.
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
      required:
        - success
        - code
        - message
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      in: header
      name: partner-api-key
      description: API key for the affiliated partner performing the request.

````