Skip to main content
Some API requests will retrieve a large dataset. To ensure proper handling of this data, EmailBison will paginate the response. This essentially means that you will receive chunks, or pages, of the data. The response will be broken up into pages of 15 data entries per page, with information on how to view the next chunk. For example, a GET request at the endpoint /api/leads will always be paginated, as there could be thousands of entries in leads. Paginated responses from the API will have a data field for the entries at this page, as well as links and meta fields that provide you with information about the pagination in the response.
200
{
    "data": [
        {
            "id": 835910,
            "first_name": "John",
            "last_name": "Doe",
            "email": "JohnDoe@email.com",
        },
        {
            "id": 835898,
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "JaneDoe@email.com",
        },
		... +13 Leads
    ],
    "links": {
        "first": "https://dedi.emailbison.com/api/leads?page=1",
        "last": "https://dedi.emailbison.com/api/leads?page=4",
        "prev": null,
        "next": "https://dedi.emailbison.com/api/leads?page=2"
    },
	"meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 4,
		...Extra information truncated
	}
}

​
Retrieving the data programmatically

Send a request to your desired paginated endpoint. After processing the data received, you would then send a request to the endpoint provided at links.next in the response, if it is not null. Alternatively, you could loop the query by adding the page number as a paremeter for your request, incrementing the page number until you reach meta.last_page. This looks like YOUR_URL.com/api/leads?page={page_number}, where {page_number} is incremented by 1 each time until you reach meta.last_page.

​
Retrieving a specific page

Add a query paramter to the end of your request with the page number. This looks like YOUR_URL.com/api/leads?page={page_number}, where {page_number} is the page you would like to retrieve.

​
Cursor Pagination vs Default Page Pagination

The main difference between the two is that cursor pagination lets you traverse data much faster than the traditional page based pagination. If you or your team is requesting large amounts of data to loop through, we recommend using cursor pagination.
Traditional page based pagination is automatically limited to 1000 pages for all index routes (eg /api/leads, /api/replies, etc.). For larger datasets, use cursor pagination.

​
How does cursor pagination work?

When using cursor pagination, pass in an extra query parameter called pagination_type set to cursor. This will instruct the API to return the response with values for the next_cursor and prev_cursor. Think of a cursor as a “pointer,” where each dataset belongs to a cursor. To request the next page, your request will need to contain that page’s cursor.

​
Example

Request the first page of leads and set pagination_type to cursor: YOUR_URL.com/api/leads?pagination_type=cursor You’ll get your list of leads along with the following meta info: 
"meta": {
    "path": "https://dedi.emailbison.com/api/leads",
    "per_page": 15,
    "next_cursor": "eyJpZCI6NzQ1NjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null
}
To request the next page, pass the next_cursor value as the cursor query parameter: YOUR_URL.com/api/leads?pagination_type=cursor&cursor=eyJpZCI6NzQ1NjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0 That page will then return a meta object containing cursors for both the previous and next page: 
"meta": {
    "path": "https://dedi.emailbison.com/api/leads",
    "per_page": 15,
    "next_cursor": "eyJpZCI6NzQ1NDUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": "eyJpZCI6NzQ1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9"
}
Continue using the next_cursor value from each response as the cursor query parameter on your next request to traverse the full dataset.