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

> List leads in a channel, with custom property values flattened as top-level fields.

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

## Authentication

<ApiAuth />

## Request

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

<ParamField body="channel_id" type="uuid" required>
  The channel to retrieve leads from. Your company must have access to this channel.
</ParamField>

## Response

Returns a JSON array of lead objects ordered by `created_at` descending. Up to 100 leads are returned per request.

<Note>
  Custom properties defined on the channel appear as top-level keys on each lead, keyed by the property definition name (for example, `"Deal size"`). Use [`get_channels`](/api-reference/get-channels) to retrieve the list of property definitions for a channel.
</Note>

<ResponseField name="[]" type="array">
  <Expandable title="Lead object">
    <ResponseField name="id" type="uuid">Lead ID.</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="created_at" type="timestamp">When the lead was created.</ResponseField>
    <ResponseField name="status" type="string | null">Current lead status name.</ResponseField>

    <ResponseField name="<custom property name>" type="string">
      Any custom properties defined for the channel appear as additional top-level keys, named by their property definition name.
    </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_leads",
    "channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
```

### Response

```json theme={null}
[
  {
    "id": "99887766-5544-3322-1100-aabbccddeeff",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+45 12345678",
    "company_name": "Acme Inc",
    "source": "website",
    "referring_employee": "John Smith",
    "business_id": "biz-123",
    "notes": "Interested in premium plan",
    "created_at": "2026-04-21T10:00:00.000Z",
    "status": "New",
    "Deal size": "50000",
    "Region": "EMEA"
  }
]
```

## Errors

| Status | Error                      | Cause                                              |
| ------ | -------------------------- | -------------------------------------------------- |
| `400`  | `"channel_id required"`    | The `channel_id` field is missing.                 |
| `401`  | `"Invalid API key"`        | Missing or invalid `X-Api-Key` header.             |
| `403`  | `"Channel not accessible"` | Your company does not have access to this channel. |