---
title: "Update a lead"
method: PATCH
path: "/leads/{identifier}"
tags: ["Leads"]
---

# Update a lead

`PATCH /leads/{identifier}`

## Request

- Base URL: `https://api.lassotech.com/api/v1/rest`
- URL: `https://api.lassotech.com/api/v1/rest/leads/{identifier}`
- Auth: API key in header `x-lasso-access-token`

Update a referral's details or move it to another status. Lookup by slug (default), id, email,
company_name, or external ID using the `?by=` query param. Requires `partners_edit`, and
`payment_write` as well when `remove_rewards` is `true`.

Only the fields you send are changed. Fields this endpoint does not list are ignored, with one
exception: `status` is refused with a `400`, because it is create-only. Use the `mark_as_*`
flags instead. Blank `company_name`, `contact_name` or `email` values are ignored.

### Status changes
**Only one status change can be requested per call**; sending two is a `422`. A change that is
not available from the referral's current status is a `422`
(`Cannot transition lead from <status> via <event>`). Marking an already `closed_lost` referral
as closed lost succeeds without doing anything, so a retry is safe.

| Flag | Allowed when the referral is |
|------|------------------------------|
| `mark_as_accepted` | `open`, `rejected`, `closed_lost` |
| `mark_as_qualified` | `open`, `accepted` |
| `mark_as_closed_won` | `accepted`, `qualified` |
| `mark_as_closed_lost` | any status except `closed_lost` (where it is a no-op) |
| `mark_as_rejected` | any status |
| `mark_as_churned` | `qualified`, `closed_won` |
| `mark_as_expired` | `open`, `accepted`, `qualified` |
| `mark_as_revived` (deprecated) | `rejected`, `churned`, `expired` |

`mark_as_revived` is deprecated and kept only for existing integrations; new integrations
should avoid it.

A `mark_as_*` flag, like `remove_rewards`, is on only when sent as `true` (or the string
`"true"`, `"1"` or `"yes"`, for form-encoded callers). Any other value, including `false`,
`"false"` and `"0"`, leaves it off and does not count toward the one-change limit.

### Removing rewards
`remove_rewards` removes every reward on the referral and voids their draft and payment-ready
invoices, so it requires `payment_write` in addition to `partners_edit`. A key without it gets
a `403` and nothing in the request is applied. If any reward has a finalized or paid invoice,
nothing in the request is applied and the call is a `422` with code `invoice_locked`, the same
refusal `DELETE /leads/{lead_identifier}/rewards/{id}` gives. Void or reverse those invoices
first.

### Reassigning the partner contact
Send one `partner_member_*` selector to attribute the referral to a different contact at the
same partner. Rewards already calculated keep paying the contact they were calculated for; the
response carries a `REWARD_ATTRIBUTION_UNCHANGED` warning when that is the case.

## Path parameters

- `identifier` string, required

## Query parameters

- `by` 'slug' | 'id' | 'email' | 'company_name' | 'external'
- `external_system_type` string
- `external_object_type` string

## Request body

- object
  - `mark_as_accepted` boolean
  - `mark_as_qualified` boolean
  - `mark_as_rejected` boolean
  - `mark_as_closed_won` boolean
  - `mark_as_closed_lost` boolean
  - `mark_as_churned` boolean
  - `mark_as_revived` boolean: Restores a rejected, churned or expired referral to whatever status it was in immediately beforehand, with no way to request a different target. Retained so existing integrations keep working; prefer an explicit status transition where one is available for your use case.
  - `mark_as_expired` boolean
  - `partner_member_slug` string: Attribute the referral to this partner contact, by Lasso Partner Contact Key. Slug wins over email, which wins over a CRM contact ID.
  - `partner_member_email` string, email: Attribute the referral to the partner contact with this email.
  - `partner_member_hubspot_contact_id` string: Attribute the referral to the partner contact linked to this HubSpot contact.
  - `partner_member_salesforce_contact_id` string: Attribute the referral to the partner contact linked to this Salesforce contact.
  - `partner_member_pipedrive_person_id` string: Attribute the referral to the partner contact linked to this Pipedrive person.
  - `expires_at` string, date-time, nullable: Lead expiration date. Set to null to clear.
  - `billing_start_date` string, date, nullable: Overrides the date this referral's billing starts from, which Lasso otherwise derives from your billing settings (for example the closed-won date or the date of the first revenue). Invoicing starts from the calendar month containing this date. Send null to go back to the derived date. Must be an ISO 8601 date; an invalid value is a `422` reported against `billing_start_date`.
  - `company_name` string
  - `contact_name` string
  - `email` string
  - `amount` number, float: Estimated deal amount
  - `expected_close_date` string, date
  - `co_sold` boolean: Mark as co-sold
  - `remove_rewards` boolean: Remove all rewards from the referral and void their draft and payment-ready invoices (typically used with `co_sold`). Requires `payment_write`. Refused with `invoice_locked` when any reward has a finalized or paid invoice. See Removing rewards above.
  - `internal_notes` string
  - `external_notes` string

## Response `200`

Lead updated

- object
  - `lead` Lead
    - `slug` string
    - `status` 'open' | 'accepted' | 'qualified' | 'closed_won' | 'closed_lost' | 'rejected' | 'churned' | 'expired'
    - `source_type` string, nullable
    - `company_name` string, nullable
    - `contact_name` string, nullable
    - `email` string, nullable
    - `partner_slug` string, nullable
    - `partner_lasso_key` string, nullable: The partner's Lasso Partner Key, the value to send back as `partner_lasso_key`.
    - `partner_member` object, nullable: The partner contact this referral is attributed to, if any.
      - `slug` string
      - `full_name` string, nullable
      - `email` string, nullable
    - `rewards` object[]: The rewards copied onto this referral from the partner's plan. Empty until the referral is accepted. `payee_type` says who each reward is owed to, so you can confirm a partner-contact reward actually landed rather than being skipped for want of a contact.
      - `name` string, nullable
      - `reward_type` string
      - `amount` string
      - `amount_type` string
      - `currency` string
      - `payee_type` 'partner' | 'partner_user'
    - `amount` string: Deal amount.
    - `currency_code` string
    - `expected_close_date` string, date, nullable
    - `co_sold` boolean
    - `deleted_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `billing_start_date` string, date: The date this referral's billing starts from, after any override is applied.
    - `billing_start_date_override` string, date, nullable: The override set with `billing_start_date` on update, or null when the date is derived from your billing settings.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `warnings` object[]: Non-fatal problems with a request that otherwise succeeded. The write happened, but something you asked for was not applied, or the referral will earn less than you may expect. Absent when there is nothing to report. Worth logging: these are the cases that are otherwise only visible as a missing commission weeks later. Messages are prefixed with a stable code: | Code | Returned by | Meaning | |------|-------------|---------| | `SKIPPED_REWARDS` | `POST /leads` (201) | Some rewards on the partner's plan pay the partner contact, and no contact was supplied, so those rewards were not applied. | | `STATUS_NOT_APPLIED` | `POST /leads` (201) | The referral was created, but the requested `status` could not be applied. It stays in the status the message names; finish with `PUT /leads/{identifier}`. | | `EXISTING_REFERRAL_NOT_UPDATED` | `POST /leads` (200) | A referral already carried the CRM record you sent and was returned unchanged. The message lists the fields from your request that were not applied. | | `REWARD_ATTRIBUTION_UNCHANGED` | `PATCH`/`PUT /leads/{identifier}` (200) | The referral was reassigned to another partner contact, but rewards already calculated still pay the previous contact. |
    - `field` string
    - `message` string

## Other responses

- `400`: `status` was sent; use the `mark_as_*` flags on update
- `401`: Missing or invalid API key
- `403`: API key lacks required permission
- `404`: Resource not found
- `422`: The update was refused and nothing was changed: two status changes in one call, a status change not available from the current status, `remove_rewards` on a referral with a finalized or paid invoice (`invoice_locked`), an invalid `billing_start_date`, or another validation error.
- `429`: Rate limit exceeded. Wait the number of seconds in `Retry-After`, then retry.

---

[API](https://skmtc.dev/onelasso/apis/lasso-rest-api.md) · [All operations](https://skmtc.dev/onelasso/apis/lasso-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onelasso/apis/lasso-rest-api/revisions/bbc328f5e2d1?raw)