Agent API/Leads

List Leads

Retrieve leads captured by your AI agent(s). Supports pagination, search (including booking confirmation codes), date range filtering, and CRM status filtering. Use your agent API key (pk_live_) to scope results to a single agent, or your Search API key (sk_live_) to pull leads across all agents in your account.

GET

https://agent.askhandle.com/api/v1/public/leads

Requires X-API-Key — Agent API key (pk_live_) — returns leads for that agent only. Or Search API key (sk_live_) — returns leads across all your agents.

Request

Headers

X-API-Key

stringrequired

Your pk_live_ (agent) or sk_live_ (account) API key

Query Parameters

workflowId

string

Filter by a specific AI agent ID (sk_live_ only — ignored when using pk_live_)

search

string

Search name, email, phone, company, custom fields, or a booking confirmation code

startDate

string

ISO date string — only leads extracted on or after this date (e.g. 2026-01-01)

endDate

string

ISO date string — only leads extracted on or before this date (e.g. 2026-03-31)

crmStatus

string

Filter by CRM push status: pending | completed | failed | skipped

limit

number

Max results per page (default 50, max 100)

offset

number

Pagination offset (default 0)

includeHistory

string

When "true", also returns a `transcript` field with the full conversation as plain text (default false, since this can be large)

Response

Success 200

JSON

{
  "leads": [
    {
      "id": "cm1abc123def456",
      "workflowId": "wf_xyz789",
      "workflowName": "Sales Bot",
      "channel": "web",
      "sender": "session_a1b2c3",
      "messageCount": 8,
      "conversationStatus": "completed",
      "startedAt": "2026-03-20T10:00:00.000Z",
      "endedAt": "2026-03-20T10:05:00.000Z",
      "extractedAt": "2026-03-20T10:06:00.000Z",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@acme.com",
      "phone": "+14155552671",
      "company": "Acme Inc",
      "jobTitle": "CTO",
      "budget": "$50k",
      "timeline": "Q2 2026",
      "interest": "high",
      "customFields": {
        "industry": "SaaS"
      },
      "formResponses": null,
      "preChatForm": {
        "name": "Jane",
        "email": "jane@acme.com"
      },
      "satisfaction": {
        "score": 3,
        "label": "Happy"
      },
      "ipInfo": {
        "place": "Singapore",
        "timeZone": "Asia/Singapore (+08)",
        "network": "StarHub · Mobile"
      },
      "transcript": "User: Hi, I'm interested in your product.\n\nAgent: Great! Can I get your name and email?\n\nUser: Jane Doe, jane@acme.com",
      "crm": {
        "status": "completed",
        "attempts": 1,
        "completedAt": "2026-03-20T10:07:00.000Z",
        "error": null
      }
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}

Errors

401

API key is missing

Error

{
  "error": "Missing API key. Include an X-API-Key header with your pk_live_ or sk_live_ key."
}

401

API key is invalid

Error

{
  "error": "Invalid API key."
}

403

The requested AI agent is not accessible with this key

Error

{
  "error": "Workflow not found or not accessible."
}

Code examples

// Using an agent key (pk_live_) — scoped to that agent
const res = await fetch('https://agent.askhandle.com/api/v1/public/leads', {
  headers: { 'X-API-Key': 'pk_live_your_agent_api_key' },
});
const { leads, total, hasMore } = await res.json();
console.log(`Fetched ${leads.length} of ${total} leads`);
leads.forEach(lead => {
  console.log(`${lead.firstName} ${lead.lastName} — ${lead.email}`);
});

Request

Headers

X-API-Key

stringrequired

Your pk_live_ (agent) or sk_live_ (account) API key

Query Parameters

workflowId

string

Filter by a specific AI agent ID (sk_live_ only — ignored when using pk_live_)

search

string

Search name, email, phone, company, custom fields, or a booking confirmation code

startDate

string

ISO date string — only leads extracted on or after this date (e.g. 2026-01-01)

endDate

string

ISO date string — only leads extracted on or before this date (e.g. 2026-03-31)

crmStatus

string

Filter by CRM push status: pending | completed | failed | skipped

limit

number

Max results per page (default 50, max 100)

offset

number

Pagination offset (default 0)

includeHistory

string

When "true", also returns a `transcript` field with the full conversation as plain text (default false, since this can be large)

Response

Success 200

JSON

{
  "leads": [
    {
      "id": "cm1abc123def456",
      "workflowId": "wf_xyz789",
      "workflowName": "Sales Bot",
      "channel": "web",
      "sender": "session_a1b2c3",
      "messageCount": 8,
      "conversationStatus": "completed",
      "startedAt": "2026-03-20T10:00:00.000Z",
      "endedAt": "2026-03-20T10:05:00.000Z",
      "extractedAt": "2026-03-20T10:06:00.000Z",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@acme.com",
      "phone": "+14155552671",
      "company": "Acme Inc",
      "jobTitle": "CTO",
      "budget": "$50k",
      "timeline": "Q2 2026",
      "interest": "high",
      "customFields": {
        "industry": "SaaS"
      },
      "formResponses": null,
      "preChatForm": {
        "name": "Jane",
        "email": "jane@acme.com"
      },
      "satisfaction": {
        "score": 3,
        "label": "Happy"
      },
      "ipInfo": {
        "place": "Singapore",
        "timeZone": "Asia/Singapore (+08)",
        "network": "StarHub · Mobile"
      },
      "transcript": "User: Hi, I'm interested in your product.\n\nAgent: Great! Can I get your name and email?\n\nUser: Jane Doe, jane@acme.com",
      "crm": {
        "status": "completed",
        "attempts": 1,
        "completedAt": "2026-03-20T10:07:00.000Z",
        "error": null
      }
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}

Errors

401

API key is missing

Error

{
  "error": "Missing API key. Include an X-API-Key header with your pk_live_ or sk_live_ key."
}

401

API key is invalid

Error

{
  "error": "Invalid API key."
}

403

The requested AI agent is not accessible with this key

Error

{
  "error": "Workflow not found or not accessible."
}

// Using an agent key (pk_live_) — scoped to that agent const res = await fetch('https://agent.askhandle.com/api/v1/public/leads', { headers: { 'X-API-Key': 'pk_live_your_agent_api_key' }, }); const { leads, total, hasMore } = await res.json(); console.log(`Fetched ${leads.length} of ${total} leads`); leads.forEach(lead => { console.log(`${lead.firstName} ${lead.lastName} — ${lead.email}`); });