Pagination and links

Response envelope

Responses wrap their content in a data key. A single record is an object:

{
  "data": {
    "id": "39d247bc-eea2-4f8b-9322-f20f9832d76d",
    "name": "Downtown Office",
    "links": {
      "self": {"href": "https://platform.homecarepro.io/api/agency_offices/39d247bc-eea2-4f8b-9322-f20f9832d76d", "method": "GET"}
    }
  }
}

A list is an array, with pagination links alongside it:

{
  "data": [{"id": "39d247bc-eea2-4f8b-9322-f20f9832d76d", "name": "Downtown Office"}],
  "links": {
    "self": {"href": "https://platform.homecarepro.io/api/agency_offices?page=1", "method": "GET"},
    "next": {"href": "https://platform.homecarepro.io/api/agency_offices?page=2", "method": "GET"}
  }
}

Pagination

Lists return up to 100 records per page. Ask for a page with the page query parameter, starting at 1.

To read a whole list, start without page and follow links.next until a response has no next link. prev is absent on the first page. Lists don't include a total count.

Following next keeps any filters you applied, so you don't need to rebuild the URL.

📘

Follow the links; don't build them

We reserve the right to change the format of pagination links. Always follow the URLs in links rather than constructing page URLs yourself.

Links

Every record has a links object. Each key names a relation and each value is a link with an href and an HTTP method:

"links": {
  "self": {"href": "https://platform.homecarepro.io/api/tasks/c09e2b34-1faf-436e-a9e3-08f134ff2df9", "method": "GET"},
  "agency_member": {"href": "https://platform.homecarepro.io/api/agency_members/2d33762e-1260-4d14-9365-1a4442ec7a3b", "method": "GET"},
  "documents": [
    {"href": "https://platform.homecarepro.io/api/documents/a61fbb60-e3c3-42dc-bd2d-d96bfe7749cd", "method": "GET"}
  ]
}

A relation to many records, such as a task's documents, is a list of links and may be empty. self is always present.

When you follow a link, send your Authorization and X-Agency-Id headers as usual.

Embedding related records

Tasks can embed their member and agency, which saves a request per task. Add includes[] to the request:

GET /api/tasks?includes[]=agency_member

Each task then carries an agency_member object alongside its own fields. An unsupported includes[] value returns 422.

Filters

Some lists take filters as repeated query parameters. A record matches when its value equals any of the values you give.

For example, to list one new hire's incomplete tasks:

GET /api/tasks?filters[agency_member][id][]=2d33762e-1260-4d14-9365-1a4442ec7a3b&filters[task_assignment][status][]=incomplete