Create a new shift
POST /v1/shifts
- Scope
shifts:write- Roles
- admin, scheduler
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
62 top-level fields; 28 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
title | string or null | Example |
description | string or null | Example |
isPublished | boolean or null | false saves a draft and relaxes nearly every other requirement; true publishes and triggers status auto-update plus the published notifications. Example |
duration | number or null | Hours — used when setting location.onsite/remote slot capacity. Example |
allowPointOfContact | string or null | Any non-empty value auto-fills requestorEmail/requestorPhone from the client's primary location contact, overwriting whatever was sent. Example |
requestorName | string or null | Not validated; stored with the shift and shown in the list and sidebar. Example |
requestorEmail | string (email) or null | Example |
requestorPhone | string or null | Example |
requestorCountryCode | string or null | Example |
requestorPhoneType | string or null | One of: |
requestorPhoneExtension | string or null | Example |
assignTo | string or null | Prunes the payload before anything is stored: assignTo=client drops assignClient, assignTo=organization drops client — so a contradictory pair never reaches the relation handlers. One of: |
billTo | string or null | clients (with a non-empty assignClients) switches the shift to per-client billing. One of: |
client | object or null (2 nested) | The single client. Required when assignTo=client. Dropped outright when assignTo=organization, and ignored when assignClients/assignClient is sent in the same payload. |
assignClients | array of object or null (2 nested) | The shift's full client roster. Not validated. Dropped outright when assignTo=client. assignClient (singular key, same array shape) is accepted as a legacy alias. |
assignClient | array of object or null (1 nested) | Legacy alias for assignClients — same shape, same effect. |
assignClientLocation | array of object or null (1 nested) | Not validated. Sets the shift's client locations; assignments have no equivalent. |
billingDistribution | string or null | How the shift's cost is divided across multiple clients. Only meaningful on a multi-client shift. One of: |
clientAllocations | array of object or null (2 nested) | Per-client service charges, read when billTo=clients. Not validated on create — unlike the update endpoint, there is no check that the charges sum to a declared total, and totalServiceCharge is not read here at all. |
billingOption | string or null | Top-level fallback for location.billingOption, which wins when both are sent. Defaults to primary. Unlike the shift update endpoint, this top-level form IS read on create. Example |
location | object or null (55 nested) | locationType is required when isPublished=true. |
timezone | string or null | Required when isPublished=true. Defaults to the organization's timezone when omitted. Example |
scheduleType | string or null | Selects which wrapper below the slots are read from; an unrecognized value is rejected. One of: |
oneTime | object or null (10 nested) | Read only when scheduleType=one_time. |
multiDay | object or null (10 nested) | Read only when scheduleType=multi_day. |
recurring | object or null (10 nested) | Read only when scheduleType=recurring. |
priority | object or null (2 nested) | |
status required | object (2 nested) | Required. Send {id} alone and the label is filled from the statuses table. Omit the id and the status defaults to Still Seeking when publishing, On Hold when saving a draft. |
rateType | object or null (2 nested) | |
shiftBlock required | object (1 nested) | Required — a shift is always created inside a shift block, which an assignment has no equivalent of. |
broadcast | object or null (2 nested) | Required when isPublished=true. |
broadcastNotify | boolean or null | Example |
broadcastAudience | array of object or null (1 nested) | |
enableBroadcastBestMatch | boolean or null | When true, assignProviders is no longer required for a published direct shift. Example |
assignmentMethod | string or null | Required when isPublished=true. One of: |
assignProviders | array of object or null (7 nested) | Required for a published direct shift unless enableBroadcastBestMatch is true. A provider that cannot be attached is reported back in data.skippedProviders rather than failing the create. |
userRestricted | array of object or null (2 nested) | |
userPreferred | array of object or null (2 nested) | |
requirementAndPreferences | array of object or null (3 nested) | Not validated; saved as the shift's requirements and preferences. |
notesToServiceProvider | string or null | Example |
internalNotes | string or null | Example |
externalNotes | string or null | Example |
allowPartialCoverage | boolean or null | Example |
partialDuration | array of object or null (4 nested) | Partial coverage windows — required when allowPartialCoverage is true. |
overrideSingleRate | boolean or null | Example |
overrideBufferTime | boolean or null | Example |
overrideClientPreference | boolean or null | Example |
clientPreferences | object (8 nested) | Which of the client's stored requirements and preferences the scheduler overrode on this work item. Each flag set to true means that kind is overridden. Stored as sent. |
overrideServiceProviderPreference | boolean or null | Example |
serviceProviderPreferences | object (12 nested) | Provider-side rules the scheduler overrode on this work item. Stored as sent. |
requireVerifiedTimeDocumentation | boolean or null | Example |
reimbursableExpenses | array of object or null (2 nested) | |
providerExpenses | array of object or null (17 nested) | Provider expenses. |
invoiceStatus | object or null (1 nested) | Only stored when billing is enabled for shifts and the status is a completed one; otherwise cleared. |
payStatus | object or null (1 nested) | Only stored when payables are enabled for shifts and the status is a completed one; otherwise cleared. |
estimatedCost | object or null | Client-calculated rate preview. |
isDuplicated | boolean or null | Set when this create duplicates an existing shift; records a duplication audit event instead of a plain create. Example |
duplicateId | string or null | The shift being duplicated. Read only with isDuplicated=true. Example |
customFields | object or null | Custom field values keyed by field id. File-typed values are attached once the shift exists. |
externalCustomFields | object or null | Values for the external custom fields, keyed by field id. |
documents | array of object or null (2 nested) | |
cancellationDetails | object (7 nested) | Only meaningful when creating a shift directly in a canceled status. cancellationReason/cancellationCausedBy/billableForCancellation/billCancellationClient/payCancellationProvider are also accepted flat at the top level; the nested value wins if both are sent. |
Nested fields
client 2 fields
| Field | Type | Description |
|---|---|---|
client.id | string | Example |
client.label | string | Example |
assignClients 2 fields
| Field | Type | Description |
|---|---|---|
assignClients[].id | string | Example |
assignClients[].label | string | Example |
assignClient 1 fields
| Field | Type | Description |
|---|---|---|
assignClient[].id | string | Example |
assignClientLocation 1 fields
| Field | Type | Description |
|---|---|---|
assignClientLocation[].id | string | Example |
clientAllocations 2 fields
| Field | Type | Description |
|---|---|---|
clientAllocations[].clientId | string | Example |
clientAllocations[].serviceCharges | number | Example |
location 55 fields
| Field | Type | Description |
|---|---|---|
location.locationType | string | One of: |
location.billingLocationSource | string or null | One of: |
location.billingOrganizationLocationId | string or null | A {id} object is also accepted. Nested here only — there is no top-level fallback for this one. Example |
location.billingClientLocationId | string or null | A {id} object is also accepted. Nested here only — there is no top-level fallback for this one. Example |
location.billingOption | string or null | Wins over the top-level billingOption. Example |
location.onsite | object or null | |
location.onsite.onSiteType | string | One of: |
location.onsite.organizationLocationId | object or null | |
location.onsite.organizationLocationId.id | string | Example |
location.onsite.clientLocationId | object or null | |
location.onsite.clientLocationId.id | string | Example |
location.onsite.manualLocation | object or null | |
location.onsite.manualLocation.addressLine1 | string | Example |
location.onsite.manualLocation.city | string | Example |
location.onsite.manualLocation.state | object | |
location.onsite.manualLocation.postalCode | string | Example |
location.onsite.manualLocationContact | object or null | contactPhone is required (when published) unless videoPhone is sent. The server derives fullManuallyContactPhone/fullManuallyContactVideoPhone from these sub-fields — those two are output, not accepted input. |
location.onsite.manualLocationContact.contactName | string | Example |
location.onsite.manualLocationContact.contactEmail | string (email) | Example |
location.onsite.manualLocationContact.contactPhone | string or null | Example |
location.onsite.manualLocationContact.contactCountryCode | string or null | Example |
location.onsite.manualLocationContact.contactPhoneExtension | string or null | Example |
location.onsite.manualLocationContact.videoPhone | string or null | Example |
location.onsite.manualLocationContact.videoPhoneCountryCode | string or null | Example |
location.onsite.onDemandLocationType | string or null | One of: |
location.onsite.onDemandLink | string or null | Example |
location.onsite.onDemandAccessInstructions | string or null | Example |
location.onsite.onDemandOrganizationLocationId | object or null | |
location.onsite.onDemandOrganizationLocationId.id | string | Example |
location.onsite.onDemandClientLocationId | object or null | |
location.onsite.onDemandClientLocationId.id | string | Example |
location.onsite.onDemandManualLocation | object or null | |
location.onsite.onDemandManualLocation.addressLine1 | string | Example |
location.onsite.onDemandManualLocation.city | string | Example |
location.onsite.onDemandManualLocation.state | object | |
location.onsite.onDemandManualLocation.postalCode | string | Example |
location.onsite.serviceTypes | array of object | |
location.onsite.serviceTypes[].id | integer | Example |
location.onsite.serviceTypeBreakdown | array of object | The sum of providerTypeBreakdown.totalProviders must equal totalProviders. |
location.onsite.serviceTypeBreakdown[].serviceTypeId | integer | Example |
location.onsite.serviceTypeBreakdown[].totalProviders | integer | Example |
location.onsite.serviceTypeBreakdown[].providerTypeBreakdown | array of object | |
location.remote | object or null | |
location.remote.remoteType | string | One of: |
location.remote.meetingPlatform | string or null | Example |
location.remote.meetingLink | string or null | Example |
location.remote.meetingPhone | string or null | Example |
location.remote.meetingCountryCode | string or null | Example |
location.remote.meetingExtension | string or null | Example |
location.remote.accessInstruction | string or null | Example |
location.remote.onDemandLink | string or null | Example |
location.remote.onDemandAccessInstructions | string or null | Example |
location.remote.serviceTypes | array of object | |
location.remote.serviceTypes[].id | integer | Example |
location.remote.serviceTypeBreakdown | array of object |
oneTime 10 fields
| Field | Type | Description |
|---|---|---|
oneTime.dateTimeSlots | array of object | |
oneTime.dateTimeSlots[].startDate | string (date) | Example |
oneTime.dateTimeSlots[].endDate | string (date) | Example |
oneTime.dateTimeSlots[].timeSlots | array of object | |
oneTime.dateTimeSlots[].timeSlots[].startTime | string | Example |
oneTime.dateTimeSlots[].timeSlots[].endTime | string | Example |
oneTime.dateTimeSlots[].scheduleFrequency | string or null | One of: |
oneTime.dateTimeSlots[].scheduleInterval | integer or null | Example |
oneTime.dateTimeSlots[].scheduleDays | array of string or null | Days of week this slot recurs on, when scheduleFrequency=weekly. |
oneTime.dateTimeSlots[].recurrenceOption | string or null | How the recurrence ends — e.g. an end date or an occurrence count. Example |
multiDay 10 fields
| Field | Type | Description |
|---|---|---|
multiDay.dateTimeSlots | array of object | |
multiDay.dateTimeSlots[].startDate | string (date) | Example |
multiDay.dateTimeSlots[].endDate | string (date) | Example |
multiDay.dateTimeSlots[].timeSlots | array of object | |
multiDay.dateTimeSlots[].timeSlots[].startTime | string | Example |
multiDay.dateTimeSlots[].timeSlots[].endTime | string | Example |
multiDay.dateTimeSlots[].scheduleFrequency | string or null | One of: |
multiDay.dateTimeSlots[].scheduleInterval | integer or null | Example |
multiDay.dateTimeSlots[].scheduleDays | array of string or null | Days of week this slot recurs on, when scheduleFrequency=weekly. |
multiDay.dateTimeSlots[].recurrenceOption | string or null | How the recurrence ends — e.g. an end date or an occurrence count. Example |
recurring 10 fields
| Field | Type | Description |
|---|---|---|
recurring.dateTimeSlots | array of object | |
recurring.dateTimeSlots[].startDate | string (date) | Example |
recurring.dateTimeSlots[].endDate | string (date) | Example |
recurring.dateTimeSlots[].timeSlots | array of object | |
recurring.dateTimeSlots[].timeSlots[].startTime | string | Example |
recurring.dateTimeSlots[].timeSlots[].endTime | string | Example |
recurring.dateTimeSlots[].scheduleFrequency | string or null | One of: |
recurring.dateTimeSlots[].scheduleInterval | integer or null | Example |
recurring.dateTimeSlots[].scheduleDays | array of string or null | Days of week this slot recurs on, when scheduleFrequency=weekly. |
recurring.dateTimeSlots[].recurrenceOption | string or null | How the recurrence ends — e.g. an end date or an occurrence count. Example |
priority 2 fields
| Field | Type | Description |
|---|---|---|
priority.id | integer | Example |
priority.label | string | Example |
status 2 fields
| Field | Type | Description |
|---|---|---|
status.id | integer or null | Example |
status.label | string or null | Example |
rateType 2 fields
| Field | Type | Description |
|---|---|---|
rateType.id | integer | Example |
rateType.label | string | Example |
shiftBlock 1 fields
| Field | Type | Description |
|---|---|---|
shiftBlock.id | integer | Example |
broadcast 2 fields
| Field | Type | Description |
|---|---|---|
broadcast.id | string | Example |
broadcast.label | string | Example |
broadcastAudience 1 fields
| Field | Type | Description |
|---|---|---|
broadcastAudience[].id | string | Example |
assignProviders 7 fields
| Field | Type | Description |
|---|---|---|
assignProviders[].id | string | Example |
assignProviders[].serviceType | integer | Example |
assignProviders[].locationType | string | One of: |
assignProviders[].serviceProviderType | integer or null | Provider type the provider fills. Inferred when the service type has only one. Example |
assignProviders[].partialReason | string or null | Why a partly matching provider was assigned anyway. |
assignProviders[].notAvailableReason | string or null | Why an unavailable provider was assigned anyway. |
assignProviders[].visibilityReason | string or null | How the provider came to be listed. Defaults to partial_match_allowed when partialReason is sent, else full_match. Example |
userRestricted 2 fields
| Field | Type | Description |
|---|---|---|
userRestricted[].id | string | Example |
userRestricted[].label | string | Example |
userPreferred 2 fields
| Field | Type | Description |
|---|---|---|
userPreferred[].id | string | Example |
userPreferred[].label | string | Example |
requirementAndPreferences 3 fields
| Field | Type | Description |
|---|---|---|
requirementAndPreferences[].serviceType | integer | Example |
requirementAndPreferences[].serviceProviderCertifications | array of object | Required when serviceType is set. |
requirementAndPreferences[].serviceProviderCertifications[].serviceProviderType | integer | Example |
partialDuration 4 fields
| Field | Type | Description |
|---|---|---|
partialDuration[].startDate | string (date) | Example |
partialDuration[].endDate | string (date) | Example |
partialDuration[].startTime | string | Example |
partialDuration[].endTime | string | Example |
clientPreferences 8 fields
| Field | Type | Description |
|---|---|---|
clientPreferences.clearance | boolean or null | |
clientPreferences.skill | boolean or null | |
clientPreferences.certifications | boolean or null | |
clientPreferences.specialization | boolean or null | |
clientPreferences.gender | boolean or null | |
clientPreferences.restrictedServiceProvider | boolean or null | |
clientPreferences.restrictedConsumers | boolean or null | |
clientPreferences.preferredServiceProvider | boolean or null |
serviceProviderPreferences 12 fields
| Field | Type | Description |
|---|---|---|
serviceProviderPreferences.overrideBufferTime | boolean or null | |
serviceProviderPreferences.onSite | boolean or null | |
serviceProviderPreferences.remote | boolean or null | |
serviceProviderPreferences.assignmentLimits | boolean or null | |
serviceProviderPreferences.availability | boolean or null | |
serviceProviderPreferences.locationDistance | boolean or null | |
serviceProviderPreferences.restrictedConsumers | boolean or null | |
serviceProviderPreferences.restrictedClients | boolean or null | |
serviceProviderPreferences.restrictedServiceProviders | boolean or null | |
serviceProviderPreferences.preferredConsumers | boolean or null | |
serviceProviderPreferences.preferredClients | boolean or null | |
serviceProviderPreferences.preferredServiceProviders | boolean or null |
reimbursableExpenses 2 fields
| Field | Type | Description |
|---|---|---|
reimbursableExpenses[].id | integer | Example |
reimbursableExpenses[].label | string | Example |
providerExpenses 17 fields
| Field | Type | Description |
|---|---|---|
providerExpenses[].entityId | string or null | Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved. Example |
providerExpenses[].providerId required | string | Example |
providerExpenses[].expenses | array of object | |
providerExpenses[].expenses[].id | integer or null | Existing expense id to update; omit to create. Example |
providerExpenses[].expenses[].name required | string | Example |
providerExpenses[].expenses[].amount | number or null | min 0.01. Example |
providerExpenses[].expenses[].expense | number or null | Unit amount, multiplied by quantity. min 0.01. Example |
providerExpenses[].expenses[].quantity | number or null | min 0.01. Example |
providerExpenses[].expenses[].billTo | string or null | One of: |
providerExpenses[].expenses[].document | string (binary) or null | Receipt: pdf, jpg, jpeg or png, max 2 MB. |
providerExpenses[].expenses[].isDefault | boolean or null | |
providerExpenses[].expenses[].reimbursement_basic | string or null | Reimbursement basis of a freeform custom expense. One of: |
providerExpenses[].expenses[].expenseType | string or null | One of: |
providerExpenses[].expenses[].rate | number or null | Required when reimbursement_basic is percentage. min 0. |
providerExpenses[].expenses[].sourceReimbursableExpense | object | Catalog category a custom line is seeded from. |
providerExpenses[].expenses[].sourceReimbursableExpense.id | integer or string | Example |
providerExpenses[].expenses[].sourceReimbursableExpense.label | string or null | Example |
invoiceStatus 1 fields
| Field | Type | Description |
|---|---|---|
invoiceStatus.id | string | Example |
payStatus 1 fields
| Field | Type | Description |
|---|---|---|
payStatus.id | string | Example |
documents 2 fields
| Field | Type | Description |
|---|---|---|
documents[].file | string (binary) | |
documents[].fileName | string | Example |
cancellationDetails 7 fields
| Field | Type | Description |
|---|---|---|
cancellationDetails.cancellationReason | string | Example |
cancellationDetails.cancellationCausedBy | string or object | Who caused the cancellation, as a label or a {id, label} object. |
cancellationDetails.cancellationCausedByClient | object or array of object | The client or clients responsible, when the cause is a client: one {id, label} or a list. |
cancellationDetails.cancellationCausedByProvider | object or array of object | The provider or providers responsible, when the cause is a provider: one {id, label} or a list. |
cancellationDetails.billableForCancellation | boolean | Example |
cancellationDetails.billCancellationClient | boolean | When billableForCancellation is true, at least one of billCancellationClient/payCancellationProvider must also be true. Example |
cancellationDetails.payCancellationProvider | boolean | Example |
Example
{
"title": "Weekend overnight coverage",
"description": "description of the shift",
"isPublished": true,
"duration": 1.5,
"allowPointOfContact": "client_poc",
"requestorName": "John Doe",
"requestorEmail": "user@example.com",
"requestorPhone": "1234567890",
"requestorCountryCode": "+1",
"requestorPhoneType": "sms_and_voice",
"requestorPhoneExtension": "123",
"assignTo": "client",
"billTo": "clients",
"client": {
"id": "CLT-KBX0Q6",
"label": "Client Name"
},
"assignClients": [
{
"id": "CLT-KBX0Q6",
"label": "Client Name"
}
],
"assignClient": [
{
"id": "CLT-KBX0Q6"
}
],
"assignClientLocation": [
{
"id": "1"
}
],
"billingDistribution": "split_evenly",
"clientAllocations": [
{
"clientId": "CLT-KBX0Q6",
"serviceCharges": 125.5
}
],
"billingOption": "primary",
"location": {
"locationType": "onsite",
"billingLocationSource": "client",
"billingOrganizationLocationId": "1",
"billingClientLocationId": "1",
"billingOption": "primary",
"onsite": {
"onSiteType": "client",
"organizationLocationId": {
"id": "1"
},
"clientLocationId": {
"id": "1"
},
"manualLocation": {
"addressLine1": "123 Main St",
"city": "Springfield",
"state": {
"id": 1
},
"postalCode": "12345"
},
"manualLocationContact": {
"contactName": "Jane Roe",
"contactEmail": "jane@example.test",
"contactPhone": "1234567890",
"contactCountryCode": "+1",
"contactPhoneExtension": "123",
"videoPhone": "1234567890",
"videoPhoneCountryCode": "+1"
},
"onDemandLocationType": "organization",
"onDemandLink": "https://meet.example.test/room",
"onDemandAccessInstructions": "Dial in 5 minutes early",
"onDemandOrganizationLocationId": {
"id": "1"
},
"onDemandClientLocationId": {
"id": "1"
},
"onDemandManualLocation": {
"addressLine1": "123 Main St",
"city": "Springfield",
"state": {
"id": 1
},
"postalCode": "12345"
},
"serviceTypes": [
{
"id": 1
}
],
"serviceTypeBreakdown": [
{
"serviceTypeId": 1,
"totalProviders": 2,
"providerTypeBreakdown": [
null
]
}
]
},
"remote": {
"remoteType": "scheduled",
"meetingPlatform": "zoom",
"meetingLink": "https://zoom.us/j/123",
"meetingPhone": "1234567890",
"meetingCountryCode": "+1",
"meetingExtension": "123",
"accessInstruction": "Dial in 5 minutes early",
"onDemandLink": "https://meet.example.test/room",
"onDemandAccessInstructions": "Dial in 5 minutes early",
"serviceTypes": [
{
"id": 1
}
],
"serviceTypeBreakdown": [
{}
]
}
},
"timezone": "America/New_York",
"scheduleType": "recurring",
"oneTime": {
"dateTimeSlots": [
{
"startDate": "2024-01-01",
"endDate": "2024-01-04",
"timeSlots": [
{
"startTime": "10:00",
"endTime": "12:00"
}
],
"scheduleFrequency": "daily",
"scheduleInterval": 2,
"scheduleDays": [
"monday"
],
"recurrenceOption": "on_date"
}
]
},
"multiDay": {
"dateTimeSlots": [
{
"startDate": "2024-01-01",
"endDate": "2024-01-04",
"timeSlots": [
{
"startTime": "10:00",
"endTime": "12:00"
}
],
"scheduleFrequency": "daily",
"scheduleInterval": 2,
"scheduleDays": [
"monday"
],
"recurrenceOption": "on_date"
}
]
},
"recurring": {
"dateTimeSlots": [
{
"startDate": "2024-01-01",
"endDate": "2024-01-04",
"timeSlots": [
{
"startTime": "10:00",
"endTime": "12:00"
}
],
"scheduleFrequency": "daily",
"scheduleInterval": 2,
"scheduleDays": [
"monday"
],
"recurrenceOption": "on_date"
}
]
},
"priority": {
"id": 1,
"label": "Priority Label"
},
"status": {
"id": 1,
"label": "Status Label"
},
"rateType": {
"id": 1,
"label": "Rate Type Label"
},
"shiftBlock": {
"id": 1
},
"broadcast": {
"id": "on",
"label": "On"
},
"broadcastNotify": true,
"broadcastAudience": [
{
"id": "SPR-H6OUI3"
}
],
"enableBroadcastBestMatch": true,
"assignmentMethod": "direct",
"assignProviders": [
{
"id": "SPR-H6OUI3",
"serviceType": 1,
"locationType": "onsite",
"serviceProviderType": 2,
"partialReason": "string",
"notAvailableReason": "string",
"visibilityReason": "client_selected"
}
],
"userRestricted": [
{
"id": "SPR-H6OUI3",
"label": "User 1"
}
],
"userPreferred": [
{
"id": "SPR-DQRNUV",
"label": "User 1"
}
],
"requirementAndPreferences": [
{
"serviceType": 1,
"serviceProviderCertifications": [
{
"serviceProviderType": 1
}
]
}
],
"notesToServiceProvider": "Reason for preference if any",
"internalNotes": "Internal notes about the shift",
"externalNotes": "Notes visible to the client",
"allowPartialCoverage": true,
"partialDuration": [
{
"startDate": "2024-01-01",
"endDate": "2024-01-01",
"startTime": "09:00",
"endTime": "10:00"
}
],
"overrideSingleRate": true,
"overrideBufferTime": true,
"overrideClientPreference": true,
"clientPreferences": {
"clearance": true,
"skill": true,
"certifications": true,
"specialization": true,
"gender": true,
"restrictedServiceProvider": true,
"restrictedConsumers": true,
"preferredServiceProvider": true
},
"overrideServiceProviderPreference": true,
"serviceProviderPreferences": {
"overrideBufferTime": true,
"onSite": true,
"remote": true,
"assignmentLimits": true,
"availability": true,
"locationDistance": true,
"restrictedConsumers": true,
"restrictedClients": true,
"restrictedServiceProviders": true,
"preferredConsumers": true,
"preferredClients": true,
"preferredServiceProviders": true
},
"requireVerifiedTimeDocumentation": false,
"reimbursableExpenses": [
{
"id": 1,
"label": "Expense 1"
}
],
"providerExpenses": [
{
"entityId": "ASG-SA2IVL",
"providerId": "SPR-H6OUI3",
"expenses": [
{
"id": 42,
"name": "Parking",
"amount": 12.5,
"expense": 12.5,
"quantity": 1,
"billTo": "organization",
"document": "string",
"isDefault": true,
"reimbursement_basic": "per_unit",
"expenseType": "travel",
"rate": 0,
"sourceReimbursableExpense": {
"id": 1,
"label": "Example"
}
}
]
}
],
"invoiceStatus": {
"id": "pending"
},
"payStatus": {
"id": "pending"
},
"estimatedCost": {},
"isDuplicated": false,
"duplicateId": "SFT-K2L9QX",
"customFields": {},
"externalCustomFields": {},
"documents": [
{
"file": "string",
"fileName": "intake-form.pdf"
}
],
"cancellationDetails": {
"cancellationReason": "Client requested cancellation",
"cancellationCausedBy": "client",
"cancellationCausedByClient": {
"id": 1,
"label": "Example"
},
"cancellationCausedByProvider": {
"id": 1,
"label": "Example"
},
"billableForCancellation": true,
"billCancellationClient": true,
"payCancellationProvider": false
}
}Example request
curl -X POST "https://api.fetchfido.ai/v1/shifts" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"title":"Weekend overnight coverage","description":"description of the shift","isPublished":true,"duration":1.5,"allowPointOfContact":"client_poc","requestorName":"John Doe","requestorEmail":"user@example.com","requestorPhone":"1234567890","requestorCountryCode":"+1","requestorPhoneType":"sms_and_voice","requestorPhoneExtension":"123","assignTo":"client","billTo":"clients","client":{"id":"CLT-KBX0Q6","label":"Client Name"},"assignClients":[{"id":"CLT-KBX0Q6","label":"Client Name"}],"assignClient":[{"id":"CLT-KBX0Q6"}],"assignClientLocation":[{"id":"1"}],"billingDistribution":"split_evenly","clientAllocations":[{"clientId":"CLT-KBX0Q6","serviceCharges":125.5}],"billingOption":"primary","location":{"locationType":"onsite","billingLocationSource":"client","billingOrganizationLocationId":"1","billingClientLocationId":"1","billingOption":"primary","onsite":{"onSiteType":"client","organizationLocationId":{"id":"1"},"clientLocationId":{"id":"1"},"manualLocation":{"addressLine1":"123 Main St","city":"Springfield","state":{"id":1},"postalCode":"12345"},"manualLocationContact":{"contactName":"Jane Roe","contactEmail":"jane@example.test","contactPhone":"1234567890","contactCountryCode":"+1","contactPhoneExtension":"123","videoPhone":"1234567890","videoPhoneCountryCode":"+1"},"onDemandLocationType":"organization","onDemandLink":"https://meet.example.test/room","onDemandAccessInstructions":"Dial in 5 minutes early","onDemandOrganizationLocationId":{"id":"1"},"onDemandClientLocationId":{"id":"1"},"onDemandManualLocation":{"addressLine1":"123 Main St","city":"Springfield","state":{"id":1},"postalCode":"12345"},"serviceTypes":[{"id":1}],"serviceTypeBreakdown":[{"serviceTypeId":1,"totalProviders":2,"providerTypeBreakdown":[null]}]},"remote":{"remoteType":"scheduled","meetingPlatform":"zoom","meetingLink":"https://zoom.us/j/123","meetingPhone":"1234567890","meetingCountryCode":"+1","meetingExtension":"123","accessInstruction":"Dial in 5 minutes early","onDemandLink":"https://meet.example.test/room","onDemandAccessInstructions":"Dial in 5 minutes early","serviceTypes":[{"id":1}],"serviceTypeBreakdown":[{}]}},"timezone":"America/New_York","scheduleType":"recurring","oneTime":{"dateTimeSlots":[{"startDate":"2024-01-01","endDate":"2024-01-04","timeSlots":[{"startTime":"10:00","endTime":"12:00"}],"scheduleFrequency":"daily","scheduleInterval":2,"scheduleDays":["monday"],"recurrenceOption":"on_date"}]},"multiDay":{"dateTimeSlots":[{"startDate":"2024-01-01","endDate":"2024-01-04","timeSlots":[{"startTime":"10:00","endTime":"12:00"}],"scheduleFrequency":"daily","scheduleInterval":2,"scheduleDays":["monday"],"recurrenceOption":"on_date"}]},"recurring":{"dateTimeSlots":[{"startDate":"2024-01-01","endDate":"2024-01-04","timeSlots":[{"startTime":"10:00","endTime":"12:00"}],"scheduleFrequency":"daily","scheduleInterval":2,"scheduleDays":["monday"],"recurrenceOption":"on_date"}]},"priority":{"id":1,"label":"Priority Label"},"status":{"id":1,"label":"Status Label"},"rateType":{"id":1,"label":"Rate Type Label"},"shiftBlock":{"id":1},"broadcast":{"id":"on","label":"On"},"broadcastNotify":true,"broadcastAudience":[{"id":"SPR-H6OUI3"}],"enableBroadcastBestMatch":true,"assignmentMethod":"direct","assignProviders":[{"id":"SPR-H6OUI3","serviceType":1,"locationType":"onsite","serviceProviderType":2,"partialReason":"string","notAvailableReason":"string","visibilityReason":"client_selected"}],"userRestricted":[{"id":"SPR-H6OUI3","label":"User 1"}],"userPreferred":[{"id":"SPR-DQRNUV","label":"User 1"}],"requirementAndPreferences":[{"serviceType":1,"serviceProviderCertifications":[{"serviceProviderType":1}]}],"notesToServiceProvider":"Reason for preference if any","internalNotes":"Internal notes about the shift","externalNotes":"Notes visible to the client","allowPartialCoverage":true,"partialDuration":[{"startDate":"2024-01-01","endDate":"2024-01-01","startTime":"09:00","endTime":"10:00"}],"overrideSingleRate":true,"overrideBufferTime":true,"overrideClientPreference":true,"clientPreferences":{"clearance":true,"skill":true,"certifications":true,"specialization":true,"gender":true,"restrictedServiceProvider":true,"restrictedConsumers":true,"preferredServiceProvider":true},"overrideServiceProviderPreference":true,"serviceProviderPreferences":{"overrideBufferTime":true,"onSite":true,"remote":true,"assignmentLimits":true,"availability":true,"locationDistance":true,"restrictedConsumers":true,"restrictedClients":true,"restrictedServiceProviders":true,"preferredConsumers":true,"preferredClients":true,"preferredServiceProviders":true},"requireVerifiedTimeDocumentation":false,"reimbursableExpenses":[{"id":1,"label":"Expense 1"}],"providerExpenses":[{"entityId":"ASG-SA2IVL","providerId":"SPR-H6OUI3","expenses":[{"id":42,"name":"Parking","amount":12.5,"expense":12.5,"quantity":1,"billTo":"organization","document":"string","isDefault":true,"reimbursement_basic":"per_unit","expenseType":"travel","rate":0,"sourceReimbursableExpense":{"id":1,"label":"Example"}}]}],"invoiceStatus":{"id":"pending"},"payStatus":{"id":"pending"},"estimatedCost":{},"isDuplicated":false,"duplicateId":"SFT-K2L9QX","customFields":{},"externalCustomFields":{},"documents":[{"file":"string","fileName":"intake-form.pdf"}],"cancellationDetails":{"cancellationReason":"Client requested cancellation","cancellationCausedBy":"client","cancellationCausedByClient":{"id":1,"label":"Example"},"cancellationCausedByProvider":{"id":1,"label":"Example"},"billableForCancellation":true,"billCancellationClient":true,"payCancellationProvider":false}}'Try it
Responses
201 Shift created successfully
Shift created successfully
{
"success": true,
"message": "Shift created successfully",
"data": {
"id": "SFT-MNP4PJ",
"skippedProviders": [
{
"id": "SPR-ABC123",
"locationType": "onsite",
"serviceType": 1,
"serviceProviderType": 2,
"reason": "slot_full_or_type_not_on_record"
}
]
}
}Response fields (10)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | string | The new shift's id — shifts are prefixed SFT-, not ASG-. Example |
data.skippedProviders | array of object | Only present when a requested provider could not be attached (location or service type not on the record, no provider type, slot full). The record is still created. |
data.skippedProviders[].id | string | Example |
data.skippedProviders[].locationType | string | Example |
data.skippedProviders[].serviceType | integer | Example |
data.skippedProviders[].serviceProviderType | integer or null | Example |
data.skippedProviders[].reason | string | Example |
401 Not signed in
Missing, invalid or expired API key.
{
"success": false,
"message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
"errors": null,
"code": "API_KEY_MISSING"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
403 Not allowed
Scope, tenant, IP allow-list or RBAC check failed.
{
"success": false,
"message": "You don't have permission to access this endpoint. This API key is missing the 'shifts:write' scope.",
"errors": null,
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Always empty on this status. Example |
429 Too many requests
Rate limit exceeded. See Retry-After.
{
"success": false,
"message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
"errors": null,
"code": "RATE_LIMITED"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
500 Server error
Unexpected error
{
"success": false,
"errors": "Shift creation failed",
"message": "An unexpected error occurred — please try again."
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
errors | string or null | Null in production. The exception message only when the application runs with debug on. Example |
message | string | Example |