Update an existing lead
Update a lead. Only the fields you send are changed, and omitted fields keep their current values. addresses replaces all of the lead’s addresses.
Contacts: a contact in contacts with an id updates that existing contact, and one without an id is added to the lead. Existing contacts you don’t list are kept. To delete a contact, use the Contacts API.
Returns the updated lead.
Custom fields: set a custom field by setting custom.{custom_field_id} to its value, or to null to clear it, e.g.:
Custom fields you don’t send keep their values. For a custom field with accepts_multiple_values: true, pass the full list of values, or append .add or .remove to the key to add or remove a single value, e.g.:
See Custom Fields for more details.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Query parameters
Comma-separated list of fields to include in the response.
Request
Addresses of the lead, up to 100. Replaces all of the lead’s addresses: include its current addresses to keep them, or pass [] to remove them all.
Contacts to update or add, up to 300 in total. A contact with an id updates that existing contact, and one without an id is added. Existing contacts that aren’t listed are kept.
Free-text description of the lead.
Name of the lead, usually a company name, e.g. Bluth Company.
Label of the lead’s status, e.g. Potential, matched ignoring case. Using status_id instead is recommended, so renaming a status doesn’t break your integration. Pass either status or status_id, not both.
ID of the lead’s status, e.g. stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk. See Lead Statuses.
Website of the lead, e.g. https://www.example.com. https:// is added if the URL has no scheme.
Response
ID of the user who created the lead, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA, or null if no user created it
Free-text description of the lead, or null
The lead’s ID, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O
Name of the lead, usually a company name, or null if unnamed. See display_name.
The owning organization’s ID, e.g. orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
ID of the lead’s status, e.g. stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk
ID of the user who last updated the lead, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA, or null if the last update wasn’t made by a user
Website of the lead, e.g. https://close.com, or null if unset
IDs of the lead’s contacts, in the same order as contacts. Only returned when requested in _fields.
Display name of the lead’s first contact, followed by +N when the lead has N more contacts, e.g. Bruce Wayne +2. Empty if the lead has no contacts. Only returned when requested in _fields.
Name to display for the lead: the lead’s name if set, otherwise the name, first email address or first phone number (in international format) of the first contact that has one, then Untitled
Current time in the lead’s timezone, as an ISO 8601 timestamp without a UTC offset. The timezone comes from the lead’s first address, or else from its contacts’ timezones. Null if no timezone is known. Only returned when requested in _fields.
The lead’s first address on one line: the street lines, City, State Zip and the country name, separated by commas. Null if the lead has no address. Only returned when requested in _fields.
Short summary of the lead’s first address: City, State if both are set, otherwise the city, state, country name or postal code. Null if the lead has no address. Only returned when requested in _fields.
First email address of the first contact that has one, or null if no contact has an email address. Only returned when requested in _fields.
First phone number of the first contact that has one, or null if no contact has a phone number. Only returned when requested in _fields.
Label of the lead’s status, e.g. Potential
Incomplete tasks on the lead (_type lead), soonest due first. To list all of a lead’s tasks, including completed ones, use List Tasks with lead_id.
Contacts on the lead. Deprecated: use List Contacts with lead_id instead.
Opportunities on the lead. Deprecated: use List Opportunities with lead_id instead.