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

# Create a user

> Create a person your company has verified, with no connect code.

Create a person your company vouches for: you send their name, date of birth and an email or phone number, and no code goes to them. Use the `id` it returns as the `user_id` on every other endpoint.

To have a person approve your app themselves, [connect them](https://docs.agentcard.com/api-reference/connections/overview.md) instead. Cardholders you created with `/api/v1/cardholders` already work on v2: pass either their cardholder id or their `user_id`.

Creating the same person again answers `409 user_exists` with the person you already have, so a retry is safe.


## OpenAPI

````yaml openapi.json POST /api/v2/users
openapi: 3.1.0
info:
  title: Agentcard API
  version: 2.0.0
  description: >-
    The Agentcard v2 API — connect your users and verify their identity from
    your own backend. Every call is authenticated with a platform access token
    minted from your `client_id` + `client_secret`.
servers:
  - url: https://api.agentcard.sh
    description: >-
      There is one base URL. Sandbox vs production is decided by the client
      credential you use, never by the host.
security:
  - platformToken: []
tags:
  - name: Authentication
    description: >-
      Exchange your client credentials for a platform access token, and
      introspect what a token acts as.
  - name: Connect
    description: >-
      Connect a user to your platform: send a one-time code, verify it, record
      consent, and keep the connection alive.
  - name: Identity verification
    description: >-
      Verify a connected user's identity: upload their ID, submit any extra
      fields we ask for, then show a short face scan.
paths:
  /api/v2/users:
    post:
      tags:
        - Users
      summary: Create a user
      description: >-
        Creates a person your company has verified, with no connect code. The
        answer's `id` is their `user_id`.
      operationId: userCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - last_name
                - date_of_birth
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                date_of_birth:
                  type: string
                  description: '`YYYY-MM-DD`.'
                  example: '1990-01-15'
                email:
                  type: string
                  description: Send an email, a phone number, or both.
                phone_number:
                  type: string
                  description: Send an email, a phone number, or both.
      responses:
        '201':
          description: The user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: >-
            `invalid_request`: a field is missing or malformed, or neither an
            email nor a phone number was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The access token is missing or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: '`cardholder_limit_reached`: your plan''s user limit.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `user_exists`: this person already exists in your company. The error
            carries them as `user`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - platformToken: []
components:
  schemas:
    User:
      type: object
      required:
        - object
        - id
        - cardholder_id
        - livemode
        - created_at
      properties:
        object:
          type: string
          description: Always `user`.
        id:
          type: string
          description: The `user_id` every other endpoint takes.
        cardholder_id:
          type: string
          description: >-
            The same person's id on `/api/v1/cardholders`. v2 endpoints take it
            as `user_id` too.
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        date_of_birth:
          type: string
          nullable: true
          description: '`YYYY-MM-DD`.'
        livemode:
          type: boolean
          description: '`false` for a person created with a sandbox credential.'
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      description: Every v2 error uses the same envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable string (snake_case). Branch on this.
            message:
              type: string
              description: A human-readable explanation, safe to log.
            docs:
              type: string
              description: A link back to the reference.
            field_errors:
              type: object
              additionalProperties:
                type: string
              description: Only on `invalid_fields` — names each field to fix.
            warnings:
              type: array
              items:
                type: string
              description: >-
                Only on document upload errors — actionable feedback safe to
                show the user.
            status:
              type: string
              description: >-
                Only on `verification_terminally_rejected` — the user's current
                verification status, which this call did not change.
            reason:
              type: string
              description: >-
                The detail behind the failure, on the errors that carry one: on
                `verification_terminally_rejected` an end-user-safe explanation
                of the rejection, when the review left one; on `invalid_code`
                and `invalid_return_url` which part of the input was refused.
            reason_code:
              type: string
              description: >-
                Only on `verification_terminally_rejected`, and only when the
                rejection maps to a known class — most final rejections carry no
                code.
  securitySchemes:
    platformToken:
      type: http
      scheme: bearer
      description: >-
        A platform access token. Get one on the **Create an access token**
        endpoint by exchanging your `client_id` + `client_secret`, then send it
        as `Authorization: Bearer <token>`. Tokens live one hour.

````

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