Skip to main content
Talk to salesStart

Update lead

Update an existing lead by ID with automatic company re-matching.

PUT/api/leads/{lead_id}
HTTP referenceScope leads:writeUpdated April 25, 2026

This page documents the canonical HTTP contract for this endpoint.

This is an open object at the HTTP boundary, but the handler allows only the writable fields listed above. Contact fields (email, email_addresses, phone_numbers, primary_phone) are rejected; use POST /api/leads/{lead_id}/contact-channels. Activity summary fields are read-only, and unknown fields or invalid status return 400. The returned Lead is normalized and may include populated company and priority data.

Path parameters

  • lead_idrequired

    string

    Lead ID.

Body parameters

  • first_name · optional

    string

    Updated first name.

  • last_name · optional

    string

    Updated last name.

  • company_domain · optional

    string

    Updated company domain (triggers company re-matching).

  • linkedin_url · optional

    string

    Updated LinkedIn profile URL.

  • linkedin_member_id · optional

    string

    LinkedIn member identifier.

  • linkedin_sales_url · optional

    string

    LinkedIn Sales URL.

  • company_id · optional

    string

    Company record ID.

  • company_name · optional

    string

    Company name.

  • company_linkedin_url · optional

    string

    Company LinkedIn URL.

  • location · optional

    string

    Location.

  • city · optional

    string

    City.

  • state · optional

    string

    State.

  • country · optional

    string

    Country.

  • zip_code · optional

    string

    Postal code.

  • timezone · optional

    string

    Time zone.

  • notes · optional

    string

    Lead notes.

  • title · optional

    string

    Updated job title.

  • lead_status · optional

    string

    Updated status; valid values: new, qualified, contacting, converted, customer, unqualified, bad_data, nurture.

  • user_id · optional

    string

    Optional owner user ID field.

  • next_activity_at · optional

    string

    Next activity timestamp.

  • note · optional

    string

    Optional status transition note.

  • unqualified_reason · optional

    string

    Optional reason for unqualified status.

  • unqualifiedReason · optional

    string

    Accepted alias for unqualified_reason.

  • lead_status_reason · optional

    string

    Optional lead status reason.

  • leadStatusReason · optional

    string

    Accepted alias for lead_status_reason.

  • status_reason · optional

    string

    Accepted status reason alias.

  • statusReason · optional

    string

    Accepted status reason alias.

Errors

StatusMeaning
400Invalid update payload.
401Invalid API key or missing auth.
403Missing leads:write scope.
404Lead not found.

Docs