API reference › Providers

Retrieve a list of service providers

GET /v1/providers

Scope
providers:read
Roles
admin, scheduler

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

Parameters

Query parameters

NameTypeDescription
searchstring

Search query to filter service providers by name, email, or provider ID.

Example jane.

statusinteger

Filter service providers by status ID.

Example 1.

hearingStatusstring

Filter service providers by hearing status.

One of: deaf, hard_to_hearing, hearing, deaf_blind. Example deaf.

employmentStatusstring

Filter service providers by employment status.

One of: full_time, part_time, contractor. Example full_time.

skillLevelinteger

Filter service providers by skill ID.

Example 1.

serviceTypeinteger

Filter service providers by service type ID.

Example 1.

certificationinteger

Filter service providers by certification ID.

Example 1.

clearanceinteger

Filter service providers by clearance ID.

Example 1.

specializationinteger

Filter service providers by specialization ID.

Example 1.

isPublishedboolean

Filter service providers by their Published status.

Example true.

sortBystring

Sort service providers 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 service providers to retrieve per page.

Example 10.

pageinteger

Page number to retrieve.

Example 1.

columnsstring

Search query within visible column content.

Example user,status,serviceType.

startDatestring (date)

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

endDatestring (date)

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

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

Example request

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

Try it

Responses

200 Service providers retrieved successfully

Service providers retrieved successfully

JSON
{
  "success": true,
  "data": [
    {
      "id": "USR-LBW3CV",
      "name": "Example name",
      "email": "user@example.com",
      "phone": "+1-555-0142",
      "logo": "https://cdn.example.com/image.png",
      "status": {
        "id": 1,
        "label": "Active"
      },
      "activeAssignments": 3,
      "lastAssignmentDate": "2026-01-15",
      "specializations": [
        {
          "id": 1,
          "label": "ASL"
        }
      ],
      "clearance": [
        {
          "id": 1,
          "label": "Background Check"
        }
      ],
      "employmentStatus": "string",
      "serviceProviderRole": "string",
      "hearingStatus": "string",
      "skill": "string",
      "certifications": [
        {
          "id": 1,
          "label": "NIC"
        }
      ],
      "serviceTypes": [
        {
          "id": 1,
          "label": "ASL Interpreting"
        }
      ],
      "serviceProviderTypes": [
        {
          "id": 1,
          "label": "Interpreter"
        }
      ],
      "statusChangedAt": "2026-01-15",
      "publishedAt": "2026-01-15",
      "isPublished": true,
      "portalAccess": true,
      "canLogin": true,
      "gender": {
        "id": "male",
        "label": "Male"
      },
      "onlineStatus": "online",
      "requiresPrimaryReassignmentOnDelete": "string",
      "otherActiveRoles": "string"
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 5,
    "perPage": 10,
    "total": 50
  }
}
Response fields (47)

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

FieldTypeDescription
successboolean

Example true.

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

Nested fields

data 40 fields
FieldTypeDescription
data[].idstring

Example USR-LBW3CV.

data[].namestring

Example Example name.

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[].statusobject or null
data[].status.idinteger

Example 1.

data[].status.labelstring

Example Active.

data[].activeAssignmentsinteger

Count of active assignments and shifts linked to the provider

Example 3.

data[].lastAssignmentDatestring or null

Example 2026-01-15.

data[].specializationsarray of object
data[].specializations[].idinteger

Example 1.

data[].specializations[].labelstring

Example ASL.

data[].clearancearray of object
data[].clearance[].idinteger

Example 1.

data[].clearance[].labelstring

Example Background Check.

data[].employmentStatusstring or null
data[].serviceProviderRolestring or null
data[].hearingStatusstring or null
data[].skillstring or null
data[].certificationsarray of object
data[].certifications[].idinteger

Example 1.

data[].certifications[].labelstring

Example NIC.

data[].serviceTypesarray of object
data[].serviceTypes[].idinteger

Example 1.

data[].serviceTypes[].labelstring

Example ASL Interpreting.

data[].serviceProviderTypesarray of object
data[].serviceProviderTypes[].idinteger

Example 1.

data[].serviceProviderTypes[].labelstring

Example Interpreter.

data[].statusChangedAtstring or null

Example 2026-01-15.

data[].publishedAtstring or null

Example 2026-01-15.

data[].isPublishedboolean or null

Example true.

data[].portalAccessboolean or null

Example true.

data[].canLoginboolean

Example true.

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

Example male.

data[].gender.labelstring

Example Male.

data[].onlineStatusstring

Example online.

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 'providers: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 'providers: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..