Leads

Change a lead

PATCH/leads/{leadId}

Changes how a person is named and what Salesteam knows about them, with the same rules as the app: first and last name ({{first_name}}), the short company name ({{company_short}}), company, job title, email, custom fields, and tags to add or take off. Only the fields you send change; list a field in clear to empty it. Returns the lead.

Try itSend a real request with your API key

API key leadId path Body JSON

This changes your workspace, as the same change in the app would. Your key stays in this page and goes only to Salesteam.

Path

leadIdstringRequired
The lead.

Headers

Idempotency-Keystring
Any unique value up to 255 characters, like a UUID. The request runs once; repeats within 24 hours get the first answer, with Idempotent-Replayed: true. Up to 255 characters.

Body

firstNamestring or null
What {{first_name}} says. It can’t be emptied. Up to 100 characters.
lastNamestring or null
Up to 100 characters.
companystring or null
A new company resets companyShort to the automatic one, unless you send companyShort too. Up to 200 characters.
companyShortstring or null
The short company name {{company_short}} and {{company_name}} use, like “Acme” for “Acme Holdings, Inc.”. Clear it to go back to the automatic one. Up to 100 characters.
titlestring or null
Their job title. Up to 200 characters.
emailstring · email or null
The email Salesteam uses for them from now on. Up to 254 characters.
customFieldsobject or null
Values for the workspace's custom fields, by field key or name (service_word or Service word; see GET /custom-fields). A name the workspace doesn't have yet becomes a new field: a number makes a Number field, a list a Multi-select, anything else Text. Values are checked against the field's type: a URL needs a web address, a Number a number, a Date a date (saved as YYYY-MM-DD), and a choice that isn't an option yet is added. null removes a value; an empty string or an empty list leaves it as it is. Up to 50 per lead.
tagsobject or null
Tags to add (a new name becomes a workspace tag) and tags to take off, by name.
Inside it
- addarray of string or null
  Tag names (or IDs); one name can be a string. Up to 20.
- removearray of string or null
  Tag names (or IDs); one name can be a string. Up to 20.
cleararray of string or null
Fields to empty: lastName, company, companyShort (back to the automatic one), title or email. A cleared company or title shows what LinkedIn says, if anything.

Answer

200 OK The lead, changed.

dataLeadRequired
Inside it
- idstringRequired
- firstNamestringRequired
- lastNamestringRequired
- fullNamestringRequired
- titlestringRequired
- companystringRequired
- companyShortstringRequired
  What {{company_short}} (and {{company_name}}) say for this lead in messages: the short name set for them, or the company name cleaned up (no Inc., no tagline).
- companyShortSetbooleanRequired
  A short company name was set for this lead; false means the automatic one.
- locationstringRequired
- industrystringRequired
- linkedinUrlstringRequired
- emailstring or nullRequired
  A found email, when it is usable.
- emailStatusstring or nullRequired
  One of deliverable, catch_all, unknown.
- statusstringRequired
  One of new, queued, contacted, connected, replied, suppressed.
- stagestringRequired
  Where the person is, as the Leads table’s Stage column says it: Blacklisted or Do not contact (suppressed) first, then an outcome you recorded (interested, qualified, booked, attended, won, no_show, lost), then Interested or Not interested from tags and AI reply tags, else the automatic status (new, queued, contacted, connected, replied). One of new, queued, contacted, connected, replied, interested, qualified, booked, attended, won, not_interested, no_show, lost, suppressed, blacklisted.
- tagsarray of stringRequired
- customFieldsobjectRequired
  The lead's custom field values by field key: text, numbers, dates as YYYY-MM-DD, web addresses, and lists for Multi-select fields.
- listsarray of objectRequired
  Each item
  - idstringRequired
    The list's ID.
  - namestringRequired
    The list's name.
- fromPostobject or nullRequired
  The LinkedIn post this person liked or commented on when they were saved from it (Posts › Engagers), kept beside how they were first added. Null when they weren't saved from a post.
  Inside it
  - postUrlstringRequired
  - topicstring or nullRequired
    What the post was about, in the workspace's words: what {{post_topic}} says in messages.
  - interactionstringRequired
    One of like, comment.
  - commentstring or nullRequired
    Their comment, up to 300 characters.
  - yourPostbooleanRequired
    The post is one of the workspace's own.
  - engagedAtstring · date-timeRequired
  - savedAtstring · date-timeRequired
- createdAtstring · date-timeRequired
- updatedAtstring · date-timeRequired
  The last time anything about this person changed: their details, lists or tags, an email found, outreach or a reply. What updatedSince filters on.
- campaignsarray of LeadCampaignRequired
  Each item
  - campaignobjectRequired
    Inside it
    idstringRequired
    namestringRequired
    statusstringRequired
    draft: not launched. active: running. paused: stopped by the owner. completed: finished. One of draft, active, paused, completed.
  - statusstringRequired
    Where the person is in a campaign. One of active, waiting_for_acceptance, retrying, paused, needs_review, replied, suppressed, finished, stopped.
  - stepintegerRequired
    The step they are on, from 1.
  - stepsintegerRequired
  - senderobject or nullRequired
    The LinkedIn account reaching out.
    Inside it
    idstring
    namestring
  - connectionRequestSentAtstring · date-time or nullRequired
  - acceptedAtstring · date-time or nullRequired
  - lastContactedAtstring · date-time or nullRequired
  - messagesSentintegerRequired
  - repliedAtstring · date-time or nullRequired
  - finishedAtstring · date-time or nullRequired
  - nextStepAtstring · date-time or nullRequired
    When the next step is due, while active.
  - pausedReasonstring or nullRequired

Errors

400 Bad requestinvalid_request invalid_json duplicate_in_request
401 Unauthorizedunauthorized
404 Not foundnot_found not_in_campaign
409 Conflictconflict idempotency_in_progress workspace_busy campaign_finished campaign_without_list tag_limit lead_has_history campaign_not_launched campaign_cannot_resume ambiguous_email
413 Too largetoo_large
415 Wrong content typeunsupported_media_type
422 Can’t processidempotency_key_reused
429 Too many requestsrate_limited
500 Server errorserver_error

Every error has the same shape. See Errors.