> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenpartner.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a lead

> Update standard fields and custom property values on an existing lead.

import ApiAuth from "/_snippets/api-auth.mdx";

Use this action to update standard fields and/or custom property values on a lead in a channel your API key can access.

## Authentication

<ApiAuth />

The API key's company must have access to the lead's channel. Access is granted when your company is part of the channel as creator, partner, referring company, or receiving company.

## Request

<ParamField body="action" type="string" required>
  Must be `"update_lead"`.
</ParamField>

<ParamField body="lead_id" type="uuid" required>
  The lead's UUID. If you only have the legacy integer ID, use
  [`get_lead_by_legacy_id`](/api-reference/get-lead-by-legacy-id) to resolve it
  first.
</ParamField>

<ParamField body="email" type="string">
  Contact email address.
</ParamField>

<ParamField body="first_name" type="string">
  First name of the contact.
</ParamField>

<ParamField body="last_name" type="string">
  Last name of the contact.
</ParamField>

<ParamField body="phone" type="string">
  Phone number.
</ParamField>

<ParamField body="company_name" type="string">
  Company name of the lead.
</ParamField>

<ParamField body="source" type="string">
  How the lead was sourced (e.g. `"Website"`, `"Referral"`).
</ParamField>

<ParamField body="referring_employee" type="string">
  Employee at the referring company who submitted the lead.
</ParamField>

<ParamField body="notes" type="string">
  Free-text notes about the lead.
</ParamField>

<ParamField body="business_id" type="string">
  The business' ID in the company register or an external identifier from your
  own system.
</ParamField>

<ParamField body="properties" type="array">
  Custom property values to upsert on the lead. Each entry requires a `property_definitions_id` and a `value`. Use [`get_channels`](/api-reference/get-channels) to retrieve the property definitions available on the lead's channel.

  ```json theme={null}
  [
    {
      "property_definitions_id": "019dc3f6-1790-7298-932b-90a7ee4ba10c",
      "value": "High interest"
    }
  ]
  ```
</ParamField>

Each `properties` entry has the following fields:

* `property_definitions_id` (uuid, required): Must reference an active property definition on the same channel as the lead.
* `value` (string, number, boolean, or object, required): Stored as text. Numbers and booleans are stringified. Objects and arrays are JSON-serialized. `null` and `undefined` are not allowed.

<Note>
  At least one standard field or a non-empty `properties` array is required.
</Note>

## Behavior

* **Upsert semantics**: If a value already exists for the same lead and property definition, it is updated in place. Otherwise a new value is created.
* **Partial updates**: Standard fields you don't include are left unchanged.
* **No side effects**: This action is a pure data edit. It does not trigger new-lead rewards, status-change rewards, webhooks, notifications, or workflows.

## Response

Returns the full updated lead, including its status and all custom property values.

<ResponseField name="lead" type="object">
  <Expandable title="Lead object">
    <ResponseField name="id" type="uuid">
      Lead ID.
    </ResponseField>

    <ResponseField name="created_at" type="timestamp">
      When the lead was created.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Contact email.
    </ResponseField>

    <ResponseField name="first_name" type="string | null">
      First name.
    </ResponseField>

    <ResponseField name="last_name" type="string | null">
      Last name.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      Phone number.
    </ResponseField>

    <ResponseField name="company_name" type="string | null">
      Company name of the lead.
    </ResponseField>

    <ResponseField name="source" type="string | null">
      Lead source.
    </ResponseField>

    <ResponseField name="referring_employee" type="string | null">
      Employee at the referring company who submitted the lead.
    </ResponseField>

    <ResponseField name="notes" type="string | null">
      Free-text notes.
    </ResponseField>

    <ResponseField name="business_id" type="string | null">
      External business identifier.
    </ResponseField>

    <ResponseField name="channels_id" type="uuid">
      Channel this lead belongs to.
    </ResponseField>

    <ResponseField name="lead_status_id" type="uuid">
      Current lead status ID.
    </ResponseField>

    <ResponseField name="legacy_id" type="integer">
      Legacy integer ID for the lead.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current lead status name. Same value as `lead_status.status`.
    </ResponseField>

    <ResponseField name="lead_status" type="object">
      The current lead status.

      <Expandable title="Lead status object">
        <ResponseField name="id" type="uuid">
          Lead status ID. Matches `lead_status_id`.
        </ResponseField>

        <ResponseField name="status" type="string">
          Lead status name.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="property_values" type="array">
      Custom property values set on this lead.

      <Expandable title="Property value object">
        <ResponseField name="id" type="uuid">
          Property value ID.
        </ResponseField>

        <ResponseField name="value" type="string">
          The stored value.
        </ResponseField>

        <ResponseField name="property_definitions_id" type="uuid">
          ID of the property definition.
        </ResponseField>

        <ResponseField name="property_definitions" type="object">
          The property definition this value belongs to.

          <Expandable title="Property definition">
            <ResponseField name="id" type="uuid">
              Property definition ID.
            </ResponseField>

            <ResponseField name="name" type="string">
              Field name.
            </ResponseField>

            <ResponseField name="type" type="string">
              Field type.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Request

```bash theme={null}
curl -X POST https://data.keenpartner.com/functions/v1/keen-api \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "action": "update_lead",
    "lead_id": "019e4035-0fc5-7d3e-a16a-80b3360f137a",
    "company_name": "Acme",
    "notes": "Spoke with prospect on 2026-05-19",
    "properties": [
      {
        "property_definitions_id": "019dc3f6-1790-7298-932b-90a7ee4ba10c",
        "value": "High interest"
      }
    ]
  }'
```

### Response

```json theme={null}
{
  "lead": {
    "id": "019e4035-0fc5-7d3e-a16a-80b3360f137a",
    "created_at": "2026-05-19T12:27:59.809Z",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+45 12 34 56 78",
    "company_name": "Acme",
    "source": "Website",
    "referring_employee": "Bob",
    "notes": "Spoke with prospect on 2026-05-19",
    "business_id": "12345678",
    "channels_id": "019dc3f5-f38d-7dee-a5c9-9b9da6e6e77e",
    "lead_status_id": "019dc3f7-7ef5-7dd4-99b2-88ddf0b8f0e5",
    "legacy_id": 20047,
    "status": "New lead",
    "lead_status": {
      "id": "019dc3f7-7ef5-7dd4-99b2-88ddf0b8f0e5",
      "status": "New lead"
    },
    "property_values": [
      {
        "id": "019e40e7-6d0f-712c-91bb-2b0fca218b68",
        "value": "High interest",
        "property_definitions_id": "019dc3f6-1790-7298-932b-90a7ee4ba10c",
        "property_definitions": {
          "id": "019dc3f6-1790-7298-932b-90a7ee4ba10c",
          "name": "Interest",
          "type": "text"
        }
      }
    ]
  }
}
```

## Errors

| Status | Error                                                                   | Cause                                                                                                                                                                                                                                                                                         |
| ------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `"lead_id (uuid) required"`                                             | The `lead_id` field is missing or not a valid UUID.                                                                                                                                                                                                                                           |
| `400`  | `"At least one updatable field or non-empty properties array required"` | The request contains no allowed standard fields and no `properties`.                                                                                                                                                                                                                          |
| `400`  | `"Invalid properties"`                                                  | One or more `properties` entries reference a definition that doesn't belong to the lead's channel, are missing `property_definitions_id`, or have a `null`/`undefined` value. The response includes an `invalid` array with the offending entries. No changes are persisted when this occurs. |
| `401`  | `"Invalid API key"`                                                     | Missing or invalid `X-Api-Key` header.                                                                                                                                                                                                                                                        |
| `403`  | `"Lead not accessible"`                                                 | The lead exists but is not in a channel your API key's company can access.                                                                                                                                                                                                                    |
| `404`  | `"Lead not found"`                                                      | The lead could not be found after the access check.                                                                                                                                                                                                                                           |
| `500`  | `"..."`                                                                 | Unexpected server error.                                                                                                                                                                                                                                                                      |