API reference › Assignments

Retrieve a list of assignments

GET /v1/assignments

Scope
assignments:read or shifts:read
Roles
admin, scheduler

Fetches a paginated list of assignments based on search criteria, filters, and sorting options. With isFromPortal=true the list also carries shifts (the Summary tab of a client, consumer or provider); a Scheduler or custom role needs Read on Assignments or Shifts (an API key the matching scope): assignments are left out without Assignments Read, shifts without Shifts Read, and without either the answer is an empty page.

Parameters

Query parameters

NameTypeDescription
searchstring

Search query to filter assignmenr by name, email, or assignment Id.

Example assignment 1.

priorityinteger

Filter assignment by priority ID.

Example 1.

statusinteger

Filter by assignment-status ID. Statuses are tenant-configurable rows, not a fixed vocabulary, so there is no enum here — read the valid IDs for this tenant from GET /assignment-statuses. A hard-coded value will go stale the moment a tenant edits its statuses.

Example 1.

serviceTypesinteger

Filter assignment by service Types ID.

Example 1.

broadcaststring

Filter by broadcast state. Matched exactly against assignments.broadcast.

One of: off, active, onhold. Example active.

serviceProviderstring

Filter assignment by service provider ID.

Example SRP-26TR5.

consumerstring

Filter assignment by consumer ID.

Example CSM-12FGT4.

clientstring

Filter assignment by client ID.

Example CLT-567FGR.

isPublishedboolean

Filter assignments by their Published status.

Example true.

without_active_invoiceboolean

when true, only assignments with no active (non-Canceled/Void) invoice link.

Example true.

without_active_payableboolean

when true, only assignments with no active (non-Canceled/Void) payable link.

Example true.

sortBystring

Sort clients by a specific field (e.g., 'name', 'created_at').

Example name.

sortOrderstring

Sorting order: ascending ('asc') or descending ('desc').

One of: asc, desc. Example asc.

perPageinteger

Number of clients to retrieve per page.

Example 10.

columnsstring

Search query within visible column content.

Example name,status,priority.

customTabstring

Preset filter tab, applied in addition to any other filters.

One of: active, archived, past, need_attention, upcoming, organization_request. Example active.

startDatestring (date)

Filter assignments by scheduled start date on or after this date (YYYY-MM-DD).

endDatestring (date)

Filter assignments by scheduled end date on or before this date (YYYY-MM-DD).

startTimestring (time)

Filter assignments whose scheduled time range overlaps this start time (HH:MM:SS). Pairs with endTime; an overnight range (startTime later than endTime) is handled as spanning midnight.

endTimestring (time)

Filter assignments whose scheduled time range overlaps this end time (HH:MM:SS). Pairs with startTime.

pageinteger

Page number (default: 1).

Example 1.

locationTypestring

Filter by the Location column: the work item location type.

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

serviceProviderTypesinteger

Filter by a provider type ID the work item asks for in its service-type breakdown (matches before anyone of that type is assigned).

Example 3.

requestSourcestring

Filter by the Request Source column (origin of the request).

One of: client-portal, consumer-portal, scheduler, public-assistant. Example client-portal.

updated_sincestring

Only work items that changed at or after this moment: the assignment itself, any of its slots, any of its provider rows (assigned, removed or a status change) or any of its check-ins. Assignments deleted in the window are returned too, with deletedAt set, so the caller can drop them; canceled ones carry their status as usual. ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD, taken as 00:00 UTC). A date-time with no zone is refused. The response meta.asOf is the moment the list was read; use it as the next updated_since. Keep the meta.asOf of the first page of a pull: every page reports its own, and the first one is the moment the pull began. Start each pull a few minutes before the previous meta.asOf: a change committed while a list was being read can carry a time just before it, and a row returned twice is harmless.

Example 2026-10-22T06:00:00Z.

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

Example request

Shell
curl "https://api.fetchfido.ai/v1/assignments" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID"

Try it

Responses

200 Assignments retrieved successfully

Assignments retrieved successfully

JSON
{
  "success": true,
  "data": [
    {
      "startDate": "2026-01-15",
      "endDate": "2026-01-15",
      "startTime": "09:00:00",
      "endTime": "09:00:00",
      "convertedStartDate": "2026-01-15",
      "convertedEndDate": "2026-01-15",
      "convertedStartTime": "09:00:00",
      "convertedEndTime": "09:00:00",
      "userTimezone": "America/New_York",
      "timezone": "America/New_York",
      "assignmentDateTooltip": "Jan 15, 2026 9:00 AM – 11:00 AM",
      "userDateTooltip": "Jan 15, 2026 9:00 AM – 11:00 AM",
      "requestedOn": "2026-01-15",
      "submissionDate": "2026-01-15",
      "timeSlots": {
        "id": 1,
        "startTime": "09:00:00",
        "endTime": "09:00:00"
      },
      "deletedAt": "string"
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 5,
    "perPage": 10,
    "total": 50,
    "asOf": "2026-10-23T06:00:00Z"
  }
}
Response fields (27)

3 top-level fields; 2 hold nested fields, listed below.

FieldTypeDescription
successboolean

Example true.

dataarray of object (19 nested)
metaobject (5 nested)

Nested fields

data 19 fields
FieldTypeDescription
data[].startDatestring or null

Example 2026-01-15.

data[].endDatestring or null

Example 2026-01-15.

data[].startTimestring or null

Example 09:00:00.

data[].endTimestring or null

Example 09:00:00.

data[].convertedStartDatestring

Example 2026-01-15.

data[].convertedEndDatestring

Example 2026-01-15.

data[].convertedStartTimestring

Example 09:00:00.

data[].convertedEndTimestring

Example 09:00:00.

data[].userTimezonestring or null

Example America/New_York.

data[].timezonestring or null

Example America/New_York.

data[].assignmentDateTooltipstring

Example Jan 15, 2026 9:00 AM – 11:00 AM.

data[].userDateTooltipstring

Example Jan 15, 2026 9:00 AM – 11:00 AM.

data[].requestedOnstring

Example 2026-01-15.

data[].submissionDatestring

Example 2026-01-15.

data[].timeSlotsobject or null
data[].timeSlots.idinteger

Example 1.

data[].timeSlots.startTimestring

Example 09:00:00.

data[].timeSlots.endTimestring

Example 09:00:00.

data[].deletedAtstring (date-time) or null

Only with updated_since: when the assignment was deleted (UTC, ending in Z), or empty while it exists.

meta 5 fields
FieldTypeDescription
meta.currentPageinteger

Example 1.

meta.lastPageinteger

Example 5.

meta.perPageinteger

Example 10.

meta.totalinteger

Example 50.

meta.asOfstring (date-time)

Only with updated_since: the moment the list was read; use it as the next updated_since. Take it from the first page of a pull; every page reports its own.

Example 2026-10-23T06:00:00Z.

400 Bad request

Bad Request - Invalid query parameters

JSON
{
  "success": false,
  "message": "Invalid parameters. Ensure all required filters are correct."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid parameters. Ensure all required filters are correct..

401 Not signed in

Unauthorized - Authentication required

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

updated_since is not an ISO 8601 date-time with a time zone, or a date.

JSON
{
  "status": "error",
  "message": "An unexpected error occurred — please try again.",
  "errors": {
    "updated_since": [
      "The updated_since must be an ISO 8601 date-time with a time zone (for example 2026-10-22T06:00:00Z) or a date (YYYY-MM-DD)."
    ]
  }
}
Response fields (3)
FieldTypeDescription
statusstring

Example error.

messagestring

Example An unexpected error occurred — please try again..

errorsobject
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

Internal Server Error

JSON
{
  "success": false,
  "message": "An unexpected error occurred. Please try again later."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred. Please try again later..