API reference › Assignments

Create a new assignment

POST /v1/assignments

Scope
assignments:write
Roles
admin, scheduler

Parameters

None of its own.

Every call also sends Authorization and X-Tenant-ID; see Getting started.

Request body required

68 top-level fields; 31 hold nested fields, listed below.

FieldTypeDescription
titlestring or null

Example Special interpreter — intake appointment.

descriptionstring or null

Example description of the assignment.

isPublishedboolean

Publish immediately vs. save as a draft. Several other fields become required only when this is true.

Example true.

quickAssignmentboolean

The one-screen quick-create flow. Relaxes most other requirements in favor of quickServiceTypes/quickServiceProviderTypes and a same-day slot.

Example false.

allowPointOfContactstring

client_poc auto-fills requestor* from the client's primary location contact; the other values leave requestor* as sent.

One of: client_poc, external_contact, consumer, organization_poc. Example client_poc.

requestorNamestring or null

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.

requestorConsumerobject or null (1 nested)

The consumer the requestor is, when they are one of the assignment's own consumers rather than an outside party.

assignTo requiredstring

One of: client, organization. Example client.

billTostring or null

One of: organization, clients. Example clients.

clientobject or null (2 nested)

Required when assignTo=client and newClient is not sent.

newClientobject or null (14 nested)

Creates a new client inline instead of using an existing one — alternative to client.

consumerarray of object or null (2 nested)

Consumers on the assignment. A single object is also accepted and treated as a one-item list.

newConsumerobject or null (11 nested)

Creates a new consumer inline instead of using an existing one.

locationobject (64 nested)

Required (locationType) when isPublished=true. onsite/remote are read by locationType: onsite, remote, or both for hybrid.

billingOrganizationLocationIdstring or null

Example 1.

billingClientLocationIdstring or null

Example 1.

billingOptionstring or null

Example primary.

timezonestring

Example America/New_York.

scheduleType requiredstring

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)
statusobject or null (2 nested)
requestStatusobject or null (2 nested)
rateTypeobject or null (2 nested)
broadcastobject or null (2 nested)
broadcastNotifyboolean or null

Mutually exclusive with broadcastAudience; send only one.

Example true.

broadcastAudiencearray of object or null (1 nested)
userRestrictedarray of object or null (2 nested)
userPreferredarray of object or null (2 nested)
notesToServiceProviderstring or null

Example Reason for preference if any.

internalNotesstring or null

Example Internal notes about the assignment.

externalNotesstring or null

Example Notes visible to the client/consumer.

allowPartialCoverageboolean

Example true.

partialDurationarray of object or null (4 nested)

Partial coverage windows (required when allowPartialCoverage is true)

assignmentMethodstring or null

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

enableBroadcastBestMatchboolean

When true, a direct assignmentMethod no longer requires assignProviders — the best-match broadcast picks providers instead.

Example true.

assignProvidersarray of object or null (7 nested)

Required when assignmentMethod=direct and enableBroadcastBestMatch is false.

overrideSingleRateboolean

Example true.

overrideBufferTimeboolean

Example true.

overrideClientPreferenceboolean

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.

overrideConsumerPreferencesboolean

Example true.

consumerPreferencesobject (8 nested)

The same override flags for the consumer's stored requirements and preferences. Stored as sent.

overrideServiceProviderPreferenceboolean

Example true.

serviceProviderPreferencesobject (12 nested)

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

requireVerifiedTimeDocumentationboolean

Providers must sign in/out with a verified time record — see assignment-shift/provider/check-in.

Example false.

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

Provider expenses attached at creation.

invoiceStatusobject or null (1 nested)
payStatusobject or null (1 nested)
quickServiceTypesarray of object or null (1 nested)

Required when quickAssignment is true.

quickServiceProviderTypesarray of object or null (1 nested)

Required when quickAssignment is true.

estimatedCostobject or null

Client-calculated rate preview, saved as the assignment's estimated cost.

cancellationDetailsobject (7 nested)

Why and at whose cost a work item was canceled. Required (cancellationReason, cancellationCausedBy) when the status moves to a Canceled status. Stored as a blob and returned in the same shape.

durationnumber or null

Hours.

Example 1.5.

requirementAndPreferencesarray of object or null (22 nested)

Ignored when quickAssignment is true; the quick flow builds the rows from quickServiceTypes and quickServiceProviderTypes.

isDuplicatedboolean or null

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

Example false.

duplicateIdstring or null

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

Example ASG-SA2IVL.

customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

Custom field values submitted from a public embed form, keyed by field id.

documentsarray of object or null (3 nested)

Nested fields

requestorConsumer 1 fields
FieldTypeDescription
requestorConsumer.idstring

Example CSM-SQEWP0T.

client 2 fields
FieldTypeDescription
client.idstring

Example CLT-KBX0Q6.

client.labelstring

Example Client Name.

newClient 14 fields
FieldTypeDescription
newClient.namestring

Example Acme Corp.

newClient.emailstring (email)

Example contact@acme.test.

newClient.contactNamestring

Example Jane Roe.

newClient.contactPhonestring or null

Example 1234567890.

newClient.contactPhoneCountryCodestring or null

Example +1.

newClient.contactPhoneTypestring or null

Example sms_and_voice.

newClient.videoPhonestring or null

Example 1234567890.

newClient.videoPhoneCountryCodestring or null

Example +1.

newClient.phoneExtensionstring or null

Example 123.

newClient.addressLine1string

Example 123 Main St.

newClient.citystring

Example Springfield.

newClient.stateobject
newClient.state.idinteger

Example 1.

newClient.postalCodestring

Example 12345.

consumer 2 fields
FieldTypeDescription
consumer[].idstring

Example CSM-SQEWP0T.

consumer[].labelstring

Example Consumer Name.

newConsumer 11 fields
FieldTypeDescription
newConsumer.namestring

Example Pat Doe.

newConsumer.emailstring (email) or null

Example pat@example.test.

newConsumer.phonestring or null

Example 1234567890.

newConsumer.countryCodestring or null

Example +1.

newConsumer.phoneExtensionstring or null

Example 123.

newConsumer.hearingStatusobject
newConsumer.hearingStatus.idinteger

Example 1.

newConsumer.communicationModesarray of object
newConsumer.communicationModes[].idinteger

Example 1.

newConsumer.preferredServiceLocationsobject or null
newConsumer.preferredServiceLocations.idinteger

Example 1.

location 64 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

Also accepted at the top level as billingOrganizationLocationId; the top-level value wins if both are sent.

Example 1.

location.billingClientLocationIdstring or null

Also accepted at the top level as billingClientLocationId; the top-level value wins if both are sent.

Example 1.

location.billingOptionstring or null

Defaults to primary. Also accepted at the top level as billingOption; the nested value wins if both are sent.

Example primary.

location.onsiteobject or null
location.onsite.onSiteTypestring

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

location.onsite.organizationLocationIdobject or null

Required when onSiteType=organization.

location.onsite.organizationLocationId.idstring

Example 1.

location.onsite.clientLocationIdobject or null

Required when onSiteType=client and newClient is not sent.

location.onsite.clientLocationId.idstring

Example 1.

location.onsite.manualLocationobject or null

Required when onSiteType=manual.

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

Required when onSiteType=manual.

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

Required when onSiteType=ondemand.

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

Required when onDemandLocationType=organization.

location.onsite.onDemandOrganizationLocationId.idstring

Example 1.

location.onsite.onDemandClientLocationIdobject or null

Required when onDemandLocationType=client.

location.onsite.onDemandClientLocationId.idstring

Example 1.

location.onsite.onDemandManualLocationobject or null

Required when onDemandLocationType=manual.

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.onDemandManualLocationContactobject or null
location.onsite.onDemandManualLocationContact.contactNamestring or null

Example Jane Roe.

location.onsite.onDemandManualLocationContact.contactEmailstring (email) or null

Example jane@example.test.

location.onsite.onDemandManualLocationContact.contactPhonestring or null

Example 1234567890.

location.onsite.onDemandManualLocationContact.contactCountryCodestring or null

Example +1.

location.onsite.serviceTypesarray of object

Required unless serviceTypeBreakdown is sent instead.

location.onsite.serviceTypes[].idinteger

Example 1.

location.onsite.serviceTypeBreakdownarray of object

Per-service-type provider counts — alternative to serviceTypes when provider types are being split per service type.

location.onsite.serviceTypeBreakdown[].serviceTypeIdinteger

Example 1.

location.onsite.serviceTypeBreakdown[].totalProvidersinteger

Example 2.

location.onsite.serviceTypeBreakdown[].providerTypeBreakdownarray of object
location.onsite.serviceProviderTypearray of object or null
location.onsite.serviceProviderType[].idinteger

Example 1.

location.remoteobject or null
location.remote.remoteTypestring

One of: ondemand, scheduled. Example scheduled.

location.remote.meetingPlatformstring or null

Required when remoteType is not ondemand.

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
location.remote.serviceProviderTypearray of object or null
location.remote.serviceProviderType[].idinteger

Example 1.

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

Example 1.

status.labelstring

Example Status Label.

requestStatus 2 fields
FieldTypeDescription
requestStatus.idinteger

Example 1.

requestStatus.labelstring

Example Request Status Label.

rateType 2 fields
FieldTypeDescription
rateType.idinteger

Example 1.

rateType.labelstring

Example Rate Type Label.

broadcast 2 fields
FieldTypeDescription
broadcast.idstring

Example on.

broadcast.labelstring

Example On.

broadcastAudience 1 fields
FieldTypeDescription
broadcastAudience[].idstring

Example SPR-H6OUI3.

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.

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.

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.

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
consumerPreferences 8 fields
FieldTypeDescription
consumerPreferences.clearanceboolean or null
consumerPreferences.skillboolean or null
consumerPreferences.certificationsboolean or null
consumerPreferences.specializationboolean or null
consumerPreferences.genderboolean or null
consumerPreferences.restrictedServiceProviderboolean or null
consumerPreferences.restrictedClientsboolean or null
consumerPreferences.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.

quickServiceTypes 1 fields
FieldTypeDescription
quickServiceTypes[].idinteger

Example 1.

quickServiceProviderTypes 1 fields
FieldTypeDescription
quickServiceProviderTypes[].idinteger

Example 1.

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.

requirementAndPreferences 22 fields
FieldTypeDescription
requirementAndPreferences[].serviceTypeobject
requirementAndPreferences[].serviceType.idinteger or string

Example 1.

requirementAndPreferences[].serviceType.labelstring or null

Example Example.

requirementAndPreferences[].serviceProviderCertificationsarray of object

Provider type, optionally with a certification it must hold. Pairs that do not belong to the service type are skipped.

requirementAndPreferences[].serviceProviderCertifications[].serviceProviderTypeobject
requirementAndPreferences[].serviceProviderCertifications[].serviceProviderType.idinteger or string

Example 1.

requirementAndPreferences[].serviceProviderCertifications[].serviceProviderType.labelstring or null

Example Example.

requirementAndPreferences[].serviceProviderCertifications[].certificationsobject
requirementAndPreferences[].serviceProviderCertifications[].certifications.idinteger or string

Example 1.

requirementAndPreferences[].serviceProviderCertifications[].certifications.labelstring or null

Example Example.

requirementAndPreferences[].skillLevelobject
requirementAndPreferences[].skillLevel.idinteger or string

Example 1.

requirementAndPreferences[].skillLevel.labelstring or null

Example Example.

requirementAndPreferences[].clearancesarray of object
requirementAndPreferences[].clearances[].idinteger or string

Example 1.

requirementAndPreferences[].clearances[].labelstring or null

Example Example.

requirementAndPreferences[].specializationsarray of object
requirementAndPreferences[].specializations[].idinteger or string

Example 1.

requirementAndPreferences[].specializations[].labelstring or null

Example Example.

requirementAndPreferences[].genderPreferenceobject
requirementAndPreferences[].genderPreference.idinteger or string

Example 1.

requirementAndPreferences[].genderPreference.labelstring or null

Example Example.

documents 3 fields
FieldTypeDescription
documents[].idinteger or null

Existing document id — omit file when updating an existing document's metadata only.

documents[].filestring (binary)

Required unless id is sent.

documents[].fileNamestring

Example intake-form.pdf.

Example

JSON
{
  "title": "Special interpreter — intake appointment",
  "description": "description of the assignment",
  "isPublished": true,
  "quickAssignment": false,
  "allowPointOfContact": "client_poc",
  "requestorName": "John Doe",
  "requestorEmail": "user@example.com",
  "requestorPhone": "1234567890",
  "requestorCountryCode": "+1",
  "requestorPhoneType": "sms_and_voice",
  "requestorPhoneExtension": "123",
  "requestorConsumer": {
    "id": "CSM-SQEWP0T"
  },
  "assignTo": "client",
  "billTo": "clients",
  "client": {
    "id": "CLT-KBX0Q6",
    "label": "Client Name"
  },
  "newClient": {
    "name": "Acme Corp",
    "email": "contact@acme.test",
    "contactName": "Jane Roe",
    "contactPhone": "1234567890",
    "contactPhoneCountryCode": "+1",
    "contactPhoneType": "sms_and_voice",
    "videoPhone": "1234567890",
    "videoPhoneCountryCode": "+1",
    "phoneExtension": "123",
    "addressLine1": "123 Main St",
    "city": "Springfield",
    "state": {
      "id": 1
    },
    "postalCode": "12345"
  },
  "consumer": [
    {
      "id": "CSM-SQEWP0T",
      "label": "Consumer Name"
    }
  ],
  "newConsumer": {
    "name": "Pat Doe",
    "email": "pat@example.test",
    "phone": "1234567890",
    "countryCode": "+1",
    "phoneExtension": "123",
    "hearingStatus": {
      "id": 1
    },
    "communicationModes": [
      {
        "id": 1
      }
    ],
    "preferredServiceLocations": {
      "id": 1
    }
  },
  "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"
      },
      "onDemandManualLocationContact": {
        "contactName": "Jane Roe",
        "contactEmail": "jane@example.test",
        "contactPhone": "1234567890",
        "contactCountryCode": "+1"
      },
      "serviceTypes": [
        {
          "id": 1
        }
      ],
      "serviceTypeBreakdown": [
        {
          "serviceTypeId": 1,
          "totalProviders": 2,
          "providerTypeBreakdown": [
            null
          ]
        }
      ],
      "serviceProviderType": [
        {
          "id": 1
        }
      ]
    },
    "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": [
        {}
      ],
      "serviceProviderType": [
        {
          "id": 1
        }
      ]
    }
  },
  "billingOrganizationLocationId": "1",
  "billingClientLocationId": "1",
  "billingOption": "primary",
  "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"
  },
  "requestStatus": {
    "id": 1,
    "label": "Request Status Label"
  },
  "rateType": {
    "id": 1,
    "label": "Rate Type Label"
  },
  "broadcast": {
    "id": "on",
    "label": "On"
  },
  "broadcastNotify": true,
  "broadcastAudience": [
    {
      "id": "SPR-H6OUI3"
    }
  ],
  "userRestricted": [
    {
      "id": "SPR-H6OUI3",
      "label": "User 1"
    }
  ],
  "userPreferred": [
    {
      "id": "SPR-DQRNUV",
      "label": "User 1"
    }
  ],
  "notesToServiceProvider": "Reason for preference if any",
  "internalNotes": "Internal notes about the assignment",
  "externalNotes": "Notes visible to the client/consumer",
  "allowPartialCoverage": true,
  "partialDuration": [
    {
      "startDate": "2024-01-01",
      "endDate": "2024-01-01",
      "startTime": "09:00",
      "endTime": "10:00"
    }
  ],
  "assignmentMethod": "direct",
  "enableBroadcastBestMatch": true,
  "assignProviders": [
    {
      "id": "SPR-H6OUI3",
      "serviceType": 1,
      "locationType": "onsite",
      "serviceProviderType": 2,
      "partialReason": "string",
      "notAvailableReason": "string",
      "visibilityReason": "client_selected"
    }
  ],
  "overrideSingleRate": true,
  "overrideBufferTime": true,
  "overrideClientPreference": true,
  "clientPreferences": {
    "clearance": true,
    "skill": true,
    "certifications": true,
    "specialization": true,
    "gender": true,
    "restrictedServiceProvider": true,
    "restrictedConsumers": true,
    "preferredServiceProvider": true
  },
  "overrideConsumerPreferences": true,
  "consumerPreferences": {
    "clearance": true,
    "skill": true,
    "certifications": true,
    "specialization": true,
    "gender": true,
    "restrictedServiceProvider": true,
    "restrictedClients": 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"
  },
  "quickServiceTypes": [
    {
      "id": 1
    }
  ],
  "quickServiceProviderTypes": [
    {
      "id": 1
    }
  ],
  "estimatedCost": {},
  "cancellationDetails": {
    "cancellationReason": "Client requested cancellation",
    "cancellationCausedBy": "client",
    "cancellationCausedByClient": {
      "id": 1,
      "label": "Example"
    },
    "cancellationCausedByProvider": {
      "id": 1,
      "label": "Example"
    },
    "billableForCancellation": true,
    "billCancellationClient": true,
    "payCancellationProvider": false
  },
  "duration": 1.5,
  "requirementAndPreferences": [
    {
      "serviceType": {
        "id": 1,
        "label": "Example"
      },
      "serviceProviderCertifications": [
        {
          "serviceProviderType": {
            "id": 1,
            "label": "Example"
          },
          "certifications": {
            "id": 1,
            "label": "Example"
          }
        }
      ],
      "skillLevel": {
        "id": 1,
        "label": "Example"
      },
      "clearances": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "specializations": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "genderPreference": {
        "id": 1,
        "label": "Example"
      }
    }
  ],
  "isDuplicated": false,
  "duplicateId": "ASG-SA2IVL",
  "customFields": {},
  "externalCustomFields": {},
  "documents": [
    {
      "id": 0,
      "file": "string",
      "fileName": "intake-form.pdf"
    }
  ]
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/assignments" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"title":"Special interpreter — intake appointment","description":"description of the assignment","isPublished":true,"quickAssignment":false,"allowPointOfContact":"client_poc","requestorName":"John Doe","requestorEmail":"user@example.com","requestorPhone":"1234567890","requestorCountryCode":"+1","requestorPhoneType":"sms_and_voice","requestorPhoneExtension":"123","requestorConsumer":{"id":"CSM-SQEWP0T"},"assignTo":"client","billTo":"clients","client":{"id":"CLT-KBX0Q6","label":"Client Name"},"newClient":{"name":"Acme Corp","email":"contact@acme.test","contactName":"Jane Roe","contactPhone":"1234567890","contactPhoneCountryCode":"+1","contactPhoneType":"sms_and_voice","videoPhone":"1234567890","videoPhoneCountryCode":"+1","phoneExtension":"123","addressLine1":"123 Main St","city":"Springfield","state":{"id":1},"postalCode":"12345"},"consumer":[{"id":"CSM-SQEWP0T","label":"Consumer Name"}],"newConsumer":{"name":"Pat Doe","email":"pat@example.test","phone":"1234567890","countryCode":"+1","phoneExtension":"123","hearingStatus":{"id":1},"communicationModes":[{"id":1}],"preferredServiceLocations":{"id":1}},"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"},"onDemandManualLocationContact":{"contactName":"Jane Roe","contactEmail":"jane@example.test","contactPhone":"1234567890","contactCountryCode":"+1"},"serviceTypes":[{"id":1}],"serviceTypeBreakdown":[{"serviceTypeId":1,"totalProviders":2,"providerTypeBreakdown":[null]}],"serviceProviderType":[{"id":1}]},"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":[{}],"serviceProviderType":[{"id":1}]}},"billingOrganizationLocationId":"1","billingClientLocationId":"1","billingOption":"primary","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"},"requestStatus":{"id":1,"label":"Request Status Label"},"rateType":{"id":1,"label":"Rate Type Label"},"broadcast":{"id":"on","label":"On"},"broadcastNotify":true,"broadcastAudience":[{"id":"SPR-H6OUI3"}],"userRestricted":[{"id":"SPR-H6OUI3","label":"User 1"}],"userPreferred":[{"id":"SPR-DQRNUV","label":"User 1"}],"notesToServiceProvider":"Reason for preference if any","internalNotes":"Internal notes about the assignment","externalNotes":"Notes visible to the client/consumer","allowPartialCoverage":true,"partialDuration":[{"startDate":"2024-01-01","endDate":"2024-01-01","startTime":"09:00","endTime":"10:00"}],"assignmentMethod":"direct","enableBroadcastBestMatch":true,"assignProviders":[{"id":"SPR-H6OUI3","serviceType":1,"locationType":"onsite","serviceProviderType":2,"partialReason":"string","notAvailableReason":"string","visibilityReason":"client_selected"}],"overrideSingleRate":true,"overrideBufferTime":true,"overrideClientPreference":true,"clientPreferences":{"clearance":true,"skill":true,"certifications":true,"specialization":true,"gender":true,"restrictedServiceProvider":true,"restrictedConsumers":true,"preferredServiceProvider":true},"overrideConsumerPreferences":true,"consumerPreferences":{"clearance":true,"skill":true,"certifications":true,"specialization":true,"gender":true,"restrictedServiceProvider":true,"restrictedClients":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"},"quickServiceTypes":[{"id":1}],"quickServiceProviderTypes":[{"id":1}],"estimatedCost":{},"cancellationDetails":{"cancellationReason":"Client requested cancellation","cancellationCausedBy":"client","cancellationCausedByClient":{"id":1,"label":"Example"},"cancellationCausedByProvider":{"id":1,"label":"Example"},"billableForCancellation":true,"billCancellationClient":true,"payCancellationProvider":false},"duration":1.5,"requirementAndPreferences":[{"serviceType":{"id":1,"label":"Example"},"serviceProviderCertifications":[{"serviceProviderType":{"id":1,"label":"Example"},"certifications":{"id":1,"label":"Example"}}],"skillLevel":{"id":1,"label":"Example"},"clearances":[{"id":1,"label":"Example"}],"specializations":[{"id":1,"label":"Example"}],"genderPreference":{"id":1,"label":"Example"}}],"isDuplicated":false,"duplicateId":"ASG-SA2IVL","customFields":{},"externalCustomFields":{},"documents":[{"id":0,"file":"string","fileName":"intake-form.pdf"}]}'

Try it

Responses

201 Assignment created successfully

Assignment created successfully

JSON
{
  "success": true,
  "message": "Assignment created successfully",
  "data": {
    "id": "ASG-001",
    "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 Assignment created successfully.

dataobject
data.idstring

Example ASG-001.

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 'assignments: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 'assignments: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": "Assignment 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 Assignment creation failed.

messagestring

Example An unexpected error occurred — please try again..