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

# Create a User

> Creates one identity owned by your partner account. For a provisioned organization, the user receives the requested membership. For an owner-linked organization with an active viewer-management grant, the user is created as a read-only dashboard viewer with role 'user'; the response has a null embed_token and a scoped token must then be requested with organization_id. Linked organizations reject provisioning fields.




## OpenAPI

````yaml /openapi.yaml post /users
openapi: 3.0.0
info:
  title: Answering Agent API
  description: API for Answering Agent platform
  version: 1.0.0
servers:
  - url: https://answeringagent.com/api/v1
    description: Production API
  - url: https://playground.answeringagent.com/api/v1
    description: Playground API
security: []
paths:
  /users:
    post:
      tags:
        - Users
      summary: Create a User
      description: >
        Creates one identity owned by your partner account. For a provisioned
        organization, the user receives the requested membership. For an
        owner-linked organization with an active viewer-management grant, the
        user is created as a read-only dashboard viewer with role 'user'; the
        response has a null embed_token and a scoped token must then be
        requested with organization_id. Linked organizations reject provisioning
        fields.
      operationId: createUser
      parameters:
        - in: query
          name: organization_id
          schema:
            type: integer
          description: Organization to assign the user to (alternative to the body field)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - external_id
                - email
              properties:
                external_id:
                  type: string
                  description: >-
                    Unique identifier in your database. This key is unique
                    across your partner account.
                email:
                  type: string
                  format: email
                  description: Email address of the user.
                name:
                  type: string
                  description: Customer's display name.
                  nullable: true
                team_name:
                  type: string
                  description: >-
                    Name of a new team to create for this user (if not adding to
                    existing organization).
                  nullable: true
                organization_id:
                  type: integer
                  description: >
                    ID of an existing organization to add the user to
                    (alternative to the query parameter). Owner-linked
                    organizations require an active viewer-management grant and
                    always assign role 'user'.
                  nullable: true
                role:
                  type: string
                  description: >-
                    Role to assign to the user in the organization. If provided,
                    organization_id is required.
                  enum:
                    - owner
                    - manager
                    - user
                  nullable: true
      responses:
        '201':
          description: User created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Organization not found (if organization_id provided)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Organization not found
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateUserResponse:
      type: object
      properties:
        embed_token:
          type: string
          nullable: true
          description: Secure, compact embed token for dashboard authentication
          example: MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA
        user:
          $ref: '#/components/schemas/User'
        team:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        locations:
          type: array
          items:
            type: object
            properties:
              location:
                type: string
              phone_id:
                type: integer
    User:
      type: object
      properties:
        id:
          type: integer
          description: Internal user ID
        external_id:
          type: string
          description: External identifier provided by the reseller
        email:
          type: string
          format: email
          description: User's email address
        name:
          type: string
          description: User's display name
        created_at:
          type: string
          format: date-time
          description: When the user was created
        updated_at:
          type: string
          format: date-time
          description: When the user was last updated
        organizations:
          type: array
          description: Organizations this user belongs to with their role
          items:
            type: object
            properties:
              id:
                type: integer
                description: Organization ID
              name:
                type: string
                description: Organization name
              role:
                type: string
                description: User's role in this organization
                enum:
                  - owner
                  - manager
                  - user
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: API key is required
                enum:
                  - API key is required
                  - Invalid credentials
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              errors:
                type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````