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

# Get a lead by ID

> Retrieve a specific lead by its Keen lead UUID.

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

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

## 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 `"get_lead_by_id"`.
</ParamField>

<ParamField body="lead_id" type="uuid" required>
  The UUID of the lead to retrieve.
</ParamField>

## Response

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

<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="business_id" type="string | null">
      External business identifier.
    </ResponseField>

    <ResponseField name="notes" type="string | null">
      Free-text notes.
    </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="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="status" type="string">
      Current lead status name. Same value as `lead_status.status`.
    </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": "get_lead_by_id",
    "lead_id": "99887766-5544-3322-1100-aabbccddeeff"
  }'
```

### Response

```json theme={null}
{
  "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.                                                                 |