Skip to main content

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.

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

​
action
string
required
Must be "update_lead".
​
lead_id
uuid
required
The lead’s UUID. If you only have the legacy integer ID, use get_lead_by_legacy_id to resolve it first.
​
email
string
Contact email address.
​
first_name
string
First name of the contact.
​
last_name
string
Last name of the contact.
​
phone
string
Phone number.
​
company_name
string
Company name of the lead.
​
source
string
How the lead was sourced (e.g. "Website", "Referral").
​
referring_employee
string
Employee at the referring company who submitted the lead.
​
notes
string
Free-text notes about the lead.
​
business_id
string
The business’ ID in the company register or an external identifier from your own system.
​
properties
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.
​
lead
object

​
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

StatusErrorCause
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.