API reference › Consumers

Retrieve a list of consumers

GET /v1/consumers

Scope
consumers:read
Roles
admin, scheduler

Fetches a paginated list of consumers based on filters, search criteria, and sorting options.

Parameters

Query parameters

NameTypeDescription
searchstring

Search consumers by name, email, or consumer ID.

serviceTypesstring

Comma-separated list of service type IDs.

hearingStatusstring

Hearing status filter.

isPublishedboolean

Filter consumers by their Published status.

Example true.

needsReviewboolean

Only consumers whose guardianship review is open (turned 18 with guardians still acting, pending or snoozed).

Example true.

communicationModesstring

Comma-separated list of communication mode IDs.

associatedClientstring

Comma-separated list of client IDs associated with the consumer.

statusinteger

Filter by status ID.

priorityinteger

Filter by priority ID.

startDatestring (date)

Start date for filtering consumers (YYYY-MM-DD).

endDatestring (date)

End date for filtering consumers (YYYY-MM-DD).

sortBystring

Field to sort by (e.g., 'user', 'priority', 'created_at').

sortOrderstring

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

One of: asc, desc.

perPageinteger

Number of records per page.

Example 10.

columnsstring

Comma-separated list of columns for filtering or display. Valid columns: user, status, priority, serviceTypes, hearingStatus, communicationModes, associatedClient.

Example user, status, priority, serviceTypes, hearingStatus, communicationModes, associatedClient.

portalAccessboolean

Filter by the Portal Access column.

Example true.

inviteStatestring

Filter by the Invite State column, using the same rule as the inviteState badge.

One of: invited, invite_expired, active, active_never_signed_in, not_invited. Example invite_expired.

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

Example request

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

Try it

Responses

200 Consumers retrieved successfully

Consumers retrieved successfully

JSON
{
  "success": true,
  "data": [
    {
      "id": "USR-LBW3CV",
      "name": "Example name",
      "onlineStatus": "online",
      "email": "user@example.com",
      "phone": "+1-555-0142",
      "logo": "https://cdn.example.com/image.png",
      "status": 1,
      "statusName": "Active",
      "statusChangedAt": "2026-06-30 14:29:00",
      "publishedAt": "2026-06-30 14:29:00",
      "priority": 1,
      "priorityName": "Example name",
      "associatedClient": [
        {
          "client": "CLT-PJ6TFP",
          "clientName": "Test2",
          "clientImage": "hi",
          "relationship": "employee"
        }
      ],
      "serviceTypes": [
        6
      ],
      "serviceTypesName": [
        "string"
      ],
      "hearingStatus": {
        "id": "string",
        "label": "Example label"
      },
      "communicationModes": [
        1
      ],
      "communicationModesName": [
        "ASL (American Sign Language)"
      ],
      "portalAccess": true,
      "canLogin": true,
      "isPublished": true,
      "activeAssignment": 1,
      "gender": {
        "id": "string",
        "label": "Example label"
      },
      "requiresPrimaryReassignmentOnDelete": "string",
      "otherActiveRoles": "string"
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 1,
    "perPage": 10,
    "total": 1
  }
}
Response fields (40)

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

FieldTypeDescription
successboolean

Example true.

dataarray of object (33 nested)
metaobject (4 nested)

Nested fields

data 33 fields
FieldTypeDescription
data[].idstring

Example USR-LBW3CV.

data[].namestring or null

Example Example name.

data[].onlineStatusstring

Example online.

data[].emailstring or null

Example user@example.com.

data[].phonestring or null

Example +1-555-0142.

data[].logostring or null

Example https://cdn.example.com/image.png.

data[].statusinteger or null

Example 1.

data[].statusNamestring or null

Example Active.

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

When the consumer entered its current status

Example 2026-06-30 14:29:00.

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

When the consumer entered its current publication state

Example 2026-06-30 14:29:00.

data[].priorityinteger or null

Example 1.

data[].priorityNamestring or null

Example Example name.

data[].associatedClientarray of object
data[].associatedClient[].clientstring

Example CLT-PJ6TFP.

data[].associatedClient[].clientNamestring

Example Test2.

data[].associatedClient[].clientImagestring

Example hi.

data[].associatedClient[].relationshipstring

Example employee.

data[].serviceTypesarray of integer
data[].serviceTypesNamearray of string
data[].hearingStatusobject or null
data[].hearingStatus.idstring
data[].hearingStatus.labelstring

Example Example label.

data[].communicationModesarray of integer
data[].communicationModesNamearray of string
data[].portalAccessboolean

Example true.

data[].canLoginboolean

Example true.

data[].isPublishedboolean or null

Example true.

data[].activeAssignmentinteger

Example 1.

data[].genderobject or null
data[].gender.idstring
data[].gender.labelstring

Example Example label.

data[].requiresPrimaryReassignmentOnDeletestring
data[].otherActiveRolesstring
meta 4 fields
FieldTypeDescription
meta.currentPageinteger

Example 1.

meta.lastPageinteger

Example 1.

meta.perPageinteger

Example 10.

meta.totalinteger

Example 1.

400 Bad request

Bad Request - Invalid parameters

JSON
{
  "success": false,
  "message": "Invalid filters provided. Please check the query parameters."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid filters provided. Please check the query parameters..

401 Not signed in

Unauthorized - Token missing or invalid

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 'consumers: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 'consumers:read' 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

Internal Server 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..