Pagination and filtering

You can paginate and filter all list requests using the same query format. For convenience, we’ve made sure all list-based endpoints return data with the same structure.

Pagination

We use two parameters for pagination:

take is the number of items the API returns. The default is 50 and the max is 100.
skip is the number of items the API skips. The default is 0.

So if you want to get the first 50 items of a list, you don’t need any parameters. If you need items from the 350th to the 425th, you’ll use take=75 and skip=350. Here’s an example with the customer list:

curl --request GET \
  --url 'https://api.hyperline.co/v1/customers?take=10&skip=10' \
  --header 'Authorization: Bearer <token>'

The API always returns a similarly shaped payload containing:

data the items you requested
meta the contextual information (total number of items, number selected…)

For instance for customers:

{
  "meta": {
    "total": 2,
    "taken": 2,
    "skipped": 0
  },
  "data": [
    {
      "id": "cus_3fhwCWcL0Rx5MQ"
      // other properties
    },
    {
      "id": "cus_9huL9ahn7KQqHo"
      // other properties
    }
  ]
}

Sorting

Some list endpoints support sorting results using the sort and order query parameters:

sort specifies the field to sort by (e.g., created_at, emitted_at)
order specifies the sort direction: asc (ascending) or desc (descending)

For example:

curl --request GET \
  --url 'https://api.hyperline.co/v1/invoices?sort=emitted_at&order=desc' \
  --header 'Authorization: Bearer <token>'

Not all list endpoints support sorting. Refer to each endpoint’s documentation to see which sort fields are available.

Filtering

Our API offers many filtering capabilities so you can always find what you’re looking for. Pass filters as query parameters using a common pattern. fieldName__operator=value For instance:

GET /v1/customers?name__contains=instagram returns all customers with the name containing instagram
GET /v1/customers?id__in=123,456,789 returns customers with ID equal to 123, 456, or 789

List of available operators

equals (or just <field>=xxx)
not
lt
lte
gt
gte
contains
startsWith
endsWith
in
notIn
isNull
isNotNull

You can apply numerical operators to numbers or dates.

You can’t filter on every field. Refer to each model in the API Reference to see which ones are available.

​Pagination

​Sorting

​Filtering

​List of available operators

Pagination

Sorting

Filtering

List of available operators