API reference › Shifts

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.

FieldTypeDescription
titlestring or null

Example Weekend overnight coverage.

descriptionstring or null

Example description of the shift.

isPublishedboolean or null

false saves a draft and relaxes nearly every other requirement; true publishes and triggers status auto-update plus the published notifications.

Example true.

durationnumber or null

Hours — used when setting location.onsite/remote slot capacity.

Example 1.5.

allowPointOfContactstring or null

Any non-empty value auto-fills requestorEmail/requestorPhone from the client's primary location contact, overwriting whatever was sent.

Example client_poc.

requestorNamestring or null

Not validated; stored with the shift and shown in the list and sidebar.

Example John Doe.

requestorEmailstring (email) or null

Example user@example.com.

requestorPhonestring or null

Example 1234567890.

requestorCountryCodestring or null

Example +1.

requestorPhoneTypestring or null

One of: sms_and_voice, voice_only. Example sms_and_voice.

requestorPhoneExtensionstring or null

Example 123.

assignTostring 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: client, organization. Example client.

billTostring or null

clients (with a non-empty assignClients) switches the shift to per-client billing.

One of: organization, clients. Example clients.

clientobject 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.

assignClientsarray 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.

assignClientarray of object or null (1 nested)

Legacy alias for assignClients — same shape, same effect.

assignClientLocationarray of object or null (1 nested)

Not validated. Sets the shift's client locations; assignments have no equivalent.

billingDistributionstring or null

How the shift's cost is divided across multiple clients. Only meaningful on a multi-client shift.

One of: split_evenly, manual_allocation, individual. Example split_evenly.

clientAllocationsarray 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.

billingOptionstring 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 primary.

locationobject or null (55 nested)

locationType is required when isPublished=true.

timezonestring or null

Required when isPublished=true. Defaults to the organization's timezone when omitted.

Example America/New_York.

scheduleTypestring or null

Selects which wrapper below the slots are read from; an unrecognized value is rejected.

One of: one_time, multi_day, recurring. Example recurring.

oneTimeobject or null (10 nested)

Read only when scheduleType=one_time.

multiDayobject or null (10 nested)

Read only when scheduleType=multi_day.

recurringobject or null (10 nested)

Read only when scheduleType=recurring.

priorityobject or null (2 nested)
status requiredobject (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.

rateTypeobject or null (2 nested)
shiftBlock requiredobject (1 nested)

Required — a shift is always created inside a shift block, which an assignment has no equivalent of.

broadcastobject or null (2 nested)

Required when isPublished=true.

broadcastNotifyboolean or null

Example true.

broadcastAudiencearray of object or null (1 nested)
enableBroadcastBestMatchboolean or null

When true, assignProviders is no longer required for a published direct shift.

Example true.

assignmentMethodstring or null

Required when isPublished=true.

One of: direct, accept, interest. Example direct.

assignProvidersarray 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.

userRestrictedarray of object or null (2 nested)
userPreferredarray of object or null (2 nested)
requirementAndPreferencesarray of object or null (3 nested)

Not validated; saved as the shift's requirements and preferences.

notesToServiceProviderstring or null

Example Reason for preference if any.

internalNotesstring or null

Example Internal notes about the shift.

externalNotesstring or null

Example Notes visible to the client.

allowPartialCoverageboolean or null

Example true.

partialDurationarray of object or null (4 nested)

Partial coverage windows — required when allowPartialCoverage is true.

overrideSingleRateboolean or null

Example true.

overrideBufferTimeboolean or null

Example true.

overrideClientPreferenceboolean or null

Example true.

clientPreferencesobject (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.

overrideServiceProviderPreferenceboolean or null

Example true.

serviceProviderPreferencesobject (12 nested)

Provider-side rules the scheduler overrode on this work item. Stored as sent.

requireVerifiedTimeDocumentationboolean or null

Example false.

reimbursableExpensesarray of object or null (2 nested)
providerExpensesarray of object or null (17 nested)

Provider expenses.

invoiceStatusobject or null (1 nested)

Only stored when billing is enabled for shifts and the status is a completed one; otherwise cleared.

payStatusobject or null (1 nested)

Only stored when payables are enabled for shifts and the status is a completed one; otherwise cleared.

estimatedCostobject or null

Client-calculated rate preview.

isDuplicatedboolean or null

Set when this create duplicates an existing shift; records a duplication audit event instead of a plain create.

Example false.

duplicateIdstring or null

The shift being duplicated. Read only with isDuplicated=true.

Example SFT-K2L9QX.

customFieldsobject or null

Custom field values keyed by field id. File-typed values are attached once the shift exists.

externalCustomFieldsobject or null

Values for the external custom fields, keyed by field id.

documentsarray of object or null (2 nested)
cancellationDetailsobject (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
FieldTypeDescription
client.idstring

Example CLT-KBX0Q6.

client.labelstring

Example Client Name.

assignClients 2 fields
FieldTypeDescription
assignClients[].idstring

Example CLT-KBX0Q6.

assignClients[].labelstring

Example Client Name.

assignClient 1 fields
FieldTypeDescription
assignClient[].idstring

Example CLT-KBX0Q6.

assignClientLocation 1 fields
FieldTypeDescription
assignClientLocation[].idstring

Example 1.

clientAllocations 2 fields
FieldTypeDescription
clientAllocations[].clientIdstring

Example CLT-KBX0Q6.

clientAllocations[].serviceChargesnumber

Example 125.5.

location 55 fields
FieldTypeDescription
location.locationTypestring

One of: onsite, remote, hybrid. Example onsite.

location.billingLocationSourcestring or null

One of: organization, client. Example client.

location.billingOrganizationLocationIdstring or null

A {id} object is also accepted. Nested here only — there is no top-level fallback for this one.

Example 1.

location.billingClientLocationIdstring or null

A {id} object is also accepted. Nested here only — there is no top-level fallback for this one.

Example 1.

location.billingOptionstring or null

Wins over the top-level billingOption.

Example primary.

location.onsiteobject or null
location.onsite.onSiteTypestring

One of: organization, client, manual, ondemand. Example client.

location.onsite.organizationLocationIdobject or null
location.onsite.organizationLocationId.idstring

Example 1.

location.onsite.clientLocationIdobject or null
location.onsite.clientLocationId.idstring

Example 1.

location.onsite.manualLocationobject or null
location.onsite.manualLocation.addressLine1string

Example 123 Main St.

location.onsite.manualLocation.citystring

Example Springfield.

location.onsite.manualLocation.stateobject
location.onsite.manualLocation.postalCodestring

Example 12345.

location.onsite.manualLocationContactobject 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.contactNamestring

Example Jane Roe.

location.onsite.manualLocationContact.contactEmailstring (email)

Example jane@example.test.

location.onsite.manualLocationContact.contactPhonestring or null

Example 1234567890.

location.onsite.manualLocationContact.contactCountryCodestring or null

Example +1.

location.onsite.manualLocationContact.contactPhoneExtensionstring or null

Example 123.

location.onsite.manualLocationContact.videoPhonestring or null

Example 1234567890.

location.onsite.manualLocationContact.videoPhoneCountryCodestring or null

Example +1.

location.onsite.onDemandLocationTypestring or null

One of: organization, client, manual. Example organization.

location.onsite.onDemandLinkstring or null

Example https://meet.example.test/room.

location.onsite.onDemandAccessInstructionsstring or null

Example Dial in 5 minutes early.

location.onsite.onDemandOrganizationLocationIdobject or null
location.onsite.onDemandOrganizationLocationId.idstring

Example 1.

location.onsite.onDemandClientLocationIdobject or null
location.onsite.onDemandClientLocationId.idstring

Example 1.

location.onsite.onDemandManualLocationobject or null
location.onsite.onDemandManualLocation.addressLine1string

Example 123 Main St.

location.onsite.onDemandManualLocation.citystring

Example Springfield.

location.onsite.onDemandManualLocation.stateobject
location.onsite.onDemandManualLocation.postalCodestring

Example 12345.

location.onsite.serviceTypesarray of object
location.onsite.serviceTypes[].idinteger

Example 1.

location.onsite.serviceTypeBreakdownarray of object

The sum of providerTypeBreakdown.totalProviders must equal totalProviders.

location.onsite.serviceTypeBreakdown[].serviceTypeIdinteger

Example 1.

location.onsite.serviceTypeBreakdown[].totalProvidersinteger

Example 2.

location.onsite.serviceTypeBreakdown[].providerTypeBreakdownarray of object
location.remoteobject or null
location.remote.remoteTypestring

One of: ondemand, scheduled. Example scheduled.

location.remote.meetingPlatformstring or null

Example zoom.

location.remote.meetingLinkstring or null

Example https://zoom.us/j/123.

location.remote.meetingPhonestring or null

Example 1234567890.

location.remote.meetingCountryCodestring or null

Example +1.

location.remote.meetingExtensionstring or null

Example 123.

location.remote.accessInstructionstring or null

Example Dial in 5 minutes early.

location.remote.onDemandLinkstring or null

Example https://meet.example.test/room.

location.remote.onDemandAccessInstructionsstring or null

Example Dial in 5 minutes early.

location.remote.serviceTypesarray of object
location.remote.serviceTypes[].idinteger

Example 1.

location.remote.serviceTypeBreakdownarray of object
oneTime 10 fields
FieldTypeDescription
oneTime.dateTimeSlotsarray of object
oneTime.dateTimeSlots[].startDatestring (date)

Example 2024-01-01.

oneTime.dateTimeSlots[].endDatestring (date)

Example 2024-01-04.

oneTime.dateTimeSlots[].timeSlotsarray of object
oneTime.dateTimeSlots[].timeSlots[].startTimestring

Example 10:00.

oneTime.dateTimeSlots[].timeSlots[].endTimestring

Example 12:00.

oneTime.dateTimeSlots[].scheduleFrequencystring or null

One of: daily, weekly, monthly, yearly. Example daily.

oneTime.dateTimeSlots[].scheduleIntervalinteger or null

Example 2.

oneTime.dateTimeSlots[].scheduleDaysarray of string or null

Days of week this slot recurs on, when scheduleFrequency=weekly.

oneTime.dateTimeSlots[].recurrenceOptionstring or null

How the recurrence ends — e.g. an end date or an occurrence count.

Example on_date.

multiDay 10 fields
FieldTypeDescription
multiDay.dateTimeSlotsarray of object
multiDay.dateTimeSlots[].startDatestring (date)

Example 2024-01-01.

multiDay.dateTimeSlots[].endDatestring (date)

Example 2024-01-04.

multiDay.dateTimeSlots[].timeSlotsarray of object
multiDay.dateTimeSlots[].timeSlots[].startTimestring

Example 10:00.

multiDay.dateTimeSlots[].timeSlots[].endTimestring

Example 12:00.

multiDay.dateTimeSlots[].scheduleFrequencystring or null

One of: daily, weekly, monthly, yearly. Example daily.

multiDay.dateTimeSlots[].scheduleIntervalinteger or null

Example 2.

multiDay.dateTimeSlots[].scheduleDaysarray of string or null

Days of week this slot recurs on, when scheduleFrequency=weekly.

multiDay.dateTimeSlots[].recurrenceOptionstring or null

How the recurrence ends — e.g. an end date or an occurrence count.

Example on_date.

recurring 10 fields
FieldTypeDescription
recurring.dateTimeSlotsarray of object
recurring.dateTimeSlots[].startDatestring (date)

Example 2024-01-01.

recurring.dateTimeSlots[].endDatestring (date)

Example 2024-01-04.

recurring.dateTimeSlots[].timeSlotsarray of object
recurring.dateTimeSlots[].timeSlots[].startTimestring

Example 10:00.

recurring.dateTimeSlots[].timeSlots[].endTimestring

Example 12:00.

recurring.dateTimeSlots[].scheduleFrequencystring or null

One of: daily, weekly, monthly, yearly. Example daily.

recurring.dateTimeSlots[].scheduleIntervalinteger or null

Example 2.

recurring.dateTimeSlots[].scheduleDaysarray of string or null

Days of week this slot recurs on, when scheduleFrequency=weekly.

recurring.dateTimeSlots[].recurrenceOptionstring or null

How the recurrence ends — e.g. an end date or an occurrence count.

Example on_date.

priority 2 fields
FieldTypeDescription
priority.idinteger

Example 1.

priority.labelstring

Example Priority Label.

status 2 fields
FieldTypeDescription
status.idinteger or null

Example 1.

status.labelstring or null

Example Status Label.

rateType 2 fields
FieldTypeDescription
rateType.idinteger

Example 1.

rateType.labelstring

Example Rate Type Label.

shiftBlock 1 fields
FieldTypeDescription
shiftBlock.idinteger

Example 1.

broadcast 2 fields
FieldTypeDescription
broadcast.idstring

Example on.

broadcast.labelstring

Example On.

broadcastAudience 1 fields
FieldTypeDescription
broadcastAudience[].idstring

Example SPR-H6OUI3.

assignProviders 7 fields
FieldTypeDescription
assignProviders[].idstring

Example SPR-H6OUI3.

assignProviders[].serviceTypeinteger

Example 1.

assignProviders[].locationTypestring

One of: onsite, remote. Example onsite.

assignProviders[].serviceProviderTypeinteger or null

Provider type the provider fills. Inferred when the service type has only one.

Example 2.

assignProviders[].partialReasonstring or null

Why a partly matching provider was assigned anyway.

assignProviders[].notAvailableReasonstring or null

Why an unavailable provider was assigned anyway.

assignProviders[].visibilityReasonstring or null

How the provider came to be listed. Defaults to partial_match_allowed when partialReason is sent, else full_match.

Example client_selected.

userRestricted 2 fields
FieldTypeDescription
userRestricted[].idstring

Example SPR-H6OUI3.

userRestricted[].labelstring

Example User 1.

userPreferred 2 fields
FieldTypeDescription
userPreferred[].idstring

Example SPR-DQRNUV.

userPreferred[].labelstring

Example User 1.

requirementAndPreferences 3 fields
FieldTypeDescription
requirementAndPreferences[].serviceTypeinteger

Example 1.

requirementAndPreferences[].serviceProviderCertificationsarray of object

Required when serviceType is set.

requirementAndPreferences[].serviceProviderCertifications[].serviceProviderTypeinteger

Example 1.

partialDuration 4 fields
FieldTypeDescription
partialDuration[].startDatestring (date)

Example 2024-01-01.

partialDuration[].endDatestring (date)

Example 2024-01-01.

partialDuration[].startTimestring

Example 09:00.

partialDuration[].endTimestring

Example 10:00.

clientPreferences 8 fields
FieldTypeDescription
clientPreferences.clearanceboolean or null
clientPreferences.skillboolean or null
clientPreferences.certificationsboolean or null
clientPreferences.specializationboolean or null
clientPreferences.genderboolean or null
clientPreferences.restrictedServiceProviderboolean or null
clientPreferences.restrictedConsumersboolean or null
clientPreferences.preferredServiceProviderboolean or null
serviceProviderPreferences 12 fields
FieldTypeDescription
serviceProviderPreferences.overrideBufferTimeboolean or null
serviceProviderPreferences.onSiteboolean or null
serviceProviderPreferences.remoteboolean or null
serviceProviderPreferences.assignmentLimitsboolean or null
serviceProviderPreferences.availabilityboolean or null
serviceProviderPreferences.locationDistanceboolean or null
serviceProviderPreferences.restrictedConsumersboolean or null
serviceProviderPreferences.restrictedClientsboolean or null
serviceProviderPreferences.restrictedServiceProvidersboolean or null
serviceProviderPreferences.preferredConsumersboolean or null
serviceProviderPreferences.preferredClientsboolean or null
serviceProviderPreferences.preferredServiceProvidersboolean or null
reimbursableExpenses 2 fields
FieldTypeDescription
reimbursableExpenses[].idinteger

Example 1.

reimbursableExpenses[].labelstring

Example Expense 1.

providerExpenses 17 fields
FieldTypeDescription
providerExpenses[].entityIdstring or null

Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved.

Example ASG-SA2IVL.

providerExpenses[].providerId requiredstring

Example SPR-H6OUI3.

providerExpenses[].expensesarray of object
providerExpenses[].expenses[].idinteger or null

Existing expense id to update; omit to create.

Example 42.

providerExpenses[].expenses[].name requiredstring

Example Parking.

providerExpenses[].expenses[].amountnumber or null

min 0.01. Example 12.5.

providerExpenses[].expenses[].expensenumber or null

Unit amount, multiplied by quantity.

min 0.01. Example 12.5.

providerExpenses[].expenses[].quantitynumber or null

min 0.01. Example 1.

providerExpenses[].expenses[].billTostring or null

One of: organization, client. Example organization.

providerExpenses[].expenses[].documentstring (binary) or null

Receipt: pdf, jpg, jpeg or png, max 2 MB.

providerExpenses[].expenses[].isDefaultboolean or null
providerExpenses[].expenses[].reimbursement_basicstring or null

Reimbursement basis of a freeform custom expense.

One of: per_unit, per_day, flat_amount, percentage.

providerExpenses[].expenses[].expenseTypestring or null

One of: travel, lodging, meals, supplies, miscellaneous.

providerExpenses[].expenses[].ratenumber or null

Required when reimbursement_basic is percentage.

min 0.

providerExpenses[].expenses[].sourceReimbursableExpenseobject

Catalog category a custom line is seeded from.

providerExpenses[].expenses[].sourceReimbursableExpense.idinteger or string

Example 1.

providerExpenses[].expenses[].sourceReimbursableExpense.labelstring or null

Example Example.

invoiceStatus 1 fields
FieldTypeDescription
invoiceStatus.idstring

Example pending.

payStatus 1 fields
FieldTypeDescription
payStatus.idstring

Example pending.

documents 2 fields
FieldTypeDescription
documents[].filestring (binary)
documents[].fileNamestring

Example intake-form.pdf.

cancellationDetails 7 fields
FieldTypeDescription
cancellationDetails.cancellationReasonstring

Example Client requested cancellation.

cancellationDetails.cancellationCausedBystring or object

Who caused the cancellation, as a label or a {id, label} object.

cancellationDetails.cancellationCausedByClientobject or array of object

The client or clients responsible, when the cause is a client: one {id, label} or a list.

cancellationDetails.cancellationCausedByProviderobject or array of object

The provider or providers responsible, when the cause is a provider: one {id, label} or a list.

cancellationDetails.billableForCancellationboolean

Example true.

cancellationDetails.billCancellationClientboolean

When billableForCancellation is true, at least one of billCancellationClient/payCancellationProvider must also be true.

Example true.

cancellationDetails.payCancellationProviderboolean

Example false.

Example

JSON
{
  "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

Shell
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

JSON
{
  "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)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Shift created successfully.

dataobject
data.idstring

The new shift's id — shifts are prefixed SFT-, not ASG-.

Example SFT-MNP4PJ.

data.skippedProvidersarray 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[].idstring

Example SPR-ABC123.

data.skippedProviders[].locationTypestring

Example onsite.

data.skippedProviders[].serviceTypeinteger

Example 1.

data.skippedProviders[].serviceProviderTypeinteger or null

Example 2.

data.skippedProviders[].reasonstring

Example slot_full_or_type_not_on_record.

401 Not signed in

Missing, invalid or expired API key.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED. Example API_KEY_MISSING.

403 Not allowed

Scope, tenant, IP allow-list or RBAC check failed.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You don't have permission to access this endpoint. This API key is missing the 'shifts:write' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

429 Too many requests

Rate limit exceeded. See Retry-After.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: RATE_LIMITED. Example RATE_LIMITED.

500 Server error

Unexpected error

JSON
{
  "success": false,
  "errors": "Shift creation failed",
  "message": "An unexpected error occurred — please try again."
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

errorsstring or null

Null in production. The exception message only when the application runs with debug on.

Example Shift creation failed.

messagestring

Example An unexpected error occurred — please try again..