Get a lead by ID

Use this action to retrieve one lead by its Keen lead UUID. Your company must have access to the lead’s channel.

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

uuid

required

The UUID of the lead to retrieve.

Response

Returns the full lead object, including nested property_values with their property_definitions.

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

External business identifier.

string | null

Free-text notes.

uuid

Channel this lead belongs to.

uuid

Current lead status ID.

object

The current lead status.

Show Lead status object

uuid

Lead status ID. Matches lead_status_id.

string

Lead status name.

string

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

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": "get_lead_by_id",
    "lead_id": "99887766-5544-3322-1100-aabbccddeeff"
  }'

Response

{
  "lead": {
    "id": "99887766-5544-3322-1100-aabbccddeeff",
    "email": "alex@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "phone": "+4512345678",
    "company_name": "Example Company",
    "source": "Partner referral",
    "referring_employee": "Jamie Smith",
    "business_id": "12345678",
    "notes": "Interested in partner program",
    "channels_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "lead_status_id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    "lead_status": {
      "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
      "status": "Qualified"
    },
    "status": "Qualified",
    "created_at": "2026-05-19T12:00:00.000Z",
    "property_values": [
      {
        "id": "77665544-3322-1100-aabb-ccddeeff0011",
        "value": "Enterprise",
        "property_definitions_id": "11111111-2222-3333-4444-555555555555",
        "property_definitions": {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Segment",
          "type": "text"
        }
      }
    ]
  }
}

Errors

Status	Error	Cause
`400`	`"lead_id (uuid) required"`	The `lead_id` field is missing or not a valid UUID.
`401`	`"Invalid API key"`	Missing or invalid `X-Api-Key` header.
`403`	`"Lead not accessible"`	Your company does not have access to the lead’s channel, or the lead cannot be accessed.
`404`	`"Lead not found"`	The lead was not found after access validation.
`500`	`"..."`	Unexpected server error.

Overview

Channels

Leads

Purchases

Get a lead by ID

Authentication

Request

Response

Example

Request

Response

Errors

​Authentication

​Request

​Response

​Example

​Request

​Response

​Errors

Authentication

Request

Response

Example

Request

Response

Errors