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.

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.


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 authentication your request and add your own values to the JSON structure.


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


For authentication with OAuth 2.0:


Request body

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

Updated 5 months ago

Adding a Lead

Suggested Edits are limited on API Reference Pages

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