Using Pagination to retrieve all Deal titles

You've learned from our Pipedrive API Documentation that the pagination max limit value is 500. So what do you do when your amount of Deals exceeds this 500 limit?

One way to solve your problem is to define a reusable function which can be used recursively to retrieve all Deals page-by-page without writing the same code (making a request, getting a response, checking if another request is needed, and then repeating it) over and over again. The comments inside the code blocks will help you if needed.

Only want to see the finished code for getting titles of all Deals? No problem, you can find it below!

Step 1: Get your API token and company domain

Follow our tutorials on how to find the API token and how to get the company domain.

Then create a file getAllDealTitles.php and give value to all three constants:

<?php
// Content of getAllDealTitles.php
  
// Insert your Pipedrive API token
const API_TOKEN = 'Your API token goes here';
 
// Insert your Pipedrive company domain
const COMPANY_DOMAIN = 'Your company domain goes here';
 
// Insert number of Deals per page you want to retrieve (cannot exceed 500 due to the pagination limit)
const DEALS_PER_PAGE = 10;

Step 2: Define a function

Follow the comments inside the code sample:

/**
 * @param int $limit Items shown per page (how many Deals retrieved per request, you can change this number)
 * @param int $start Pagination start (how many Deals will be skipped from the beginning of the full deal list)
 * @return array
 */
function getDeals($limit = DEALS_PER_PAGE, $start = 0) {
    echo "Getting Deals, limit: $limit, start: $start"  . PHP_EOL;
 
    // Here's the URL you're sending this request to
    $url = 'https://' . COMPANY_DOMAIN . '.pipedrive.com/api/v1/deals?api_token='
        . API_TOKEN . '&start=' . $start . '&limit=' . $limit;
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      
    echo 'Sending request...' . PHP_EOL;
      
    $output = curl_exec($ch);
    curl_close($ch);
      
    // Create an array from the data that is sent back from the API
    // As the original content from server is in JSON format, you need to convert it to PHP array
    $result = json_decode($output, true);
    $deals = [];
 
    // If the result is not empty, then add each Deal into the Deals array
    if (!empty($result['data'])) {
        foreach ($result['data'] as $deal) {
            $deals[] = $deal;
        }
    } else {
        // If you have no Deals in your company, then print out the whole response
        print_r($result);
    }
 
    // If the value of 'more_items_in_collection' is true, then the function calls itself
    // with an increased value for the 'start' parameter (retrieved from the previous request response)
    if (!empty($result['additional_data']['pagination']['more_items_in_collection'] 
        && $result['additional_data']['pagination']['more_items_in_collection'] === true)
    ) {
        // Merges Deals found from the current request with the ones from the next request
        $deals = array_merge($deals, getDeals($limit, $result['additional_data']['pagination']['next_start']));
    }
    return $deals;
}

Step 3: Call the defined function

// Call the function
$deals = getDeals();

Step 4: Display the result

Print out the number of Deals found and iterate over all of them. Then continue printing out the Deal title with its ID:

// Print out the number of Deals found
echo 'Found '.count($deals).' deals' . PHP_EOL;
 
// Iterate over all found Deals
foreach ($deals as $key => $deal) {
    // Print out a deal title with its ID
    echo '#' . ($key + 1) . ' ' .  $deal['title'] . ' ' . '(Deal ID:'. $deal['id'] . ')' . PHP_EOL;  
}

Full working example

Copy the full working example into getAllDealTitles.php:

<?php
// Content of getAllDealTitles.php
  
// Insert your Pipedrive API token
const API_TOKEN = 'Your API token goes here';
 
// Insert your Pipedrive company domain
const COMPANY_DOMAIN = 'Your company domain goes here';
 
// Insert number of Deals per page you want to retrieve (cannot exceed 500 due to the pagination limit)
const DEALS_PER_PAGE = 10;
 
/**
 * @param int $limit Items shown per page (how many Deals retrieved per request, you can change this number)
 * @param int $start Pagination start (how many Deals will be skipped from the beginning of the full Deal list)
 * @return array
 */
function getDeals($limit = DEALS_PER_PAGE, $start = 0) {
    echo "Getting Deals, limit: $limit, start: $start"  . PHP_EOL;
 
    // Here's the URL you're sending this request to
    $url = 'https://' . COMPANY_DOMAIN . '.pipedrive.com/api/v1/deals?api_token='
        . API_TOKEN . '&start=' . $start . '&limit=' . $limit;
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      
    echo 'Sending request...' . PHP_EOL;
      
    $output = curl_exec($ch);
    curl_close($ch);
      
    // Create an array from the data that is sent back from the API
    // As the original content from server is in JSON format, you need to convert it to PHP array
    $result = json_decode($output, true);
    $deals = [];
 
    // If the result is not empty, then add each Deal into the Deals array
    if (!empty($result['data'])) {
        foreach ($result['data'] as $deal) {
            $deals[] = $deal;
        }
    } else {
        // If you have no Deals in your company, then print out the whole response
        print_r($result);
    }
 
    // If the value of 'more_items_in_collection' is true, then the function calls itself
    // with an increased value for the 'start' parameter (retrieved from the previous request response)
    if (!empty($result['additional_data']['pagination']['more_items_in_collection'] 
        && $result['additional_data']['pagination']['more_items_in_collection'] === true)
    ) {
        // Merges Deals found from the current request with the ones from the next request
        $deals = array_merge($deals, getDeals($limit, $result['additional_data']['pagination']['next_start']));
    }
    return $deals;
}
 
// Call the function
$deals = getDeals();
 
// Print out the number of Deals found
echo 'Found '.count($deals).' deals' . PHP_EOL;
 
// Iterate over all found Deals
foreach ($deals as $key => $deal) {
    // Print out a Deal title with its ID
    echo '#' . ($key + 1) . ' ' .  $deal['title'] . ' ' . '(Deal ID:'. $deal['id'] . ')' . PHP_EOL;  
}

//All tutorial Node.Js code examples are for reference only and shouldn’t be used in production code as is. In production, a new new pipedrive.ApiClient() instance should be initialised separately for each request.
const pipedrive = require('pipedrive');
const defaultClient = new pipedrive.ApiClient();

// Configure authorization by settings api key
// PIPEDRIVE_API_KEY is an environment variable that holds real api key
defaultClient.authentications.api_key.apiKey = process.env.PIPEDRIVE_API_KEY;

async function getDealsWithPagination() {
    try {
        console.log('Sending request...');

        const api = new pipedrive.DealsApi(defaultClient);

        const data = {
            start: 5, //Items shown per page (how many Deals retrieved per request, you can change this number)
            limit: 20, // Pagination start (how many Deals will be skipped from the beginning of the full Deal list)
        }
        const response = await api.getDeals(data);

        console.log('Got deals with pagination successfully!', response);
    } catch (err) {
        const errorToLog = err.context?.body || err;

        console.log('getting deals with pagination failed', errorToLog);
    }
}

getDealsWithPagination();

Execute the code

Use php getAllDealTitles.php command to execute the code in the command line.

In my example below, I have 21 Deals and this is the output I get:

$ php getAllDealTitles.php
Getting deals, limit: 10, start: 0
Sending request...
Getting deals, limit: 10, start: 10
Sending request...
Getting deals, limit: 10, start: 20
Found 21 deals with titles:
#1 Batman deal (Deal ID:134)
#2 Big apple sale (Deal ID:135)
#3 Robin sale (Deal ID:136)
#4 Silly goose (Deal ID:137)
#5 Mademoiselle sale (Deal ID:138)
#6 Cats and dogs (Deal ID:139)
#7 Panna on vaja (Deal ID:140)
#8 Lucky (Deal ID:141)
#9 Call him now (Deal ID:142)
#10 Sending (Deal ID:143)
#11 Wolt (Deal ID:144)
#12 PD (Deal ID:145)
#13 The Explorer (Deal ID:146)
#14 The Carryall (Deal ID:147)
#15 The Pineapple (Deal ID:148)
#16 The Base (Deal ID:149)
#17 Kisser (Deal ID:150)
#18 Hugger (Deal ID:151)
#19 The Scholar (Deal ID:152)
#20 The Artist (Deal ID:153)
#21 The Ace (Deal ID:154)