Paging Through API Responses

Finix's API supports listing resources such as Transfer and Identities. Querying through these collections of resources relies on cursor-based pagination.

When you query for a list, you provide the number of entries you want by 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.

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.