PIpipedrive
Leads

Update a lead

Changed on

Updates one or more properties of a lead. Only properties included in the request will be updated. Send null to unset a property (applicable for example for value, person_id or organization_id). If a lead contains custom fields, the fields' values will be included in the response in the same format as with the Deals endpoints. If a custom field's value hasn't been set for the lead, it won't appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields’ structure from deals. See an example given in the <a href="https://pipedrive.readme.io/docs/updating-custom-field-value" target="_blank" rel="noopener noreferrer">updating custom fields’ values tutorial</a>.

patch/leads/{id}

Request

  • Base URL
    https://api.pipedrive.com/v1
  • Auth
    • API key in header x-api-token
    • or OAuth 2
      Authorization code: https://oauth.pipedrive.com/oauth/authorize
      Token URL: https://oauth.pipedrive.com/oauth/token scopes: leads:full

Path parameters

idstring uuid required

The ID of the lead

Request body

titlestring nullable

The name of the lead

owner_idinteger

The ID of the user which will be the owner of the created lead. If not provided, the user making the request will be used.

label_idsstring[]

The IDs of the lead labels which will be associated with the lead

person_idinteger nullable

The ID of a person which this lead will be linked to. If the person does not exist yet, it needs to be created first. A lead always has to be linked to a person or organization or both.

organization_idinteger nullable

The ID of an organization which this lead will be linked to. If the organization does not exist yet, it needs to be created first. A lead always has to be linked to a person or organization or both.

is_archivedboolean

A flag indicating whether the lead is archived or not

archive_reasonstring nullable

The reason for archiving the lead. Can only be provided when is_archived is being set to true in the same request, or when updating a lead that's already archived — providing it otherwise will return a 400 error. Automatically cleared when the lead is unarchived. If archiving with a reason is required for your company, archiving a lead without providing one will also return a 400 error.

expected_close_datestring date nullable

The date of when the deal which will be created from the lead is expected to be closed. In ISO 8601 format: YYYY-MM-DD.

visible_to'1' | '3' | '5' | '7'

The visibility of the lead. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups <a href="https://support.pipedrive.com/en/article/visibility-groups" target="_blank" rel="noopener noreferrer">here</a>.<h4>Light / Growth and Professional plans</h4><table><tr><th style="width: 40px">Value</th><th>Description</th></tr><tr><td>1</td><td>Owner & followers</td><tr><td>3</td><td>Entire company</td></tr></table><h4>Premium / Ultimate plan</h4><table><tr><th style="width: 40px">Value</th><th>Description</th></tr><tr><td>1</td><td>Owner only</td><tr><td>3</td><td>Owner's visibility group</td></tr><tr><td>5</td><td>Owner's visibility group and sub-groups</td></tr><tr><td>7</td><td>Entire company</td></tr></table>

was_seenboolean

A flag indicating whether the lead was seen by someone in the Pipedrive UI

channelinteger nullable

The ID of Marketing channel this lead was created from. Provided value must be one of the channels configured for your company which you can fetch with <a href="https://developers.pipedrive.com/docs/api/v1/DealFields#getDealField" target="_blank" rel="noopener noreferrer">GET /v1/dealFields</a>.

channel_idstring nullable

The optional ID to further distinguish the Marketing channel.

Response

Successful response containing payload in the data field

successboolean

Changes

  • e28596d02774Revision changes
    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

  • 24d2d929aac3Revision changes
    • info

      added the optional property / to the response with the status