API reference › Assignments

Update an existing assignment

POST /v1/assignments/{id}

Scope
assignments:edit
Roles
admin, scheduler

Carries several distinct actions as payload variations rather than separate endpoints, which is what a tool catalog needs to know to map them:

  • Reschedule — send dateTimeSlots (with scheduleType, and scheduleFrequency when recurring). There is no separate reschedule endpoint; changing the slots *is* the reschedule.
  • Broadcast vs direct assignment — assignmentMethod: direct assigns the named providers, broadcast offers the assignment to the eligible pool. Use broadcastAudience to narrow that pool.
  • Cancel — NOT done here. Use POST /assignment/cancel-assignment, which requires reasonForCancellation alongside the id and start date/time. There is no start/stop-broadcast action on this endpoint or any other: broadcast state (off / active / onhold) advances through the assignment lifecycle and the scheduled timeout and escalation commands, not through a direct call.

Parameters

Path parameters

NameTypeDescription
id requiredstring

ID of the assignment to be updated

Example ASG-SA2IVL.

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

Request body required

69 top-level fields; 32 hold nested fields, listed below.

FieldTypeDescription
titlestring or null

Example Special interpreter — intake appointment.

descriptionstring or null

Example description of the assignment.

isPublishedboolean or null

Example true.

durationnumber or null

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

Example 1.5.

allowPointOfContactstring or null

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)
assignTostring or null

One of: client, organization. Example client.

billTostring or null

One of: organization, clients. Example clients.

clientobject or null (2 nested)
newClientobject or null (14 nested)

Creates a new client inline instead of using an existing one — alternative to client. Prohibited on a request-type assignment unless the same payload approves the request (requestStatus.id).

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 (9 nested)
locationobject or null (54 nested)

Required (locationType) when isPublished=true and the assignment has no stored location. Changing locationType away from one with assigned providers is rejected.

billingOrganizationLocationIdstring or null

Example 1.

billingClientLocationIdstring or null

Example 1.

billingOptionstring or null

Example primary.

timezonestring or null

Example America/New_York.

scheduleTypestring or null

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

oneTimeobject or null (10 nested)

Read only when scheduleType=one_time. Changing dateTimeSlots on a completed/past/canceled assignment with no linked finance documents is rejected.

multiDayobject or null (10 nested)

Read only when scheduleType=multi_day. Same restriction as oneTime.

recurringobject or null (10 nested)

Read only when scheduleType=recurring. Same restriction as oneTime.

priorityobject or null (2 nested)
statusobject or null (2 nested)

Prohibited on a request-type assignment unless the same payload approves the request. Terminal once in the canceled tree. Away from completed/final/past is restricted to No-Show or Canceled.

requestStatusobject or null (2 nested)

Setting this to the 'approved' status id converts a request into a real assignment (and its child requests), allowing client/newClient/status/assignProviders in the same payload.

requestNotApprovedReasonstring or null

Example Requested provider is unavailable for this window..

rateTypeobject or null (2 nested)
broadcastobject or null (2 nested)
broadcastNotifyboolean or null

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 or null

Example true.

partialDurationarray of object or null (4 nested)

Partial coverage windows (required when allowPartialCoverage is true). Omit to keep the assignment's existing windows.

assignmentMethodstring or null

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

enableBroadcastBestMatchboolean or null

Example true.

assignProvidersarray of object or null (7 nested)

Omit to keep the assignment's currently assigned providers.

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.

overrideConsumerPreferencesboolean or null

Accepted, but not currently saved on update.

Example true.

consumerPreferencesobject (8 nested)

The same override flags for the consumer's stored requirements and preferences. 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)
payStatusobject or null (1 nested)
estimatedCostobject or null

Client-calculated rate preview. Saving is skipped on a completed/past assignment unless the slot time actually changed or finance documents are already linked.

requirementAndPreferencesarray of object or null (22 nested)

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

quickAssignmentboolean or null

Rebuild requirements from quickServiceTypes and quickServiceProviderTypes.

Example false.

quickServiceTypesarray of object or null (1 nested)
quickServiceProviderTypesarray of object or null (1 nested)
customFieldsobject or null

Omitted fields are carried forward from what is already stored, so a partial edit never wipes previously saved custom field values.

externalCustomFieldsobject or null

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

documentsarray of object or null (3 nested)
affectFinancialsboolean or null

When a no-show finance sync fails, true re-throws the error instead of saving the no-show selection silently.

noshowStatusReasonarray of object or null (8 nested)

Required when status is being set to a No-Show status. Every participant not named here is cleared of their no-show flag.

cancellationDetailsobject (7 nested)

cancellationReason/cancellationCausedBy/billableForCancellation/billCancellationClient/payCancellationProvider are also accepted flat at the top level; the nested value under cancellationDetails wins if both are sent.

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

location 54 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
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
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.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

Removing a provider type that already has assigned providers is rejected (see location.onsite.serviceTypeBreakdown).

location.onsite.serviceTypes[].idinteger

Example 1.

location.onsite.serviceTypeBreakdownarray of object

Reducing totalProviders below the number of providers already assigned to that provider type is rejected.

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

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.

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.

quickServiceTypes 1 fields
FieldTypeDescription
quickServiceTypes[].idinteger

Example 1.

quickServiceProviderTypes 1 fields
FieldTypeDescription
quickServiceProviderTypes[].idinteger

Example 1.

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.

noshowStatusReason 8 fields
FieldTypeDescription
noshowStatusReason[].clientsarray of object
noshowStatusReason[].clients[].idstring

Example CLT-KBX0Q6.

noshowStatusReason[].clients[].noShowFeenumber or null

Example 50.

noshowStatusReason[].consumersarray of object
noshowStatusReason[].consumers[].idstring

Example CSM-SQEWP0T.

noshowStatusReason[].providersarray of object
noshowStatusReason[].providers[].idstring

Example SPR-H6OUI3.

noshowStatusReason[].reasonstring

Example Did not attend.

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": "Special interpreter — intake appointment",
  "description": "description of the assignment",
  "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",
  "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
      }
    ]
  },
  "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",
        "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": [
        {}
      ]
    }
  },
  "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"
  },
  "requestNotApprovedReason": "Requested provider is unavailable for this window.",
  "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"
  },
  "estimatedCost": {},
  "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"
      }
    }
  ],
  "quickAssignment": false,
  "quickServiceTypes": [
    {
      "id": 1
    }
  ],
  "quickServiceProviderTypes": [
    {
      "id": 1
    }
  ],
  "customFields": {},
  "externalCustomFields": {},
  "documents": [
    {
      "id": 0,
      "file": "string",
      "fileName": "intake-form.pdf"
    }
  ],
  "affectFinancials": true,
  "noshowStatusReason": [
    {
      "clients": [
        {
          "id": "CLT-KBX0Q6",
          "noShowFee": 50
        }
      ],
      "consumers": [
        {
          "id": "CSM-SQEWP0T"
        }
      ],
      "providers": [
        {
          "id": "SPR-H6OUI3"
        }
      ],
      "reason": "Did not attend"
    }
  ],
  "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/assignments/{id}" \
  -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,"duration":1.5,"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}]},"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","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":[{}]}},"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"},"requestNotApprovedReason":"Requested provider is unavailable for this window.","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"},"estimatedCost":{},"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"}}],"quickAssignment":false,"quickServiceTypes":[{"id":1}],"quickServiceProviderTypes":[{"id":1}],"customFields":{},"externalCustomFields":{},"documents":[{"id":0,"file":"string","fileName":"intake-form.pdf"}],"affectFinancials":true,"noshowStatusReason":[{"clients":[{"id":"CLT-KBX0Q6","noShowFee":50}],"consumers":[{"id":"CSM-SQEWP0T"}],"providers":[{"id":"SPR-H6OUI3"}],"reason":"Did not attend"}],"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

200 Assignment updated successfully

Assignment updated successfully

JSON
{
  "success": true,
  "message": "Assignment updated successfully",
  "data": {
    "id": "ASG-SA2IVL",
    "messages": [
      "string"
    ],
    "workItemFinancialsOutOfSync": true,
    "noShowFinanceSync": {}
  }
}
Response fields (7)
FieldTypeDescription
successboolean

Example true.

messagestring

The main message; varies by what changed (e.g. a request-approval conversion message).

Example Assignment updated successfully.

dataobject
data.idstring

Example ASG-SA2IVL.

data.messagesarray of string

Secondary notices about the save (e.g. providers that could not be re-attached).

data.workItemFinancialsOutOfSyncboolean or null

Present when affectFinancials=false was sent but the change actually affects billed amounts.

data.noShowFinanceSyncobject or null

Present when a no-show selection changed.

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:edit' 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:edit' 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 updation 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 updation failed.

messagestring

Example An unexpected error occurred — please try again..