Gladly Business Hours API

openapi: 3.2.0
info:
  title: Gladly Business Hours API
  version: '1.0'
  description: '# Introducing the Gladly API


    At Gladly, we believe that customer service is best when it''s a conversation.'
servers:
- url: https://{organization}.gladly.com/api/v1
  description: Production
  variables:
    organization:
      default: organization
      description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
  description: Sandbox
  variables:
    organization:
      default: organization
      description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Business Hours
  description: '**Business Hours** define the operating schedule for your organization.'
paths:
  /api/v1/business-hours:
    get:
      tags:
      - Business Hours
      summary: List Business Hours
      description: Returns a list of all business hours configurations for your organization.
      operationId: getBusinessHours
      responses:
        '200':
          description: Business hours
          content:
            application/json:
              schema:
                title: BusinessHoursList
                type: array
                items:
                  $ref: '#/paths/~1api~1v1~1business-hours/post/responses/201/content/application~1json/schema'
              example:
              - id: bh_WmeA3Y51Q5ayCAaZ1AotIA
                version: 1
                createdAt: '2024-01-15T09:00:00Z'
                updatedAt: '2024-01-15T09:00:00Z'
                name: Default Hours
                primary: true
                officeHours:
                  timezone: America/Los_Angeles
                  monday:
                  - start: 09:00
                    stop: '17:00'
                  tuesday:
                  - start: 09:00
                    stop: '17:00'
                  wednesday:
                  - start: 09:00
                    stop: '17:00'
                  thursday:
                  - start: 09:00
                    stop: '17:00'
                  friday:
                  - start: 09:00
                    stop: '17:00'
    post:
      tags:
      - Business Hours
      summary: Create Business Hours
      description: Creates a new business hours configuration for your organization.
      operationId: createBusinessHours
      requestBody:
        required: true
        description: Business hours configuration to create
        content:
          application/json:
            schema:
              title: BusinessHoursCreateRequest
              type: object
              required:
              - name
              - officeHours
              properties:
                name:
                  type: string
                  description: Name of the business hours configuration (max 200 characters)
                  example: Default Hours
                primary:
                  type: boolean
                  description: Whether this should be the primary business hours configuration
                  default: false
                  example: false
                officeHours:
                  title: OfficeHours
                  type: object
                  required:
                  - timezone
                  properties:
                    timezone:
                      type: string
                      description: IANA timezone identifier (e.g., America/Los_Angeles)
                      example: America/Los_Angeles
                    monday:
                      type: array
                      description: Schedule blocks for Monday
                      items:
                        title: ScheduleBlock
                        type: object
                        required:
                        - start
                        - stop
                        properties:
                          start:
                            type: string
                            description: Start time in HH:MM format (24-hour)
                            pattern: ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
                            example: 09:00
                          stop:
                            type: string
                            description: End time in HH:MM format (24-hour)
                            pattern: ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
                            example: '17:00'
                    tuesday:
                      type: array
                      description: Schedule blocks for Tuesday
                      items:
                        $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
                    wednesday:
                      type: array
                      description: Schedule blocks for Wednesday
                      items:
                        $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
                    thursday:
                      type: array
                      description: Schedule blocks for Thursday
                      items:
                        $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
                    friday:
                      type: array
                      description: Schedule blocks for Friday
                      items:
                        $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
                    saturday:
                      type: array
                      description: Schedule blocks for Saturday
                      items:
                        $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
                    sunday:
                      type: array
                      description: Schedule blocks for Sunday
                      items:
                        $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
                    exceptions:
                      type: array
                      description: Schedule exceptions (e.g., holidays)
                      items:
                        title: ScheduleException
                        type: object
                        required:
                        - name
                        - start
                        - stop
                        properties:
                          name:
                            type: string
                            description: Name of the exception (e.g., 'New Year's Day')
                            example: New Year's Day
                          start:
                            type: string
                            format: date-time
                            description: Start datetime of the exception
                            example: '2024-01-01T00:00:00Z'
                          stop:
                            type: string
                            format: date-time
                            description: End datetime of the exception
                            example: '2024-01-02T00:00:00Z'
                          scheduleBlocks:
                            type: array
                            description: Optional schedule blocks during the exception period (empty for closed)
                            items:
                              $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
            example:
              name: Weekend Support
              primary: false
              officeHours:
                timezone: America/Los_Angeles
                saturday:
                - start: '10:00'
                  stop: '16:00'
                sunday:
                - start: '10:00'
                  stop: '16:00'
      responses:
        '201':
          description: Business hours created
          content:
            application/json:
              schema:
                title: BusinessHours
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the business hours configuration
                    example: bh_WmeA3Y51Q5ayCAaZ1AotIA
                  version:
                    type: integer
                    description: Version number for optimistic concurrency control
                    example: 1
                  createdAt:
                    type: string
                    format: date-time
                    description: Timestamp when the business hours were created
                    example: '2024-01-15T09:00:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the business hours were last updated
                    example: '2024-01-15T09:00:00Z'
                  name:
                    type: string
                    description: Name of the business hours configuration
                    example: Default Hours
                  primary:
                    type: boolean
                    description: Whether this is the primary business hours configuration
                    example: true
                  officeHours:
                    $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                blankName:
                  summary: Name is required
                  value:
                    errors:
                    - attr: name
                      code: invalid
                      detail: name cannot be blank
                missingTimezone:
                  summary: Timezone is required
                  value:
                    errors:
                    - attr: officeHours.timezone
                      code: blank
                      detail: Timezone is required
                invalidTimezone:
                  summary: Invalid timezone
                  value:
                    errors:
                    - attr: officeHours.timezone
                      code: invalid
                      detail: Timezone is invalid
  /api/v1/business-hours/{businessHoursId}:
    parameters:
    - name: businessHoursId
      in: path
      description: ID of the business hours configuration
      required: true
      schema:
        type: string
        example: bh_WmeA3Y51Q5ayCAaZ1AotIA
    get:
      tags:
      - Business Hours
      summary: Get Business Hours
      description: Returns a single business hours configuration by its unique ID.
      operationId: getBusinessHoursById
      responses:
        '200':
          description: Business hours
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1business-hours/post/responses/201/content/application~1json/schema'
        '404':
          description: Business hours not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: not_exist
                  detail: business hours does not exist
    put:
      tags:
      - Business Hours
      summary: Update Business Hours
      description: Updates an existing business hours configuration. The `version` field must match the current version of the business hours to prevent conflicting updates.
      operationId: updateBusinessHours
      requestBody:
        required: true
        description: Updated business hours configuration
        content:
          application/json:
            schema:
              title: BusinessHoursUpdateRequest
              type: object
              required:
              - version
              - name
              - officeHours
              properties:
                version:
                  type: integer
                  description: Current version of the business hours (for optimistic concurrency)
                  example: 1
                name:
                  type: string
                  description: Name of the business hours configuration (max 200 characters)
                  example: Updated Hours
                primary:
                  type: boolean
                  description: Whether this should be the primary business hours configuration
                  example: false
                officeHours:
                  $ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours'
            example:
              version: 1
              name: Updated Business Hours
              primary: false
              officeHours:
                timezone: America/New_York
                monday:
                - start: 08:00
                  stop: '18:00'
                tuesday:
                - start: 08:00
                  stop: '18:00'
                wednesday:
                - start: 08:00
                  stop: '18:00'
                thursday:
                - start: 08:00
                  stop: '18:00'
                friday:
                - start: 08:00
                  stop: '18:00'
      responses:
        '200':
          description: Business hours updated
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1business-hours/post/responses/201/content/application~1json/schema'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Business hours not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: not_exist
                  detail: business hours does not exist
        '409':
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: version_outdated
                  detail: the version provided is outdated
    delete:
      tags:
      - Business Hours
      summary: Delete Business Hours
      description: Deletes a business hours configuration. The primary business hours configuration cannot be deleted.
      operationId: deleteBusinessHours
      responses:
        '204':
          description: Business hours deleted
        '400':
          description: Cannot delete primary business hours
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: invalid
                  detail: cannot delete primary business hours
        '404':
          description: Business hours not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: not_exist
                  detail: business hours does not exist
components:
  schemas:
    Error:
      type: object
      properties:
        attr:
          type: string
          description: Identifies the field causing the error
        code:
          type: string
          description: Code indicating the error type
        detail:
          type: string
          description: More details describing what went wrong
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users.

        To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.


        | user name   | password  |

        | ----------- | --------- |

        | agent email | API token |


        The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.


        ```shell

        curl -u user@organization.com:$GLADLY_API_TOKEN \

        https://organization.gladly.com/api/v1/organization

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
  tags:
  - Agents
  - Public Answer
  - Answer Management
  - Audiences
  - Business Hours
  - Communications
  - Conversations
  - Customers
  - Events
  - Export
  - Freeform Topics
  - Inboxes
  - Organization
  - Proactive Conversations
  - Reports
  - Tasks
  - Teams
  - User Identity
  - Topics
  - Webhooks
- name: Webhooks
  tags:
  - Summary
  - Payloads
- name: Lookup API
  tags:
  - Customer Lookup
- name: Resources
  tags:
  - Versioning
  - Error Handling
  - Rate Limit
  - Rich Content
  - Launching Soon