API reference › Assignments

Resolve client/consumer/org default or override preferences for the assignment/shift form

POST /v1/preference

Scope
assignments:read or shifts:read

A lookup, not a mutation — despite the POST verb. Three modes: noOverride echoes requirementAndPreferences back unchanged; isDefault resolves the organization → client → consumer default preferences (merging restricted and preferred providers, priority, timezone and, when locationType is sent, default location data); otherwise the clientPreferences, consumerPreferences and serviceProviderPreferences overrides are layered on top of the merged restricted and preferred provider lists. When editing, assignmentId or shiftId also merges in the restrictions of the providers already assigned to that work item.

Parameters

None of its own.

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

Request body

15 top-level fields; 1 hold nested fields, listed below.

FieldTypeDescription
clientstring or null

A single client id — a bare string, NOT the {id, label} object the assignment/shift create and update endpoints use.

Example CLT-KBX0Q6.

clientIdsstring or null

Comma-separated client ids — the multi-client alternative to client (used for a shift with assignTo=organization and multiple assignClients).

Example CLT-KBX0Q6,CLT-OTHER1.

consumerstring or null

Comma-separated consumer ids — a plain string, NOT the array-of-objects shape used elsewhere.

Example CSM-SQEWP0T,CSM-OTHER1.

assignTostring or null

One of: client, organization. Example client.

isAssignmentboolean or null

Selects the assignment vs. shift default-preference column when isDefault is true.

Example true.

isDefaultboolean or null

Resolves the org→client→consumer default tier instead of applying an override.

Example true.

locationTypestring or null

When sent with isDefault, also returns the default location for that type.

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

assignmentIdstring or null

When editing an existing assignment, merges in its already-assigned providers' own provider-to-provider restrictions.

Example ASG-SA2IVL.

shiftIdstring or null

Same as assignmentId, for an existing shift.

Example SFT-MNP4PJ.

clientPreferencesarray of string or null

Override keys the user checked on the client side — e.g. restrictedServiceProvider, preferredServiceProvider.

consumerPreferencesarray of string or null

Same override keys, consumer side.

serviceProviderPreferencesarray of string or null

Scheduler-side overrides applied to the resulting userRestricted list: restrictedServiceProviders (drop provider-to-provider restrictions), restrictedConsumers, restrictedClients (drop the reverse-direction block for that side).

disableOverridestring or null

The single override key the user most recently unchecked; resets that field to its full default.

Example restrictedServiceProvider.

noOverrideboolean or null

Echoes requirementAndPreferences back unchanged.

requirementAndPreferencesarray of object or null (16 nested)

Passed through/merged as-is; not validated here.

Nested fields

requirementAndPreferences 16 fields
FieldTypeDescription
requirementAndPreferences[].idstring or null
requirementAndPreferences[].serviceTypeobject or null
requirementAndPreferences[].serviceType.idinteger

Example 1.

requirementAndPreferences[].serviceProviderTypeobject or null
requirementAndPreferences[].serviceProviderType.idinteger

Example 1.

requirementAndPreferences[].skillobject or null
requirementAndPreferences[].skill.idinteger

Example 1.

requirementAndPreferences[].genderobject or null
requirementAndPreferences[].gender.idinteger

Example 1.

requirementAndPreferences[].clearancearray of object or null
requirementAndPreferences[].clearance[].idinteger

Example 1.

requirementAndPreferences[].specializationarray of object or null
requirementAndPreferences[].specialization[].idinteger

Example 1.

requirementAndPreferences[].certificationarray of object or null
requirementAndPreferences[].certification[].idinteger

Example 1.

requirementAndPreferences[].isDefaultboolean or null

Example

JSON
{
  "client": "CLT-KBX0Q6",
  "clientIds": "CLT-KBX0Q6,CLT-OTHER1",
  "consumer": "CSM-SQEWP0T,CSM-OTHER1",
  "assignTo": "client",
  "isAssignment": true,
  "isDefault": true,
  "locationType": "onsite",
  "assignmentId": "ASG-SA2IVL",
  "shiftId": "SFT-MNP4PJ",
  "clientPreferences": [
    "restrictedServiceProvider"
  ],
  "consumerPreferences": [
    "restrictedServiceProvider"
  ],
  "serviceProviderPreferences": [
    "restrictedServiceProviders"
  ],
  "disableOverride": "restrictedServiceProvider",
  "noOverride": true,
  "requirementAndPreferences": [
    {
      "id": "string",
      "serviceType": {
        "id": 1
      },
      "serviceProviderType": {
        "id": 1
      },
      "skill": {
        "id": 1
      },
      "gender": {
        "id": 1
      },
      "clearance": [
        {
          "id": 1
        }
      ],
      "specialization": [
        {
          "id": 1
        }
      ],
      "certification": [
        {
          "id": 1
        }
      ],
      "isDefault": true
    }
  ]
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/preference" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"client":"CLT-KBX0Q6","clientIds":"CLT-KBX0Q6,CLT-OTHER1","consumer":"CSM-SQEWP0T,CSM-OTHER1","assignTo":"client","isAssignment":true,"isDefault":true,"locationType":"onsite","assignmentId":"ASG-SA2IVL","shiftId":"SFT-MNP4PJ","clientPreferences":["restrictedServiceProvider"],"consumerPreferences":["restrictedServiceProvider"],"serviceProviderPreferences":["restrictedServiceProviders"],"disableOverride":"restrictedServiceProvider","noOverride":true,"requirementAndPreferences":[{"id":"string","serviceType":{"id":1},"serviceProviderType":{"id":1},"skill":{"id":1},"gender":{"id":1},"clearance":[{"id":1}],"specialization":[{"id":1}],"certification":[{"id":1}],"isDefault":true}]}'

Try it

Responses

200 Preferences fetched successfully

Preferences fetched successfully

JSON
{
  "success": true,
  "message": "Preferences fetched successfully.",
  "data": {}
}
Response fields (3)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Preferences fetched successfully..

dataobject

Shape varies by mode (noOverride / isDefault / override). May include any of: requirementAndPreferences (echoed, noOverride only), timezone, priority {id, label}, userRestricted/userPreferred (arrays of {id, label}), and — when isDefault and locationType are both sent — default location fields.

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:read' 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:read' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Validation failed

JSON
{
  "success": false,
  "message": "Validation failed",
  "data": {
    "client": [
      "The selected client is invalid."
    ]
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Validation failed.

dataobject
data.clientarray of string
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,
  "message": "An unexpected error occurred — please try again."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred — please try again..