Update a lead

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

Authentication

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

string

required

Must be "update_lead".

uuid

required

The lead’s UUID. If you only have the legacy integer ID, use get_lead_by_legacy_id to resolve it first.

string

Contact email address.

string

First name of the contact.

string

Last name of the contact.

string

Phone number.

string

Company name of the lead.

string

How the lead was sourced (e.g. "Website", "Referral").

string

Employee at the referring company who submitted the lead.

string

Free-text notes about the lead.

string

The business’ ID in the company register or an external identifier from your own system.

array

Custom property values to upsert on the lead. Each entry requires a property_definitions_id and a value. Use get_channels to retrieve the property definitions available on the lead’s channel.

[
  {
    "property_definitions_id": "019dc3f6-1790-7298-932b-90a7ee4ba10c",
    "value": "High interest"
  }
]

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.

At least one standard field or a non-empty properties array is required.

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.

object

Show Lead object

uuid

Lead ID.

timestamp

When the lead was created.

string | null

Contact email.

string | null

First name.

string | null

Last name.

string | null

Phone number.

string | null

Company name of the lead.

string | null

Lead source.

string | null

Employee at the referring company who submitted the lead.

string | null

Free-text notes.

string | null

External business identifier.

uuid

Channel this lead belongs to.

uuid

Current lead status ID.

integer

Legacy integer ID for the lead.

string

Current lead status name. Same value as lead_status.status.

object

The current lead status.

Show Lead status object

uuid

Lead status ID. Matches lead_status_id.

string

Lead status name.

array

Custom property values set on this lead.

Show Property value object

uuid

Property value ID.

string

The stored value.

uuid

ID of the property definition.

object

The property definition this value belongs to.

Show Property definition

uuid

Property definition ID.

string

Field name.

string

Field type.

Example

Request

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

{
  "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.

Overview

Channels

Leads

Purchases

Update a lead

Authentication

Request

Behavior

Response

Example

Request

Response

Errors

​Authentication

​Request

​Behavior

​Response

​Example

​Request

​Response

​Errors

Authentication

Request

Behavior

Response

Example

Request

Response

Errors