Responses and pagination

Requests

Send GET parameters in the query string.
Send write parameters as form fields (application/x-www-form-urlencoded or multipart/form-data) or as a JSON body with Content-Type: application/json.
Arrays use brackets in form fields, for example additional_charges[]=3&additional_charges[]=8.

Response shapes

The API grew over many years, so responses do not all share one shape.
The endpoint reference shows the shape of each endpoint; these are the ones you will meet.

Shape	Example endpoints
Envelope: `success`, `status_code`, `errors` and the result in `data` (some endpoints use another key, such as `invoice`)	Single reservations, booking steps, fines, vehicles
Envelope with the pagination fields next to `data`	`GET /car-rental/reservations` (v1)
Envelope with the pagination object inside `data`	`GET /car-rental/fines`, v2 `GET /car-rental/reservations`, v2 `GET /car-rental/rates`
Pagination object without envelope	`GET /invoices/invoices`, `GET /contacts/categories/{category_id}/contacts`, `GET /fields`
Object keyed by the table name	`GET /fleets/locations` returns `{"fleets_locations": [...]}`
Single record keyed by the singular table name, without envelope	`GET /contacts/categories/{category_id}/contacts/{id}` returns `{"contact": {...}}`, `GET /car-rental/rates/{id}` returns `{"car_rental_rate": {...}}`
Plain array	`GET /car-rental/rates` (v1), `GET /car-rental/rate-types`

The standard envelope looks like this:

{
  "success": true,
  "status_code": 200,
  "errors": [],
  "data": { "id": 1234 }
}

Lists keyed by the table name return an empty array [] when there is nothing to return, not {"fleets_locations": []}.
Handle both forms.

Pagination

Paginated endpoints accept page (starting at 1) and limit (items per page).
The pagination object contains current_page, per_page, next_page_url and the items in data; most endpoints also return last_page and total.

{
  "current_page": 1,
  "data": [ { "id": 98 }, { "id": 97 } ],
  "last_page": 4,
  "per_page": 50,
  "next_page_url": "https://api.hqrentals.app/api/invoices/invoices?page=2",
  "total": 180
}

Repeat the same request with page increased by 1 until next_page_url is null.
Do not call next_page_url itself: it drops your other parameters, such as filters, updated_since and limit.

The default limit depends on the endpoint, for example:

Endpoints	Default `limit`
`GET /car-rental/reservations` (v1)	100, which is also the maximum
Contacts, contact categories, custom fields, files, form items (sheet items)	10
Payment methods	100
Most other paginated lists, including v2 endpoints, invoices and fines	50

GET /car-rental/rates (v1) is different: it returns a plain array of up to 1,000 rates per call, and its page starts at 0.
It has no pagination fields, so request page=0, 1, 2 and so on until a call returns fewer than 1,000 rates.

Requests#

Response shapes#

Pagination#

Requests

Response shapes

Pagination