Resolve client/consumer/org default or override preferences for the assignment/shift form
POST /v1/preference
- Scope
assignments:readorshifts: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.
| Field | Type | Description |
|---|---|---|
client | string or null | A single client id — a bare string, NOT the {id, label} object the assignment/shift create and update endpoints use. Example |
clientIds | string or null | Comma-separated client ids — the multi-client alternative to client (used for a shift with assignTo=organization and multiple assignClients). Example |
consumer | string or null | Comma-separated consumer ids — a plain string, NOT the array-of-objects shape used elsewhere. Example |
assignTo | string or null | One of: |
isAssignment | boolean or null | Selects the assignment vs. shift default-preference column when isDefault is true. Example |
isDefault | boolean or null | Resolves the org→client→consumer default tier instead of applying an override. Example |
locationType | string or null | When sent with isDefault, also returns the default location for that type. One of: |
assignmentId | string or null | When editing an existing assignment, merges in its already-assigned providers' own provider-to-provider restrictions. Example |
shiftId | string or null | Same as assignmentId, for an existing shift. Example |
clientPreferences | array of string or null | Override keys the user checked on the client side — e.g. restrictedServiceProvider, preferredServiceProvider. |
consumerPreferences | array of string or null | Same override keys, consumer side. |
serviceProviderPreferences | array 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). |
disableOverride | string or null | The single override key the user most recently unchecked; resets that field to its full default. Example |
noOverride | boolean or null | Echoes requirementAndPreferences back unchanged. |
requirementAndPreferences | array of object or null (16 nested) | Passed through/merged as-is; not validated here. |
Nested fields
requirementAndPreferences 16 fields
| Field | Type | Description |
|---|---|---|
requirementAndPreferences[].id | string or null | |
requirementAndPreferences[].serviceType | object or null | |
requirementAndPreferences[].serviceType.id | integer | Example |
requirementAndPreferences[].serviceProviderType | object or null | |
requirementAndPreferences[].serviceProviderType.id | integer | Example |
requirementAndPreferences[].skill | object or null | |
requirementAndPreferences[].skill.id | integer | Example |
requirementAndPreferences[].gender | object or null | |
requirementAndPreferences[].gender.id | integer | Example |
requirementAndPreferences[].clearance | array of object or null | |
requirementAndPreferences[].clearance[].id | integer | Example |
requirementAndPreferences[].specialization | array of object or null | |
requirementAndPreferences[].specialization[].id | integer | Example |
requirementAndPreferences[].certification | array of object or null | |
requirementAndPreferences[].certification[].id | integer | Example |
requirementAndPreferences[].isDefault | boolean or null |
Example
{
"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
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
{
"success": true,
"message": "Preferences fetched successfully.",
"data": {}
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | 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.
{
"success": false,
"message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
"errors": null,
"code": "API_KEY_MISSING"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
403 Not allowed
Scope, tenant, IP allow-list or RBAC check failed.
{
"success": false,
"message": "You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope.",
"errors": null,
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Always empty on this status. Example |
422 Validation failed
Validation failed
{
"success": false,
"message": "Validation failed",
"data": {
"client": [
"The selected client is invalid."
]
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.client | array of string |
429 Too many requests
Rate limit exceeded. See Retry-After.
{
"success": false,
"message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
"errors": null,
"code": "RATE_LIMITED"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
500 Server error
Unexpected error
{
"success": false,
"message": "An unexpected error occurred — please try again."
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |