Adding a Lead

In the sales world, Leads are potential Deals that are stored separately in the Leads Inbox within Pipedrive.

The Leads resource allows you to get, create, update, and delete Leads, Lead Labels, and get Lead Sources.

In the API requests, each Lead needs to be named (using the title field) and be linked to either a Person or an Organization. Linking to either a Person or an Organization is required in order to keep all the information regarding Contacts in one part of Pipedrive, instead of separating it between Contacts and Leads Inbox, as it is crucial information in sales peoples' daily work. In this way, all communication between the salesperson and the contact can be found in one place (Person or Organization detail view in Pipedrive) throughout the entire sales cycle.

Leads can contain the same custom fields as the custom fields of a Deal. If the value of a custom field has been set for a Lead, it will appear in the response of the request.

Authentication

First, you need to think about how you authenticate your request to our API. For that, you can either use API token or OAuth 2.0. More information about authenticating your requests, see Authentication.

Adding a new Lead

As all Leads need to be linked with either a Person or an Organization, you’ll need to include the necessary parameters in the request (either person_id or organization_id). The Person or Organization you want to connect the Lead to needs to be created before the Lead. You can follow this step-by-step guide to learn how to create an Organization.

📘

All POST and PATCH requests to Leads endpoints must have content_type: application/json.

For easier use of making requests, find out how to use Pipedrive API with Postman or Insomnia.

You can use the following JSON example to add a new Lead. Don't forget to authenticate your request and add your own values to the JSON structure.

URL

For authentication with api_token:
Replace companydomain and apitoken with your own values

https://{COMPANYDOMAIN}.pipedrive.com/v1/leads?api_token=APITOKEN

For authentication with OAuth 2.0:

https://{COMPANYDOMAIN}.pipedrive.com/api/v1/leads

Request body

{
  "title": "Slack lead",
  "person_id": 33
}

//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 addLead() {
    try {
        console.log('Sending request...');

        const api = new pipedrive.LeadsApi(defaultClient);

        const data = {
            title: 'Lead 158',
            value: {
                amount: 3000,
                currency: 'USD'
            },
            owner_id: 13293848,
            label_ids: [
                'f981d20f-cd00-4e30-a406-06576a92058b'
            ],
            person_id: 1,
            organization_id: 1,
            expected_close_date: '2022-07-12',
            visible_to: '1',
            was_seen: true
        }
        const response = await api.addLead(data);

        console.log('Lead was added successfully!', response);
    } catch (err) {
        const errorToLog = err.context?.body || err;

        console.log('Adding a lead failed', errorToLog);
    }
}


addLead();