API reference › Clients › Locations

Retrieve a list of client locations

GET /v1/clients/{client}/locations

Scope
clients:read
Roles
admin, scheduler

Fetches a paginated list of client locations based on filters like search, client, location, sorting, etc.

Parameters

Path parameters

NameTypeDescription
client requiredstring

Unique identifier of the client

Example CLT-VX6R0.

Query parameters

NameTypeDescription
searchstring

Search query to filter locations by name, address, city, etc.

locationstring

Filter locations by location name.

columnsstring

Search query within visible column content.

Example clientName,address,contact,status.

isPublishedboolean

Filter clients location by their Published status.

Example true.

statusinteger

Filter locations by status id (from the statuses lookup table).

Example 1.

startDatestring (date)

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

endDatestring (date)

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

sortBystring

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

sortOrderstring

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

One of: asc, desc.

perPageinteger

Number of locations to retrieve per page.

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

Example request

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

Try it

Responses

200 Locations retrieved successfully

Locations retrieved successfully

JSON
{
  "success": true,
  "data": [
    {
      "id": "CLTLOC-HQBS7",
      "locationName": "Main Office",
      "logo": "https://cdn.example.com/image.png",
      "addressLine1": "123 Main St",
      "addressLine2": "Suite 200",
      "city": "Austin",
      "state": {
        "id": 1,
        "label": "Example label",
        "code": "string"
      },
      "postalCode": "90210",
      "status": 1,
      "statusName": "Active",
      "isPublished": true,
      "isDefault": true,
      "isPrimaryAddress": true,
      "department": "Radiology",
      "contactName": "Jane Smith",
      "contactImage": "https://cdn.example.com/image.png",
      "contactEmail": "user@example.com",
      "contactPhone": "+1-555-0142",
      "contactPhoneExtension": "101",
      "contactPhoneType": "sms_and_voice",
      "countryCode": "+1",
      "client": "CLT-XWB2RY",
      "clientName": "Example name",
      "clientImage": "https://cdn.example.com/image.png",
      "onlineStatus": "online",
      "clientEmail": "user@example.com",
      "clientPhone": "+1-555-0142",
      "clientType": "Individual",
      "timezone": "America/New_York"
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 1,
    "perPage": 10,
    "total": 1
  }
}
Response fields (39)

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

FieldTypeDescription
successboolean

Example true.

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

Nested fields

data 32 fields
FieldTypeDescription
data[].idstring

Example CLTLOC-HQBS7.

data[].locationNamestring

Example Main Office.

data[].logostring or null

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

data[].addressLine1string or null

Example 123 Main St.

data[].addressLine2string or null

Example Suite 200.

data[].citystring or null

Example Austin.

data[].stateobject or null
data[].state.idinteger

Example 1.

data[].state.labelstring

Example Example label.

data[].state.codestring
data[].postalCodestring or null

Example 90210.

data[].statusinteger or null

Example 1.

data[].statusNamestring or null

Example Active.

data[].isPublishedboolean

Example true.

data[].isDefaultboolean

Example true.

data[].isPrimaryAddressboolean

Example true.

data[].departmentstring or null

Example Radiology.

data[].contactNamestring or null

Example Jane Smith.

data[].contactImagestring or null

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

data[].contactEmailstring or null

Example user@example.com.

data[].contactPhonestring or null

Example +1-555-0142.

data[].contactPhoneExtensionstring or null

Example 101.

data[].contactPhoneTypestring or null

Example sms_and_voice.

data[].countryCodestring or null

Example +1.

data[].clientstring

Example CLT-XWB2RY.

data[].clientNamestring or null

Example Example name.

data[].clientImagestring or null

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

data[].onlineStatusstring

Example online.

data[].clientEmailstring or null

Example user@example.com.

data[].clientPhonestring or null

Example +1-555-0142.

data[].clientTypestring or null

Example Individual.

data[].timezonestring or null

Example America/New_York.

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