API: Create Lead Endpoint

Martin Eckardt
Martin Eckardt Member Posts: 23 VERIFIED MEMBER
10 Comments 5 Up Votes

Hi there,

I just found the new API-Endpoint for Lead creation, which is great! We waited for this for quite some time. 

https://developers.pipedrive.com/docs/api/v1/#!/Leads/post_leads

There is just one issue:

Leads can only be created when the personId or organizationId is set. That makes the the use of the API with a contact form very difficult. We need to first create the person, wait for the response with the personId and then create the leads with the returned personId.

Another downside is, that the whole point of the leads inbox is to keep the data of pipedrive clean and not fill them invaluable data (too many irrelevant deals and person). When using the leads feature in the Pipedrive browser app, leads can be created without creating a person. However, we can still add contact information such as a name, telephone number and email to the lead.

When the lead looks promising, we can convert the contact information to a full person in the database with one click. This way our contact database keeps very clean. However, this is not possible when working with the API.

Please let us know if you plan on changing this. We would love an API Endpoint where we can create leads with contact information like in the webapp and convert them in persons when we think the person is valuable.

 

Tagged:
0
0 votes

· Last Updated -

Comments

  • Mike van der Valk
    Mike van der Valk Pipedrive Team Posts: 3,065 PIPEDRIVE TEAM
    2500 Comments Fourth Anniversary 100 Likes 5 Answers
    edited July 2020 #2

    Hi @Martin Eckardt 

    Thanks for sharing. We're finishing up some updates and were then going to announce the new Lead API endpoints. Regarding your additional comments. I've passed them on to our Leads team so they can take a serious look to see how we can make this best work for everyone. Thanks again for passing it along, this is super helpful!

  • Jakub Kadlubiec_2191
    Jakub Kadlubiec_2191 Posts: 6 VERIFIED MEMBER
    10 Comments Pipedrive Team
    edited February 2022 #3

    Hi @Martin Eckardt ,

    Requiring a person_id or organization_id is indeed a difference in behaviour between the UI and the API.

    We've conducted an extensive research with current users of Leads and found out that the current behaviour (in the UI) is not how the product should behave. The main issue is that now there are two databases of contact information in PD. One is in Contacts section and other in Leads. Contact information is a very valuable resource for our users and even if a Lead does not become a Deal, the contact information should not be lost in the Leads Inbox.

    Often the same person is contacted multiple times throughout a long period of time (couple of years perhaps) and the whole history should stay in one place so it can be accessed in the future. Our customers have processes for re-engaging with old contacts, etc.

    For that reason we are planning to change how Leads Inbox work and we will require a Lead to always be linked to a contact similarly as deals do and as our API requires now.

    Of course, this will require some usability changes from our side. We will make sure that adding a Lead+Contact is super simple and doesn't require any more information entering than now. Regarding keeping the contact database clean, we will make it simple to just show Contacts which aren't assigned to Leads.

    Regarding the technical difficulty:

    We need to first create the person, wait for the response with the personId and then create the leads with the returned personId.

    Yeah that's correct. Perhaps we should write a tutorial describing how this should be done, would it be helpful?

    So that's the plan for now, but of course we might always change it again if we learn something new. I appreciate that's not what you wanted to hear, but hopefully the reasoning makes sense.

  • Martin Eckardt
    Martin Eckardt Member Posts: 23 VERIFIED MEMBER
    10 Comments 5 Up Votes
    edited February 2022 #4

    Hey Guys,

    thanks a lot for taking the time to reply to my request with that much detail and insight. A Tutorial how to create a person first and then add a lead in the api reference would be great. 

    Keep up the good work. We are excited to see what’s going to come!

  • Jakub Kadlubiec_2191
    Jakub Kadlubiec_2191 Posts: 6 VERIFIED MEMBER
    10 Comments Pipedrive Team
    edited July 2020 #5

    Hey Guys,

    thanks a lot for taking the time to reply to my request with that much detail and insight. A Tutorial how to create a person first and then add a lead in the api reference would be great. 

    Keep up the good work. We are excited to see what’s going to come!

    Hey Martin,

    Thanks for the kind words! Alright, we will write a tutorial about that topic, I suspect more people will be interested in that. :)

  • Valentin Durand
    Valentin Durand Member Posts: 2 VERIFIED MEMBER
    edited February 2022 #6

    I share the same view as Martin: the purpose of <Leads> for us is to avoid the multiplication of 'poor' <Contacts>.

    Now let's take an example. Let's say I have different channels to generate Leads:

    • LinkedIn scrapping
    • Website directories
    • Purchased lists
    • etc...

    For these different sources, I will have incomplete datas (either an email, a phone number, maybe both, most likely Names written differently)

    The whole idea is to avoid creating x3 <Contacts> for the same person.

    If it stays in <Leads> it's fine. I add a <Contact> only when the data quality is high enough.

     

    Dont get me wrong: I like to have the option to automatically link my <Leads> to a contact when I use a very robust source. But I also want the flexibility to have gargabe leads that my Outbound SDR team can just power through.

  • Martin Eckardt
    Martin Eckardt Member Posts: 23 VERIFIED MEMBER
    10 Comments 5 Up Votes
    edited July 2020 #7

    Hey Guys,

    thanks a lot for taking the time to reply to my request with that much detail and insight. A Tutorial how to create a person first and then add a lead in the api reference would be great. 

    Keep up the good work. We are excited to see what’s going to come!

    Maybe even a shorthand api route where the lead and contact can be created in a single call. In some form providers it may be difficult to implement the two api calls 

  • Jakub Kadlubiec_2191
    Jakub Kadlubiec_2191 Posts: 6 VERIFIED MEMBER
    10 Comments Pipedrive Team
    edited July 2020 #8

    Hey Guys,

    thanks a lot for taking the time to reply to my request with that much detail and insight. A Tutorial how to create a person first and then add a lead in the api reference would be great. 

    Keep up the good work. We are excited to see what’s going to come!

    Creating multiple entities in one request would be technically simple to implement, but would go against REST principles, so we'd prefer to avoid it. At least for now. We will keep listening for feedback and if wee see that this is really needed, we can always reconsider it.

    Btw. currently the Leads endpoint behaves in the same way as Deals endpoint does. There you also need to manually create a Person or Organization first.

  • Michal Smetana
    Michal Smetana Pipedrive Team Posts: 5 PIPEDRIVE TEAM
    First Comment Pipedrive Team
    edited July 2020 #9

    I share the same view as Martin: the purpose of <Leads> for us is to avoid the multiplication of 'poor' <Contacts>.

    Now let's take an example. Let's say I have different channels to generate Leads:

    • LinkedIn scrapping
    • Website directories
    • Purchased lists
    • etc...

    For these different sources, I will have incomplete datas (either an email, a phone number, maybe both, most likely Names written differently)

    The whole idea is to avoid creating x3 <Contacts> for the same person.

    If it stays in <Leads> it's fine. I add a <Contact> only when the data quality is high enough.

     

    Dont get me wrong: I like to have the option to automatically link my <Leads> to a contact when I use a very robust source. But I also want the flexibility to have gargabe leads that my Outbound SDR team can just power through.

    Hi @Valentin

    While I understand where your need is coming from, as Jakub wrote in his extensive answer above, this change is a result of very extensive research we've done with our current users of leads. Once we'll do this change, we'll make sure that we'll automatically try to link the new leads to existing contacts if you already have them in your contact database but if it happens for some reason that contact is a duplicate, you always have the possibility to merge them but the main goal for us will always be one central contact database where all the data is stored in one place, not in multiple places, leading to data inconsistencies.

  • Valentin Durand
    Valentin Durand Member Posts: 2 VERIFIED MEMBER
    edited July 2020 #10

    I share the same view as Martin: the purpose of <Leads> for us is to avoid the multiplication of 'poor' <Contacts>.

    Now let's take an example. Let's say I have different channels to generate Leads:

    • LinkedIn scrapping
    • Website directories
    • Purchased lists
    • etc...

    For these different sources, I will have incomplete datas (either an email, a phone number, maybe both, most likely Names written differently)

    The whole idea is to avoid creating x3 <Contacts> for the same person.

    If it stays in <Leads> it's fine. I add a <Contact> only when the data quality is high enough.

     

    Dont get me wrong: I like to have the option to automatically link my <Leads> to a contact when I use a very robust source. But I also want the flexibility to have gargabe leads that my Outbound SDR team can just power through.

    the main goal for us will always be one central contact database where all the data is stored in one place, not in multiple places, leading to data inconsistencies

    We are aligned on the objective, but not the way to achieve it.

    For me forcing us to create tons of extremely 'poor' contacts , with lots of contacts in double/triple/xxx is going into the opposite direction.

    All I am saying is that it would be better to have the choice on how we want to manage our Leads contact details, based on each business specificities

  • Shlomo W
    Shlomo W Member Posts: 1 VERIFIED MEMBER
    edited June 2021 #11

    This 2 steps process for creating a lead makes it impossible for integrating Pipedrive with common web hook integration tools (i.e webhook.site, webhookrelay.com), which are unidirectional and does not support extracting data from a response and using it for subsequent calls.

     

  • Paper Moose
    Paper Moose Member Posts: 2 VERIFIED MEMBER
    edited October 2021 #12

    Hi @Martin Eckardt ,

    Requiring a person_id or organization_id is indeed a difference in behaviour between the UI and the API.

    We've conducted an extensive research with current users of Leads and found out that the current behaviour (in the UI) is not how the product should behave. The main issue is that now there are two databases of contact information in PD. One is in Contacts section and other in Leads. Contact information is a very valuable resource for our users and even if a Lead does not become a Deal, the contact information should not be lost in the Leads Inbox.

    Often the same person is contacted multiple times throughout a long period of time (couple of years perhaps) and the whole history should stay in one place so it can be accessed in the future. Our customers have processes for re-engaging with old contacts, etc.

    For that reason we are planning to change how Leads Inbox work and we will require a Lead to always be linked to a contact similarly as deals do and as our API requires now.

    Of course, this will require some usability changes from our side. We will make sure that adding a Lead+Contact is super simple and doesn't require any more information entering than now. Regarding keeping the contact database clean, we will make it simple to just show Contacts which aren't assigned to Leads.

    Regarding the technical difficulty:

    We need to first create the person, wait for the response with the personId and then create the leads with the returned personId.

    Yeah that's correct. Perhaps we should write a tutorial describing how this should be done, would it be helpful?

    So that's the plan for now, but of course we might always change it again if we learn something new. I appreciate that's not what you wanted to hear, but hopefully the reasoning makes sense.

    @Jakub Kadlubiec  a tutorial would be really helpful please! To me it's hard to escape the feeling I'm doing something wrong since the process feels quite involved compared to what I was hoping to create a simple contact form. I'm concerned about polluting my client's database if I don't correctly implement the API.

    I would also say as a suggestion that for my use case I was hoping there would simply be a "contact form" endpoint that would allow me to send across all the data and have PipeDrive figure out what to do with it, similar to how the UI version of the contact form works. My client has requested a custom form to fit into their website design better, so unfortunately I can't use the UI version. I appreciate something like that is probably pretty complicated to work for everyone, so not sure how realistic it is. It would be awesome to have a half-way point between the UI builder and having to do a totally custom setup using the API calls.

  • Jakub Kadlubiec_20023
    Jakub Kadlubiec_20023 Member Posts: 2 VERIFIED MEMBER
    edited October 2021 #13

    Hi @Martin Eckardt ,

    Requiring a person_id or organization_id is indeed a difference in behaviour between the UI and the API.

    We've conducted an extensive research with current users of Leads and found out that the current behaviour (in the UI) is not how the product should behave. The main issue is that now there are two databases of contact information in PD. One is in Contacts section and other in Leads. Contact information is a very valuable resource for our users and even if a Lead does not become a Deal, the contact information should not be lost in the Leads Inbox.

    Often the same person is contacted multiple times throughout a long period of time (couple of years perhaps) and the whole history should stay in one place so it can be accessed in the future. Our customers have processes for re-engaging with old contacts, etc.

    For that reason we are planning to change how Leads Inbox work and we will require a Lead to always be linked to a contact similarly as deals do and as our API requires now.

    Of course, this will require some usability changes from our side. We will make sure that adding a Lead+Contact is super simple and doesn't require any more information entering than now. Regarding keeping the contact database clean, we will make it simple to just show Contacts which aren't assigned to Leads.

    Regarding the technical difficulty:

    We need to first create the person, wait for the response with the personId and then create the leads with the returned personId.

    Yeah that's correct. Perhaps we should write a tutorial describing how this should be done, would it be helpful?

    So that's the plan for now, but of course we might always change it again if we learn something new. I appreciate that's not what you wanted to hear, but hopefully the reasoning makes sense.

    Hey @Paper Moose ,

    We wrote that tutorial a while ago: https://pipedrive.readme.io/docs/adding-a-lead

    It explains the basic concepts. It doesn't contain code samples, but it links to some other articles which include code: https://pipedrive.readme.io/docs/adding-an-organization.

    We are currently not planning to add a single endpoint to collect contact info. What information are you collecting from the contact form? It will help us to learn more about your use case and based on that we can perhaps reconsider that.

    If you need specific help with calling our endpoints, we are happy to assist here.