Skedulo Availability API

openapi: 3.2.0
info:
  title: Authentication Admin Availability API
  description: Skedulo Authentication API
  version: 1.0.0
servers:
- url: https://api.skedulo.com/auth
- url: https://api.uk.skedulo.com/auth
- url: https://api.ca.skedulo.com/auth
- url: https://api.au.skedulo.com/auth
tags:
- name: Availability
paths:
  /availability:
    get:
      summary: Fetch resource availability
      description: Fetch resource availability between a time period. The returned availability intervals are not trimmed to the request interval, so some intervals might extend beyond the request interval's bounds.
      operationId: getAvailability
      parameters:
      - name: resource_ids
        in: query
        description: Comma-separated string of resource IDs. There must be at least one ID and at most 200.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: Instant to fetch from.
        required: true
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        description: Instant to fetch to, must be after start and within 375 days of it.
        required: true
        schema:
          type: string
          format: date-time
      - name: availability
        in: query
        description: Should availability be returned
        required: false
        schema:
          type: boolean
          default: false
      - name: unavailability
        in: query
        description: Should unavailability be returned
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOKAvailability'
            result:
              examples:
                response:
                  value:
                    00059b46-320a-440e-979c-a3a657c14276:
                      available:
                      - start: '2018-07-24T23:00:00Z'
                        end: '2018-07-25T07:00:00Z'
                      - start: '2018-07-25T23:00:00Z'
                        end: '2018-07-26T07:00:00Z'
                      - start: '2018-07-26T23:00:00Z'
                        end: '2018-07-27T07:00:00Z'
                      unavailable:
                      - start: '2018-07-25T07:00:00Z'
                        end: '2018-07-25T23:00:00Z'
                      - start: '2018-07-26T07:00:00Z'
                        end: '2018-07-26T23:00:00Z'
                      availability: null
                      unavailability: null
                      shifts: []
                      regions:
                      - start: '2018-07-25T00:00:00Z'
                        end: '2018-07-25T23:00:00Z'
                        regionIds:
                        - 00039112-ce10-4a66-9bcd-4bdbd1ca8162
                        - 00034a75-7945-4011-b45e-e8044bd24b93
                      - start: '2018-07-25T23:00:00Z'
                        end: '2018-07-26T07:00:00Z'
                        regionIds:
                        - 00034a75-7945-4011-b45e-e8044bd24b93
                      - start: '2018-07-26T07:00:00Z'
                        end: '2018-07-27T00:00:00Z'
                        regionIds:
                        - 00039112-ce10-4a66-9bcd-4bdbd1ca8162
                        - 00034a75-7945-4011-b45e-e8044bd24b93
                    0005225f-f228-4309-8fde-50d5138be140:
                      available:
                      - start: '2018-07-24T23:00:00Z'
                        end: '2018-07-25T07:00:00Z'
                      - start: '2018-07-25T23:00:00Z'
                        end: '2018-07-26T07:00:00Z'
                      - start: '2018-07-26T23:00:00Z'
                        end: '2018-07-27T07:00:00Z'
                      unavailable:
                      - start: '2018-07-25T07:00:00Z'
                        end: '2018-07-25T23:00:00Z'
                      - start: '2018-07-26T07:00:00Z'
                        end: '2018-07-26T23:00:00Z'
                      availability: null
                      unavailability: null
                      shifts: []
                      regions:
                      - start: '2018-07-25T00:00:00Z'
                        end: '2018-07-27T00:00:00Z'
                        regionIds:
                        - 00039112-ce10-4a66-9bcd-4bdbd1ca8162
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Availability
    post:
      summary: Resource availability
      description: Fetch resource availability between a time period.
      operationId: postAvailability
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOKAvailability'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityParams'
        required: true
      tags:
      - Availability
  /availability/simple:
    post:
      summary: Fetch resource availability in a simplified format
      description: Fetch resource availability between a time period. This method is functionally the same as the GET method, but supports filters via the `availabilityFilterValues` array or `availabilityFilterEntityIds` map and replaces the deprecated GET method. Returned intervals might extend beyond the requested bounds.
      operationId: postAvailabilitySimple
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOKAvailabilitySimple'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleAvailabilityParams'
        required: true
      tags:
      - Availability
    get:
      deprecated: true
      summary: Fetch resource availability in a simplified format
      description: Fetch resource availability between a time period in a simplified format. The returned availability intervals are not trimmed to the request interval, so some intervals might extend beyond the request interval's bounds. This method is deprecated and replaced by the POST method.
      operationId: getAvailabilitySimple
      parameters:
      - name: resource_ids
        in: query
        description: Comma-separated string of resource IDs. There must be at least one ID and at most 200.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: Instant to fetch from.
        required: true
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        description: Instant to fetch to, must be after start and within 375 days of it.
        required: true
        schema:
          type: string
          format: date-time
      - name: mergedAvailabilities
        in: query
        description: If true, merged availability time intervals are returned with the result.
        required: false
        schema:
          type: boolean
          default: false
      - name: entries
        in: query
        description: If true or omitted, the list of availability entries is returned.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOKAvailabilitySimple'
            result:
              examples:
                response:
                  value:
                  - resourceId: 002eb23d-d576-47eb-aa14-80ac23c5d940
                    mergedAvailabilities:
                    - start: '2019-10-14T02:00:00Z'
                      end: '2019-10-14T03:00:00Z'
                    - start: '2019-10-14T05:00:00Z'
                      end: '2019-10-14T07:00:00Z'
                    entries:
                    - type: pattern
                      patternType: weekly
                      patternId: 002d6039-09f1-4dcb-915c-7edfff694999
                      patternResourceId: 002eb23d-d576-47eb-aa14-80ac23c5d940
                      name: Availability Pattern 1
                      description: Test pattern 1
                      start: '2019-10-14T22:00:00Z'
                      end: '2019-10-15T06:00:00Z'
                      available: true
                    - type: template
                      templateId: 000a1903-e8eb-4ca4-8f10-48107d4a1fe8
                      templateEntryId: 000b6dd3-76db-43dd-aef9-627efeeac847
                      name: Availability Template 1
                      end: '2019-10-15T06:00:00Z'
                      start: '2019-10-14T22:00:00Z'
                      available: true
                    - type: override
                      id: 00090d28-b5ab-4979-a8bb-4e87c53a03dc
                      start: '2019-10-20T08:00:00Z'
                      end: '2019-10-21T18:00:00Z'
                      available: true
                      overrideType: Overtime
                      notes: Some notes
                      status: Pending
                    - type: override
                      id: 0009eff1-845c-43f7-a339-0c070f6886dd
                      start: '2019-10-20T12:00:00Z'
                      end: '2019-10-21T16:00:00Z'
                      available: false
                      overrideType: Leave
                      notes: Some notes
                      status: Approved
                    - type: holiday
                      id: 000d1630-d879-4d29-b9fe-29dbcddad61a
                      name: Do Nothing Day
                      global: true
                      start: '2019-10-15T14:00:00Z'
                      end: '2019-10-16T14:00:00Z'
                      available: false
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Availability
  /availability/resources:
    post:
      summary: Fetch available resources
      description: Fetch available resources for given criteria in a time period. Must specify at least one of `resourceIds` or `regionIds`. Note that the `regionIds` filter only restricts the list of resources to query the availabilities for; resource availability is global, there is no concept of per-region availability in the system. The returned availability intervals are not trimmed to the request interval, so some intervals might extend beyond the request interval's bounds.
      operationId: postAvailableResources
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOKAvailability'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityCriteria'
        required: true
      tags:
      - Availability
  /availability/patterns:
    post:
      summary: Upsert availability patterns
      description: 'Create or update availability patterns and the related resources.


        If a UID is present on the pattern it will be updated, otherwise a new pattern will be created.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityPatternRequest'
      responses:
        '200':
          description: successful update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOkAvailabilityPatternResult'
        '201':
          description: successful insert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCreatedAvailabilityPatternResult'
        default:
          description: Error
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PatternRequestError'
                - $ref: '#/components/schemas/ParseErrorAvailabilityPatternResult'
      tags:
      - Availability
  /availability/migrate_to_patterns/status:
    get:
      summary: Retrieve information about the status of the Availability Template to Pattern migration.
      description: Retrieve information about the status of the Availability Template to Pattern migration. The Availability Patterns feature flag must be enabled in the org before calling this endpoint.
      operationId: availabilityMigrationStatus
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      totalTemplates:
                        type: integer
                        description: Total number of Availability Template objects in the org.
                      totalTemplateResources:
                        type: integer
                        description: Total number of Availability Template Resource objects in the org.
                      unmigratedTemplates:
                        type: integer
                        description: Total number of Availability Template objects in the org that have not been migrated to Availability Patterns yet.
                      unmigratedTemplateResources:
                        type: integer
                        description: Total number of Availability Template Resource objects in the org that have not been migrated to Availability Pattern Resources yet.
      tags:
      - Availability
  /availability/migrate_to_patterns/migrate:
    post:
      summary: Migrate all Availability Templates to Patterns in the org.
      description: 'Migrate all Availability Template and Availability Template Resource objects in the org to Availability Pattern and Availability Pattern Resource objects, respectively.


        The Availability Patterns feature flag must be enabled in the org before calling this endpoint. No data is deleted by the migration process. The operation is idempotent, meaning that calling the endpoint multiple times will migrate every object only once. If the operation was interrupted or not all objects could be migrated due to some errors, the endpoint should be called again to migrate the rest of the data (perhaps after fixing some problems manually first).'
      operationId: availabilityMigrationMigrate
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      totalTemplates:
                        type: integer
                        description: Total number of Availability Template objects in the org.
                      totalTemplateResources:
                        type: integer
                        description: Total number of Availability Template Resource objects in the org.
                      unmigratedTemplatesPreMigration:
                        type: integer
                        description: Total number of Availability Template objects in the org before the migration that have not been migrated to Availability Patterns yet.
                      unmigratedTemplateResourcesPreMigration:
                        type: integer
                        description: Total number of Availability Template Resource objects in the org before the migration that have not been migrated to Availability Pattern Resources yet.
                      unmigratedTemplatesPostMigration:
                        type: integer
                        description: Total number of Availability Template objects in the org after the migration that have not been migrated to Availability Patterns yet.
                      unmigratedTemplateResourcesPostMigration:
                        type: integer
                        description: Total number of Availability Template Resource objects in the org after the migration that have not been migrated to Availability Pattern Resources yet.
                      errors:
                        type: array
                        description: List of errors that occurred during the migration process.
                        items:
                          type: string
                          description: Detailed description of the error.
      tags:
      - Availability
components:
  schemas:
    PatternUpdateTooManyResults:
      description: When updating a pattern, if more than one result is returned from salesforce or postgres, this error is returned.
      type: object
      properties:
        too-many-update-results:
          description: Contains the message of the error.
          type: string
    ResultOkAvailabilityPatternResult:
      description: The UID of the successfully updated pattern.
      type: object
      properties:
        result:
          type: string
          format: uuid
    AvailabilityPatternRequest:
      description: The shape of the payload to successfully upsert a pattern.
      type: object
      properties:
        pattern:
          $ref: '#/components/schemas/AvailabilityPattern'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityPatternResource'
    AvailabilityEntryChunk:
      type: object
      required:
      - type
      - start
      - end
      properties:
        type:
          type: string
          enum:
          - template
          - pattern
          - holiday
          - custom
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    AvailabilityFilterValues:
      description: Array of availability preference groups used to filter availability based on resource preferences. Each group targets a single objectType (for example, Jobs) and contains an attribute-to-values map. There can be at most 50 groups per request, and each group's values object may contain up to 100 total values (sum of all attribute array lengths).
      type: array
      maxItems: 50
      items:
        type: object
        required:
        - objectType
        - values
        properties:
          objectType:
            type: string
            description: Object type to filter on (for example, Jobs).
            example: Jobs
          values:
            type: object
            description: Map of attribute names to non-empty arrays of values. Each key must be a valid field for the objectType. Each value is an array of one or more strings; the total number of values across all attributes in a group must not exceed 100.
            additionalProperties:
              type: array
              items:
                type: string
            example:
              Type:
              - Maintenance
              - Installation
              - Virtual
              Urgency:
              - Critical
          groupId:
            type: string
            description: Optional logical group identifier. When provided, must be non-blank and unique per objectType within a single request.
    PatternInsertError:
      description: When an insert has failed with DB/Salesforce errors.
      type: object
      properties:
        insert-failed:
          description: A list of errors
          type: array
          items:
            $ref: '#/components/schemas/PatternErrors'
    AvailabilityEntryTemplate:
      allOf:
      - $ref: '#/components/schemas/AvailabilityEntry'
      required:
      - entries
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
        entries:
          type: object
          additionalProperties:
            type: object
            required:
            - start
            - end
            properties:
              start:
                type: string
                format: date-time
              end:
                type: string
                format: date-time
              weekday:
                $ref: '#/components/schemas/AvailabilityWeekday'
    AvailabilityPatternDetailWeekly:
      allOf:
      - $ref: '#/components/schemas/AvailabilityPatternDetailBase'
      description: Weekly patterns describe patterns that span a single calendar week (always from Monday to Sunday). Optionally, there can be any number of empty padding weeks (unavailable all week) after the first week, after which the pattern repeats from the first week.
      required:
      - repeatWeeks
      - days
      properties:
        repeatWeeks:
          description: The repeat frequency of a single week pattern, must be a positive integer. The single weekly pattern is applied from the start time (which can be a non-complete week if the start time doesn't fall on a Monday), followed by `repeatWeeks - 1` number of "empty padding weeks" (unavailable all week).
          type: number
          example: 3
        days:
          type: array
          description: Weekdays that make up the pattern. Weekdays can be specified in any order. Not all weekdays must be specified (there can be holes in the pattern). Each weekday must appear only once in the pattern.
          items:
            type: object
            properties:
              weekday:
                $ref: '#/components/schemas/AvailabilityWeekday'
              intervals:
                $ref: '#/components/schemas/AvailabilityPatternIntervals'
    AvailabilityResult:
      description: '`availability` is only returned when the availability query parameter is set to `true` while `unavailability` is only returned when the unavailability query parameter is set to `true`.'
      type: object
      required:
      - available
      - unavailable
      properties:
        available:
          description: A flattened list of intervals when the resource is available to work. This is the inverse of unavailable. This will be constructed from either shifts if they are enabled or availability if they are not.
          type: array
          items:
            $ref: '#/components/schemas/TimeInterval'
        unavailable:
          description: A flattened list of intervals when the resource is unavailable to work. This is the inverse of available.
          type: array
          items:
            $ref: '#/components/schemas/TimeInterval'
        availability:
          $ref: '#/components/schemas/AvailabilityEntries'
        unavailability:
          $ref: '#/components/schemas/UnavailabilityEntries'
        shifts:
          description: A list of shifts for the resource in the requested interval. Draft shifts are excluded.
          type: array
          items:
            $ref: '#/components/schemas/Shift'
        regions:
          description: A list of the regions that the resource is available in in the request interval.
          type: array
          items:
            $ref: '#/components/schemas/AvailableRegionEntry'
    AvailabilityResultSimple:
      description: Describes the availability information of a single resource. `mergedAvailabilities` is only returned when the mergedAvailabilities query parameter is set to `true`.
      type: object
      required:
      - resourceId
      - mergedAvailabilities
      - entries
      properties:
        resourceId:
          description: ID of the resource.
          type: string
        mergedAvailabilties:
          description: A flattened list of intervals when the resource is available to work. These intervals are calculated by merging all availability entries together in the given time range according to the predefined precedence rules. This key only contains data if the `mergedAvailabilities` query string parameters was set to `true` in the request, otherwise it's set to null.
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TimeInterval'
        entries:
          description: The list of various availability entries in the given time interval applicable for the resource. Entries are sorted by the start time in ascending order.
          type:
          - array
          - 'null'
          items:
            oneOf:
            - $ref: '#/components/schemas/SimpleTemplateAvailabilityEntry'
            - $ref: '#/components/schemas/SimplePatternAvailabilityEntry'
            - $ref: '#/components/schemas/SimpleHolidayAvailabilityEntry'
            - $ref: '#/components/schemas/SimpleOverrideAvailabilityEntry'
            discriminator:
              propertyName: type
              mapping:
                template: '#/components/schemas/SimpleTemplateAvailabilityEntry'
                pattern: '#/components/schemas/SimplePatternAvailabilityEntry'
                holiday: '#/components/schemas/SimpleHolidayAvailabilityEntry'
                override: '#/components/schemas/SimpleOverrideAvailabilityEntry'
    TimeInterval:
      type: object
      required:
      - start
      - end
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    ResultCreatedAvailabilityPatternResult:
      description: The UID of the new pattern created.
      type: object
      properties:
        created:
          type: string
          format: uuid
    AvailabilityEntryChunkHoliday:
      allOf:
      - $ref: '#/components/schemas/AvailabilityEntryChunk'
      required:
      - id
      properties:
        id:
          type: string
    AvailabilityEntries:
      type: object
      required:
      - records
      - entries
      properties:
        records:
          description: An array containing an array of availabilities. Subsequent arrays have higher priority. Availabilities may overlap with themselves and with unavailabilities. Either templates or patterns are returned (but not both) depending on whether the availabilty patterns feature is enabled.
          type: array
          items:
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/AvailabilityEntryRecordTemplate'
              - $ref: '#/components/schemas/AvailabilityEntryRecordPattern'
              - $ref: '#/components/schemas/AvailabilityEntryRecordHoliday'
              - $ref: '#/components/schemas/AvailabilityEntryRecordCustom'
              discriminator:
                propertyName: type
                mapping:
                  template: '#/components/schemas/AvailabilityEntryRecordTemplate'
                  pattern: '#/components/schemas/AvailabilityEntryRecordPattern'
                  holiday: '#/components/schemas/AvailabilityEntryRecordHoliday'
                  custom: '#/components/schemas/AvailabilityEntryRecordCustom'
        entries:
          description: Contains untouched availability entries grouped by type and ID. Availabilities may overlap with themselves and also may overlap with an unavailability. Either templates or patterns are returned (but not both) depending on whether the availabilty patterns feature is enabled.
          type: object
          required:
          - holiday
          - custom
          properties:
            template:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AvailabilityEntryTemplate'
            pattern:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AvailabilityEntryPattern'
            holiday:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AvailabilityEntryHoliday'
            custom:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AvailabilityEntryCustom'
    SimplePatternAvailabilityEntry:
      allOf:
      - $ref: '#/components/schemas/SimpleAvailabilityEntryBase'
      description: Availability entry describing an availability pattern entry.
      required:
      - patternId
      - patternResourceId
      - name
      - description
      - patternType
      properties:
        patternId:
          description: ID of the availability pattern this pattern entry is part of. Note that there can be multiple entries in the response belonging to the same pattern.
          type: string
        patternResourceId:
          description: ID of the availability pattern resource record (which associates a pattern with a given resource).
          type: string
        description:
          description: Description of the pattern.
          type: string
        patternType:
          description: Type of the pattern, valid values are `weekly` and `custom`.
          type: string
    SimpleHolidayAvailabilityEntry:
      allOf:
      - $ref: '#/components/schemas/SimpleAvailabilityEntryBase'
      description: Availability entry describing a holiday entry.
      required:
      - id
      - name
      - global
      properties:
        id:
          description: ID of the holiday entry. Holiday IDs are unique.
          type: string
        name:
          description: ''
          type: string
        global:
          description: ''
          type: boolean
    Error:
      type: object
      required:
      - errorType
      - message
      properties:
        errorType:
          type: string
        message:
          type: string
    AvailabilityEntryPattern:
      allOf:
      - $ref: '#/components/schemas/AvailabilityEntry'
      required:
      - patternId
      - patternResourceId
      - patternType
      properties:
        patternId:
          type: string
        patternResourceId:
          type: string
        patternType:
          type: string
          enum:
          - custom
          - weekly
    AvailabilityEntryRecordCustom:
      allOf:
      - $ref: '#/components/schemas/AvailabilityEntryRecord'
    AvailabilityParams:
      required:
      - resourceIds
      - start
      - end
      properties:
        resourceIds:
          description: Non-empty array of resource IDs. There is a maximum limit of 200.
          type: array
          items:
            type: string
        start:
          description: Instant to fetch from.
          type: string
          format: date-time
        end:
          description: Instant to fetch to, must be after start and within 375 days of it.
          type: string
          format: date-time
        availability:
          description: Should availability be returned.
          type: boolean
          default: false
        unavailability:
          description: Should unavailability be returned.
          type: boolean
          default: false
        availabilityFilterValues:
          $ref: '#/components/schemas/AvailabilityFilterValues'
        availabilityFilterEntityIds:
          $ref: '#/components/schemas/AvailabilityFilterEntityIds'
    AvailabilityFilterEntityIds:
      description: Map of object type to entity IDs used to resolve availability filter values. Instead of providing availabilityFilterValues directly, supply entity references by type and UID; the system fetches the entities, evaluates configured record filters, and derives the filter values automatically. Each entity's UID becomes the groupId in the resolved filter values. Cannot be combined with availabilityFilterValues.
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      example

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/skedulo/refs/heads/main/openapi/skedulo-availability-api-openapi.yml