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

# Apply user availability status

> Apply a defined availability status (status_id) or a hardcoded shortcut (special: 'online' | 'offline') to a user, switching their main availability and per-support-team…



## OpenAPI

````yaml put /availability-statuses/users/{user_id}
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /availability-statuses/users/{user_id}:
    put:
      summary: Apply user availability status
      description: >-
        Apply a defined availability status (status_id) or a hardcoded shortcut
        (special: 'online' | 'offline') to a user, switching their main
        availability and per-support-team availability exactly like the
        dashboard status picker. If both fields are sent, special wins. Responds
        with the user's resulting resolved availability. The user must belong to
        the API key's organization.
      operationId: applyUserAvailabilityStatus
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 9007199254740991
          in: path
          name: user_id
          required: true
          description: Organization user ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyUserAvailabilityStatusDto'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAvailabilityStatusDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    ApplyUserAvailabilityStatusDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/ApplyUserAvailabilityStatusDtoInput'
      anyOf:
        - type: object
          properties:
            special:
              type: string
              enum:
                - online
                - offline
              description: >-
                Hardcoded shortcut: 'online' = main availability on + available
                on every support team; 'offline' = main availability off +
                unavailable on every support team. Takes priority if status_id
                is also sent.
          required:
            - special
        - type: object
          properties:
            status_id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              description: >-
                Id of a defined availability status (see
                listAvailabilityStatuses)
          required:
            - status_id
    UserAvailabilityStatusDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/UserAvailabilityStatusDto'
      type: object
      properties:
        availability:
          type: object
          properties:
            id:
              type: string
            user_id:
              type: number
            organization_id:
              type: string
            is_available:
              type: boolean
            custom_status:
              type:
                - string
                - 'null'
            last_status_change:
              type: string
              format: date-time
            current_chat_count:
              type: number
            max_concurrent_chats:
              type: number
            notes:
              type:
                - string
                - 'null'
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            call_available:
              type: boolean
            call_locked:
              type: boolean
            call_wrap_up_until:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
            call_wrap_up_started_at:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
            call_wrap_up_phone_call_id:
              type:
                - string
                - 'null'
            availability_status_id:
              type:
                - string
                - 'null'
          required:
            - id
            - user_id
            - organization_id
            - is_available
            - custom_status
            - last_status_change
            - current_chat_count
            - max_concurrent_chats
            - notes
            - created_at
            - updated_at
            - call_available
            - call_locked
            - call_wrap_up_until
            - call_wrap_up_phone_call_id
            - availability_status_id
          additionalProperties: false
          description: The user's raw availability record
        resolved_status:
          $ref: '#/components/schemas/ResolvedAvailabilityStatusDto'
        teams:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              available:
                type: boolean
            required:
              - id
              - name
              - available
            additionalProperties: false
          description: The user's full per-support-team availability switch matrix
      required:
        - availability
        - resolved_status
        - teams
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    ResolvedAvailabilityStatusDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/ResolvedAvailabilityStatusDto'
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              const: custom
              description: A defined availability status is applied
            status_id:
              type: string
              description: Id of the applied availability status
            name:
              type: string
              description: Name of the applied availability status
            availability_type:
              type: string
              enum:
                - offline
                - online
              description: Whether the applied status sets the agent online or offline
            color:
              type: string
              enum:
                - blue
                - gray
                - green
                - orange
                - red
              description: Display color configured on the applied status
          required:
            - kind
            - status_id
            - name
            - availability_type
            - color
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              const: online
              description: Main availability on and available on every support team
            color:
              type: string
              enum:
                - blue
                - gray
                - green
                - orange
                - red
              description: Always 'green' — the fixed color of the derived online state
          required:
            - kind
            - color
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              const: offline
              description: Main availability off
            color:
              type: string
              enum:
                - blue
                - gray
                - green
                - orange
                - red
              description: Always 'gray' — the fixed color of the derived offline state
          required:
            - kind
            - color
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              const: mixed
              description: Main availability on but only available on some support teams
            color:
              type: string
              enum:
                - blue
                - gray
                - green
                - orange
                - red
              description: Always 'green' — mixed is an online-related state
            available_teams:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                required:
                  - id
                  - name
                additionalProperties: false
              description: Support teams the user is currently available on
          required:
            - kind
            - color
            - available_teams
          additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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