Skip to content
Docs
Docs / REST API / Guides

Querying collections

MD View as MarkdownPlain text version of this page
Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page

Page through, filter, sort and expand the resource collections (locations, districts, categories, groups and users).

On this page

The resource collections — locations, location groups, districts, location categories and users — share one set of query parameters for pagination, filtering, sorting and including related records. The data endpoints (/api/v1/data/*), risk findings and orders take their own parameters, described on each endpoint's reference page.

Pagination

Collections are paginated by page number.

Parameter Meaning Default
page[size] Results per page, up to 100 30
page[number] Which page to return, starting at 1 1
Shell 
curl "https://app.franchisesee.com/api/v1/locations?page[size]=25&page[number]=2" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Every paginated response carries links to the neighbouring pages and a meta block with the totals:

JSON 
{
  "data": [
    { "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e", "name": "Downtown Austin" }
  ],
  "links": {
    "first": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
    "last": "https://app.franchisesee.com/api/v1/locations?page[number]=10",
    "prev": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
    "next": "https://app.franchisesee.com/api/v1/locations?page[number]=3"
  },
  "meta": {
    "current_page": 2,
    "from": 26,
    "last_page": 10,
    "path": "https://app.franchisesee.com/api/v1/locations",
    "per_page": 25,
    "to": 50,
    "total": 250
  }
}

To read a whole collection, follow links.next until it is null.

Filtering

Add filter[field]=value to narrow a collection. Several filters combine with AND:

Shell 
GET /api/v1/districts?filter[district_group_id]=e1a4c8b2-7d3f-4b6e-9a2c-8f5d1e3b7a90&filter[external_id]=CTX

Filters match part of a value and ignore case. filter[external_id]=STR-1 also returns STR-10 and STR-1042. When you look a record up by its external id or email to change it, check the exact value in the results before you act on one.

To match any of several values, separate them with commas: filter[external_id]=STR-1042,STR-1043 returns records matching either.

Sorting

Pass sort with a field name. Prefix it with - for descending order, and separate several fields with commas; later fields break ties in earlier ones:

Shell 
GET /api/v1/locations?sort=-created_at,name

Pass include to return related records nested inside each result, instead of fetching them one by one:

Shell 
GET /api/v1/locations?include=district,locationGroups
JSON 
{
  "data": [
    {
      "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
      "external_id": "STR-1042",
      "name": "Downtown Austin",
      "city": "Austin",
      "region": "TX",
      "district": {
        "id": "3f2a1b0c-9d8e-4f7a-b6c5-d4e3f2a1b0c9",
        "name": "Central Texas",
        "external_id": "CTX"
      },
      "locationGroups": [
        { "id": "a3c5e7f9-2b4d-4f6a-8c1e-3d5f7a9b1c20", "name": "Austin Metro" }
      ]
    }
  ]
}

include also works on the single-record endpoints, such as GET /api/v1/locations/{id}.

What each collection accepts

Each collection allows its own fields. Asking for anything else returns 400 Bad Request naming the values it does accept.

Collection filter[...] sort (default first) include
/api/v1/locations external_id name, created_at, updated_at locationCategory, district, district2, locationGroups
/api/v1/location-groups external_id name, created_at, updated_at locations
/api/v1/districts external_id, district_group_id name, created_at, updated_at districtGroup
/api/v1/location-categories external_id, location_category_group_id sort_order, name, created_at, updated_at locationCategoryGroup
/api/v1/users email, perspective email, first_name, last_name, created_at, updated_at locationGroups, location

Putting it together

Pagination, filters, sorting and includes combine freely in one request:

Shell 
GET /api/v1/locations?include=district,locationGroups&filter[external_id]=STR-1042&sort=-created_at&page[size]=20

Tips

  • Ask for the largest page you can use (page[size]=100) when you read a whole collection; it means fewer requests against the rate limit.
  • Include only the relations you need: each one adds work to every row.
  • Cache reference data such as districts and categories on your side; it changes rarely.