> ## 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 Organization

> Create a new organization with an owner. This is the recommended way to onboard new customers - create the organization first, then add additional users and locations as needed.




## OpenAPI

````yaml /openapi.yaml post /organizations
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:
  /organizations:
    post:
      tags:
        - Organizations
      summary: Create Organization
      description: >
        Create a new organization with an owner. This is the recommended way to
        onboard new customers - create the organization first, then add
        additional users and locations as needed.
      operationId: createOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - owner
              properties:
                name:
                  type: string
                  description: Name of the organization
                  example: Acme Corporation
                description:
                  type: string
                  description: Optional description of the organization
                  nullable: true
                  example: A technology company specializing in innovative solutions
                owner:
                  type: object
                  required:
                    - external_id
                    - email
                  description: Owner user details
                  properties:
                    external_id:
                      type: string
                      description: Your unique identifier for this user
                      example: user_123
                    email:
                      type: string
                      format: email
                      description: Email address of the owner
                      example: john@acme.com
                    name:
                      type: string
                      description: Display name of the owner
                      nullable: true
                      example: John Doe
      responses:
        '201':
          description: Organization and owner created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/Organization'
                  owner:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Organization:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the organization
          example: 1
        name:
          type: string
          description: Name of the organization
          example: Acme Corporation
        partner_type:
          type: string
          enum:
            - provisioned
            - linked
          description: >
            How this organization is attached to your partner account.
            'provisioned' organizations were created through this API and can be
            updated or deleted. 'linked' organizations belong to existing
            Answering Agent accounts attached via an accepted partner link and
            are read-only.
          example: provisioned
        permissions:
          type: object
          description: Partner capabilities for this organization
          properties:
            can_view_dashboard:
              type: boolean
            can_manage_dashboard_viewers:
              type: boolean
        created_at:
          type: string
          format: date-time
          description: When the organization was created
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the organization was last updated
          example: '2024-01-20T14:45:00Z'
        users:
          type: array
          description: Users that are members of this organization
          items:
            $ref: '#/components/schemas/User'
        phone_numbers:
          type: array
          description: Locations/phone numbers belonging to this organization
          items:
            $ref: '#/components/schemas/Location'
    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
    Location:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        phone_number:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - pending
            - active
        address:
          type: string
          nullable: true
        google_place_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  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

````