Use Pagination with List APIs

If you are using one of the list APIs such as:

• List Conversations
• List Admins
• List Contacts
• List Companies
• List Articles

You may want to retrieve the data in smaller chunks to make processing more manageable or for performance reasons. You can do this using pagination. In this guide you will paginate over a list of contacts using Node.js.

Create Example Contacts

In an empty example.js file, write a for loop that will create 51 contacts in your workspace to use as an example.

for (let i = 0; i < 50; i++) {
    const resp = await fetch(
        `https://api.intercom.io/contacts`,
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Intercom-Version': '2.10',
            Authorization: 'Bearer <your-access-token>'
          },
          body: JSON.stringify({
            email: 'user_' + i + '@example.com'
          })
        }
      );
    
      const data = await resp.json();
      console.log(data.id);

}

Run node example.js in your terminal to run the script.

Now that you have some example contacts, you can delete this code from the file.

Fetch the Contacts

Let's say that you want to fetch 5 contacts at a time.

First you declare the url with the number of pages.

let url = 'https://api.intercom.io/contacts?per_page=5'

Then you can make the API call and do something with the data to verify that the correct number of responses is obtained — in this example, we are logging the contact email addresses. You can also log the pages object.

const resp = await fetch(
    url,
    {
      method: 'GET',
      headers: {
      'Intercom-Version': '2.10',
      Authorization: 'Bearer <your-access-token>'
    }
  });

  const data = await resp.json();
  console.log(data.pages)
  console.log(data.data.map((contact) => contact.email));

If you refer to what the pages object looks like in the response, you'll see that we can check to see if next is present. If so, it means there are more pages to come.

{
  "pages": {
    "type": "pages",
    "next": {
      "page": 11,
      "starting_after": "Wy0xLCI2NWU3NGYyYmY2ZGFhMTcwNTA1NTE1MGYiLDld"
    },
    "page": 10,
    "per_page": "5",
    "total_pages": 11
  },
}

Next, check to see if the pages object has the next property. This indicates that there is another page to fetch. You are going to wrap this in a while loop. When there is no more next property, you can break the loop and set the URL to null.

  if (!data.pages.next) {
    url = null;
    break;
  }

Finally, you get the starting_after cursor string from the object, and pass it into the URL.

url = url + `&starting_after=${data.pages.next.starting_after}`;

Full Code Example

Finally, create an async function and a while loop that checks if URL exists. This will ensure the requests will continue until there is no next property, which means there are no more pages to fetch. Your final code should look like the below.

async function run() {  
  let url = 'https://api.intercom.io/contacts?per_page=5'
    
  while(url) {
    const resp = await fetch(
    url,
    {
      method: 'GET',
      headers: {
      'Intercom-Version': '2.10',
      Authorization: 'Bearer <your-access-token>'
    }
  });

  const data = await resp.json();
  console.log(data.data.map((contact) => contact.email));
        
  if (!data.pages.next) {
    url = null;
    break;
  }
  
  url = url + `&starting_after=${data.pages.next.starting_after}`; 
  }
}

run();

Now run node example.js again to see how it works.

For more details on pagination see the pagination overview and for setting up pagination for search and sorting see the search and sorting guide.