Terminology
Lead - An individual who is a potential customer.
How does Pipedrive handle leads?
In Pipedrive, leads are potential deals stored in the Leads Inbox before they are archived or converted into a deal. Each lead needs to be named and linked to a person or organization.
Within Merge, these objects are mapped as follows:
Pipedrive Lead ←→ Merge Lead
Pipedrive Organization ←→ Merge Account
Pipedrive Person ←→ Merge Contact
If you would like to programmatically push leads to your end-users’ Pipedrive accounts, you can use the POST /leads endpoint from Merge’s Unified API!
When creating a new lead via the Pipedrive API, Pipedrive requires that a “lead always has to be linked to a person or an organization or both”. As these values are not a part of the standard Merge request body for posting a lead, we have added integration parameters to accept these values when you are using the POST /leads endpoint for Pipedrive.
Using POST /leads to push leads to Pipedrive
Get your linked account ID ready. This will be the linked account ID of the Pipedrive linked account you’d like to push this lead to and will be passed in via the
X-Account-Tokenheader.Set up your request body for the POST Lead endpoint.
You can pass in values for the title (required) and owner. Note that leads created through the Pipedrive API will have “API” assigned as the lead source, so this is not a writeable field.
Include values for your integration parameter(s).
There are two possible parameters you can pass in here:
organization_idandperson_id(these field names correspond to Pipedrive’s field names).Organization ID: This is the remote_id of the account you want to link this lead to.
Person ID: This is the remote_id of the contact you want to link this lead to.
These parameters are required! You can pass in values for both parameters, or just for one, but you must pass in a value for at least one of these parameters to meet Pipedrive’s POST Lead requirements.
To pass in values for these parameters: Include them under the
integration_paramsobject.You can also use the associated /meta endpoint to retrieve the field names for the possible integration parameters and to see which standard Merge fields are required.
You can use the following POST /leads request body as a template:
{
"model": {
"owner": "3e16e372-5f25-44a0-ae27-eef089eb7154",
"title": "Co-Founder",
"integration_params": {
"organization_id": 1,
"person_id": 1
}
}
}
Send a POST request to this endpoint:
https://api.merge.dev/api/crm/v1/leads
What about addresses, phone numbers, and email addresses?
Pipedrive attaches addresses, phone numbers, and email addresses to leads based on the organization or person they are linked to.
Therefore, you will not have to pass in addresses, phone numbers, and email addresses in your POST /leads request body. Upon successfully creating a lead, you will see addresses, phone numbers, and email addresses (if available) returned in the response body. These will be mapped from the related contact/account/both.