Paging Through API Responses

Finix's API supports listing resources such as Transfer and Identities. Querying through these collections of resources relies on offset or cursor-based pagination. The pagination that's used depends on what version of Finix's API your request uses.

Offset Pagination

By default Finix's API uses offset pagination to return results.

Old

curl "https://finix.sandbox-payments-api.com/transfers?limit=20" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Example Response

{
  "_embedded": {
    "transfers": [...] // The list of resources
  },
  "_links": {...},
    "page": {
        "offset": 0,
        "limit": 20,
        "count": 1241393
    }
}

Offset pagination is limited to returning 10k results per request.

Cursor Pagination

Finix introduced cursor-based pagination based pagination in version 2022-02-01 of our API.

For details on how to migrate to cursor-based pagination, see How Do I Migrate to Cursor Pagination?

When you query for a list, you provide the number of entries you want with limit. Finix returns back a page of results per the limit you specified, as well as a next_cursor. This cursor is an opaque string that points to the end of the current page of results.

Current

curl "https://finix.sandbox-payments-api.com/transfers?limit=10" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

The response looks like:

{
  "_embedded": {
    "transfers": [...] // The list of resources
  },
  "_links": {...},
  "page" : {
    "limit" : 10,
    "next_cursor" : "TRnasXQ5AmjsLnPMwnme7TL4"
  }
}

By default, Finix returns resources ordered by their creation date.

Use next_cursor to get the next set of results by either providing the cursor value in after_cursor to page forward or before_cursor to page backwards.

For instructions on how to switch your requests to cursor-based pagination, see Migrating to Cursor Pagination.

Page Forward

To page forward, provide the next_cursor value in after_cursor. This gives you the next set of results after the cursor:

curl "https://finix.sandbox-payments-api.com/transfers?limit=10&after_cursor=TRnasXQ5AmjsLnPMwnme7TL4" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

{
  "_embedded": {
    "transfers": [...] // The next set of resources
  },
  "_links": {...},
  "page" : {
    "limit" : 10,
    "next_cursor" : "TR5F6tQgR37LAN48hHiA4Mj6"
  }
}

You can continue to take the nextcursor and provide it in aftercursor to keep paging forward.

Page Backward

To page backward, provide the next_cursor value in before_cursor. This gives you the next set of results before the cursor:

curl "https://finix.sandbox-payments-api.com/transfers?limit=10&before_cursor=TRnasXQ5AmjsLnPMwnme7TL4" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

{
  "_embedded": {
    "transfers": [...] // The previous set of resources
  },
  "_links": {...},
  "page" : {
    "limit" : 10,
    "next_cursor" : "TR5F6tQgR37LAN48hHiA4Mj6"
  }
}

The next_cursor is now pointing backwards. Take the next_cursor value and provide it as before_cursor in the next query to keep paging backward.

End of Results

If the next_cursor value is null, then there are no more resources to return for the current query.