Pipedrive API Documentation

Pipedrive's API Docs

Welcome to Pipedrive's Developer Documentation. Here you'll find comprehensive guides and documentation to help you start working with Pipedrive's API, as well as the Changelog to see any relevant changes regarding the public API.

Merging two Persons

Have a sudden urge to merge two Persons together, but don't know how to do it? No worries, you've come to the right place to solve your problem.

Only want to see the finished code? No problem! You can find it below.

You can also try out merging two Persons by using the PUT /persons/{id}/merge endpoint from our API Reference.

How to make sure you're merging the right Person?

When merging, you'll want to pay attention to which Person you want to be merged with (conflicting data is kept) and which Person will be merged (conflicting data is removed). While the terminology may seem similar, knowing which Person has priority and which Person will be removed is very important.

The ID of Person you want to be merged with will give value to the merge_with_id parameter. This Person will have priority over the other Person and its data will be kept.

The ID of the Person that will be merged will be added to the target URL. This Person will be removed from your Pipedrive account and any conflicting data will be lost.

What if both Persons have data in the same field?

If both Persons have data in the same field, the Person of merge_with_id will be considered more important as its field data will remain unchanged, but the other Person's field data will be lost. If the Person of merge_with_id has empty fields, but the other Person has content in them, it will be added to the Person of merge_with_id.

Regardless of field conflicts, all related data (activities, emails, filters, notes, products, followers, participants) will be transferred and stored.

Continue with the step by step tutorial:

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 mergeTwoPersons.php and first give value to $api_token and $company_domain variables:

<?php
// Content of mergeTwoPersons.php
 
// Pipedrive API token
$api_token = 'Your API token goes here';
 
// Pipedrive company domain
$company_domain = 'Your company domain goes here';

Step 2: Prepare the data

When merging two Persons, there's one required parameter you have to give value to in the request body:

  • merge_with_id - the ID of the Person, which will remain in your Pipedrive account and is merged with the other Person (conflicting data is kept)

To send the required parameter with your chosen value for the merging, you need to create an array with this parameter:

// ID of the Person which will remain in your Pipedrive account and is merged with the other Person
$person = array(
  'merge_with_id' => 'ID of the Person that remains in your PD account and is merged with the other Person',
);

Step 3: Define target URL

To make a request, you'll need the correct URL meant for merging Persons. All available endpoints and their URLs are described in our API Reference. You must provide the API token as part of the query string for all requests at the end of the URL, an example would look like this https://companydomain.pipedrive.com/api/v1/persons/190/merge?api_token=659c9fddb16335e48cc67114694b52074e812e03

In the URL you're using for merging two Persons, you need to specify which Person is going to be merged and eventually not be visible.

Here are the ways you can find the person_id:

  • go to Contacts > People and click on the Person in the pipeline and find the ID at the end of the URL
  • fetch all Persons using the API via GET /persons (no need to use any parameters)

Now you need to insert the ID of the Person (that will be merged) instead of the placeholder of {id}:

// Specify the Person you want to be merged by inserting it's ID instead of {id}
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/persons/{id}/merge?api_token=' . $api_token;

Step 4: Make a PUT request

This part of the code is more complex, and you don’t need to understand it right away, all you need to know is that it contains everything to make a PUT request with your data against our API. To make the request, simply copy and paste this:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($person));
  
echo 'Sending request...' . PHP_EOL;
  
$output = curl_exec($ch);
curl_close($ch);

Step 5: Check the result

$output variable holds the full response you get back from the server. As a reminder, all responses from us are in JSON format, the first thing you'll want to do is to convert it into a proper PHP array:

// 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);

After that, you should check if the request was successful. One way to do it is to check the success property of the response. If it's true, then it means the Persons were merged successfully:

// Check if the merging was successful.
// If it did, print out the name of the Person the two Persons are now merged into
if ($result['success'] === true) {
  echo 'Persons are now merged into a Person named '
    . $result['data']['name'] . ' (Person ID: ' . $result['data']['id'] . ')' . PHP_EOL;
}

Full working example

Copy the full working example into mergeTwoPersons.php:

<?php
// Content of mergeTwoPersons.php
 
// Pipedrive API token
$api_token = 'Your API token goes here';
 
// Pipedrive company domain
$company_domain = 'Your company domain goes here';
 
// ID of the Person which will remain in your Pipedrive account and is merged with the other Person
$person = array(
  'merge_with_id' => 'ID of the Person that remains in your PD account and is merged with the other Person',
);
 
// Specify the Person you want to be merged by inserting it's ID instead of {id}
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/persons/{id}/merge?api_token=' . $api_token;
 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($person));
  
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);
 
// Check if the merging was successful
// If it did, then print out the name of the Person the two Persons are now merged into
if ($result['success'] === true) {
  echo 'Persons are now merged into a Person named '
    . $result['data']['name'] . ' (Person ID: ' . $result['data']['id'] . ')' . PHP_EOL;
}

Execute the code

Now run the command php mergeTwoPersons.php in terminal and you should see the following output:

$ php mergeTwoPersons.php
Sending request...
Persons are now merged into a Person named {Person name} (Person ID: {person_id})

Updated about a month ago

Merging two Persons


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.