API reference › Clients

Retrieve a list of clients

GET /v1/clients

Scope
clients:read
Roles
admin, scheduler

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

Parameters

Query parameters

NameTypeDescription
searchstring

Search query to filter clients by name, email, or client_id.

Example acme.

priorityinteger

Filter clients by priority ID.

Example 1.

statusinteger

Filter clients by status ID.

Example 1.

portalAccessboolean

Filter clients by their Portal Access status.

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.

isPublishedboolean

Filter clients by their Published status.

Example true.

sortBystring

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

Example clientName.

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 clientName,address,contact,status.

startDatestring (date)

Filter clients created on or after this date (YYYY-MM-DD).

endDatestring (date)

Filter clients created on or before this date (YYYY-MM-DD).

localSearchstring

The table's own search box: matches only the columns named in columns. search is the global search.

pageinteger

Page number (default: 1).

Example 1.

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

Example request

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

Try it

Responses

200 Clients retrieved successfully

Clients retrieved successfully

JSON
{
  "success": true,
  "data": [
    {
      "id": "CLT-XWB2RY",
      "name": "Example name",
      "onlineStatus": "online",
      "email": "user@example.com",
      "logo": "https://cdn.example.com/image.png",
      "phone": "+1-555-0142",
      "portalAccess": true,
      "canLogin": true,
      "inviteState": "invited",
      "inviteExpiresAt": "string",
      "status": 1,
      "statusName": "Active",
      "priority": 1,
      "priorityName": "Example name",
      "isPublished": true,
      "addressLine1": "123 Main St",
      "addressLine2": "Suite 200",
      "city": "Austin",
      "state": "string",
      "postalCode": "90210",
      "contactName": "Jane Smith",
      "contactEmail": "user@example.com",
      "contactPhone": "+1-555-0142",
      "contactPhoneExtension": "101",
      "contactImage": "https://cdn.example.com/image.png",
      "activeAssignments": 3,
      "lastAssignmentDate": "2026-08-21",
      "statusChangedAt": "2026-06-30 14:29:07",
      "publishedAt": "2026-06-30 14:29:07",
      "gender": {
        "id": "string",
        "label": "Example label"
      },
      "hearingStatus": {
        "id": "string",
        "label": "Example label"
      },
      "industry": [
        null
      ],
      "requiresPrimaryReassignmentOnDelete": "string",
      "otherActiveRoles": "string"
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 5,
    "perPage": 10,
    "total": 50
  }
}
Response fields (45)

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

FieldTypeDescription
successboolean

Example true.

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

Nested fields

data 38 fields
FieldTypeDescription
data[].idstring

Example CLT-XWB2RY.

data[].namestring or null

Example Example name.

data[].onlineStatusstring

Example online.

data[].emailstring or null

Example user@example.com.

data[].logostring or null

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

data[].phonestring or null

Example +1-555-0142.

data[].portalAccessboolean

Example true.

data[].canLoginboolean

Example true.

data[].inviteStatestring

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

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

When the invite link expires or expired; null when there is no invite link

data[].statusinteger or null

Example 1.

data[].statusNamestring or null

Example Active.

data[].priorityinteger or null

Example 1.

data[].priorityNamestring or null

Example Example name.

data[].isPublishedboolean

Example true.

data[].addressLine1string or null

Example 123 Main St.

data[].addressLine2string or null

Example Suite 200.

data[].citystring or null

Example Austin.

data[].statestring or null
data[].postalCodestring or null

Example 90210.

data[].contactNamestring or null

Example Jane Smith.

data[].contactEmailstring or null

Example user@example.com.

data[].contactPhonestring or null

Example +1-555-0142.

data[].contactPhoneExtensionstring or null

Example 101.

data[].contactImagestring or null

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

data[].activeAssignmentsinteger

Count of active assignments and shifts linked to the client

Example 3.

data[].lastAssignmentDatestring (date) or null

Latest start date across the client's active assignments and shifts

Example 2026-08-21.

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

When the client entered its current status

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

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

When the client entered its current publication state

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

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

Example Example label.

data[].hearingStatusobject or null
data[].hearingStatus.idstring
data[].hearingStatus.labelstring

Example Example label.

data[].industryarray of any or null
data[].requiresPrimaryReassignmentOnDeletestring
data[].otherActiveRolesstring
meta 4 fields
FieldTypeDescription
meta.currentPageinteger

Example 1.

meta.lastPageinteger

Example 5.

meta.perPageinteger

Example 10.

meta.totalinteger

Example 50.

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 'clients: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 'clients: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 later."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

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