Agent API/Leads
Get Lead
Fetch a single lead by its ID. Returns the full lead object including all extracted fields, form responses, and CRM push details.
GET
https://agent.askhandle.com/api/v1/public/leads/{leadId}Requires X-API-Key — Agent API key (pk_live_) — only finds leads from that agent. Or Search API key (sk_live_) — finds any lead in your account.
Request
Headers
X-API-Keystringrequired
Your pk_live_ (agent) or sk_live_ (account) API key
Query Parameters
leadIdstringrequired
The lead ID (from the List Leads response)
includeHistorystring
When "true", also returns a `transcript` field with the full conversation as plain text (default false)
Response
Success 200
JSON
{
"lead": {
"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",
"notes": "Interested in enterprise plan",
"requirements": "SSO, audit logs, dedicated support",
"customFields": {
"industry": "SaaS"
},
"formResponses": null,
"preChatForm": null,
"satisfaction": null,
"ipInfo": {
"place": "Los Angeles, California, United States",
"timeZone": "America/Los_Angeles (PDT)",
"network": "Comcast · Cable"
},
"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,
"results": {
"salesforceLeadId": "00Q1234567890"
}
}
}
}Errors
401
API key is missing or invalid
Error
{
"error": "Invalid API key."
}404
Lead ID doesn't exist or is not accessible with this key
Error
{
"error": "Lead not found."
}Code examples
const leadId = 'cm1abc123def456';
const res = await fetch(
`https://agent.askhandle.com/api/v1/public/leads/${leadId}`,
{ headers: { 'X-API-Key': 'pk_live_your_agent_api_key' } }
);
const { lead } = await res.json();
console.log(`${lead.firstName} ${lead.lastName} — ${lead.email}`);
console.log('CRM status:', lead.crm.status);