Skedulo Availability API
The Availability API from Skedulo — 6 operation(s) for availability.
OpenAPI Specification
openapi: 3.0.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:
PatternNotFound:
description: When a pattern is being updated but does not exist, this error is returned.
type: object
properties:
pattern-not-found:
description: The UID of the missing pattern.
type: string
ResultOKAvailability:
type: object
properties:
result:
$ref: '#/components/schemas/AvailabilityResults'
AvailabilityEntry:
type: object
required:
- name
properties:
description:
type: string
name:
type: string
PatternResourceNotFound:
description: When attempting to save and the pattern-resource relationship couldn't be found.
type: object
properties:
pattern-resource-not-found:
description: The UID of the pattern-resource relationship.
type: string
AvailabilityEntryRecord:
type: object
required:
- type
- start
- end
- name
discriminator:
propertyName: type
properties:
type:
type: string
enum:
- template
- pattern
- holiday
- custom
start:
type: string
format: date-time
end:
type: string
format: date-time
name:
type: string
AvailabilityPatternDetailBase:
type: object
description: The shape of the availability patterns that determine a resource's availability.
required:
- type
properties:
type:
type: string
enum:
- custom
- weekly
SimpleAvailabilityEntryBase:
type: object
description: Availability entry object that deterimnes the resources's availability.
required:
- type
- start
- end
- available
properties:
type:
description: The type of the availability entry. Valid values are `template`, `pattern`, `override`, and `holiday`.
type: string
start:
description: The UTC datetime at which the availability entry beings applying to the resource (this exact point in time included).
type: string
format: date-time
end:
description: The UTC datetime at which the availability entry stops applying to the resource (this exact point in time excluded).
type: string
format: date-time
available:
description: Flag indicating whether this is an availability or unavailability entry.
type: boolean
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:
Jobs:
- 8ab1de64-ee5b-418f-b303-80bd3baec88f
- 3979c7a9-fc9a-48b0-aab1-8989a16c468d
Activities:
- ab1696b9-163b-4340-9473-8a0cff1e996e
PatternErrors:
description: The list of DB/Salesforce errors.
type: object
required:
- code
- message
properties:
code:
description: The error code.
type: string
message:
description: The error message.
type: string
AvailabilityResultsSimple:
type: array
description: Array of AvailabilityResultSimple objects, each object corresponds to the availability information of a single resource.
items:
$ref: '#/components/schemas/AvailabilityResultSimple'
AvailabilityEntryCustom:
allOf:
- $ref: '#/components/schemas/AvailabilityEntry'
required:
- start
- end
- notes
- createdDate
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
notes:
type: string
status:
type: string
availabilityType:
type: string
createdDate:
type: string
format: date-time
AvailabilityEntryRecordCustom:
allOf:
- $ref: '#/components/schemas/AvailabilityEntryRecord'
ResultOKAvailabilitySimple:
type: object
properties:
result:
$ref: '#/components/schemas/AvailabilityResultsSimple'
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
AvailabilityWeekday:
description: The days of the week
type: string
enum:
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
PatternResourceUpdateFailed:
description: Returned when updating a pattern resource details fails.
type: object
properties:
insert-failed:
type: object
properties:
errors:
description: The lis of errors received when attempt to update pattern resources.
type: array
items:
type: string
UIDs:
description: A list of IDs for the related pattern resources.
type: array
items:
type: string
resources:
description: A list of resource IDs that were used during the update.
type: array
items:
type: string
AvailableRegionEntry:
type: object
required:
- start
- end
- regionIds
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
regionIds:
type: array
items:
description: Region ID
type: string
SimpleOverrideAvailabilityEntry:
allOf:
- $ref: '#/components/schemas/SimpleAvailabilityEntryBase'
description: Availability entry describing an availability override.
required:
- id
- overrideType
- notes
- status
properties:
id:
description: ID of the availability override. Override IDs are unique.
type: string
overrideType:
description: Type of the override (e.g. `Leave`, `Occupied`, `Overtime`, `Sick`, etc.)
type: string
notes:
description: User defined notes for this override.
type: string
status:
description: Status of the override, valid values are `Approved`, `Declined` and `Pending`.
type: string
Shift:
type: object
required:
- UID
- start
- end
properties:
UID:
type: string
start:
type: string
format: date-time
end:
type: string
format: date-time
locationId:
type: string
regionId:
type: string
displayName:
type: string
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
nullable: true
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
nullable: true
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'
AvailabilityPatternDetailCustom:
allOf:
- $ref: '#/components/schemas/AvailabilityPatternDetailBase'
description: Custom patterns describe patterns that span N-number of days. Not all days have to be specified (there can be holes in the pattern). The pattern repeats after lengthDays number of days.
required:
- lengthDays
- days
properties:
lengthDays:
description: The length of the pattern in days, must be a positive integer.
type: number
example: 5
days:
type: array
description: Days that make up the pattern. Days can be specified in any order. A day with the same index cannot appear more than once. It is allowed to have holes in the pattern. The number of days specified must be less than or equal to the lengthDays property.
items:
type: object
properties:
day:
$ref: '#/components/schemas/AvailabilityDayWithIndex'
intervals:
$ref: '#/components/schemas/AvailabilityPatternIntervals'
AvailabilityResults:
type: object
description: Key of resource ID to AvailabilityResult.
additionalProperties:
$ref: '#/components/schemas/AvailabilityResult'
AvailabilityPatternIntervals:
type: array
description: A list of time intervals that determine when a resource is available on the day. At least one time interval must be specified for a day; if more intervals are specified, they must be non-overlapping. Intervals are half-open (the start time is included in the interval but the end time is excluded).
items:
type: object
required:
- startTime
- endTime
properties:
startTime:
type: string
description: Start time of the interval in local time (24-hour ISO format).
format: HH:mm
example: 08:10
endTime:
type: string
description: End time of the interval in local time (24-hour ISO format). Start time must be before end time, except for full days are which are represented as 00:00-00:00, and intervals that extend until the end of the day (e.g. 13:00-00:00).
format: HH:mm
example: '15:00'
recordFilters:
type: array
description: Optional list of record filter UIDs that define availability preferences for this interval. Each referenced filter represents a condition (for example, job type or urgency) that is evaluated during an availability request and must match the request’s availabilityFilterValues for the interval to apply. Omit or leave empty for unconditional availability.
items:
type: string
uniqueItems: true
example:
- 3b6a27bc-3e0f-4e3d-8d9e-5f8b3b2c9f10
- 0a1b2c3d-4e5f-6789-abcd-ef0123456789
AvailabilityEntryChunkHoliday:
allOf:
- $ref: '#/components/schemas/AvailabilityEntryChunk'
required:
- id
properties:
id:
type: string
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
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'
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 s
# --- 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