API Documentation

v1.0 • Lead Management

Rate Limit1,000/hour

Versionv1.0

Back to Home

Dashboard

Get Lead

Retrieve a specific lead by ID

GET

3 min read

Endpoint

Fetches one lead scoped to a chatbot in your workspace

GET https://pollybot.app/api/v1/chatbots/{chatbotId}/leads/{id}

Required Headers

Authorization: Bearer sk-workspace_your_api_key_here

Path Parameters

chatbotId

The unique identifier of the chatbot (required). Must belong to the workspace of the API key.

string

id

The unique identifier of the lead (required). Must belong to the chatbot.

string

Example Request

Fetch one lead by its ID

curl "https://pollybot.app/api/v1/chatbots/cmqjwkljc00892znge0tk4c37/leads/cmf8x2k3j0001abcdef123456" \
  -H "Authorization: Bearer sk-workspace_your_api_key_here"

Success Response

200 OK — the full lead object

{
  "success": true,
  "data": {
    "id": "cmf8x2k3j0001abcdef123456",
    "chatbotId": "cmqjwkljc00892znge0tk4c37",
    "conversationId": "cmf8x1p9a0000abcdef123456",
    "name": "Jane Cooper",
    "email": "jane@acme.com",
    "phone": "+14155550132",
    "company": "Acme Inc",
    "message": "Interested in the Pro plan",
    "source": "chat_widget",
    "status": "NEW",
    "priority": "MEDIUM",
    "assignedAgentId": null,
    "notes": null,
    "tags": ["pricing"],
    "customFields": null,
    "followUpDate": null,
    "lastContactAt": null,
    "convertedAt": null,
    "createdAt": "2026-08-15T09:24:11.000Z",
    "updatedAt": "2026-08-15T09:24:11.000Z",
    "discord": null,
    "preferredMethod": "email",
    "urgency": "low",
    "chatbots": {
      "id": "cmqjwkljc00892znge0tk4c37",
      "name": "Support Bot"
    }
  }
}

Lead Fields

Field	Type	Description
`id`	string	Unique lead identifier (cuid)
`chatbotId`	string	Chatbot the lead belongs to
`conversationId`	string \| null	Conversation the lead was captured from, if any
`name`	string	Lead name
`email`	string \| null	Email address
`phone`	string \| null	Phone number
`company`	string \| null	Company name
`message`	string \| null	Message left by the lead
`source`	string	Where the lead came from (default "chat_widget")
`status`	string	NEW, CONTACTED, QUALIFIED, NEGOTIATING, CONVERTED, LOST, or UNRESPONSIVE
`priority`	string	LOW, MEDIUM, HIGH, or URGENT
`assignedAgentId`	string \| null	Agent assigned to this lead, if any
`notes`	string \| null	Internal notes
`tags`	string[]	Tags attached to the lead
`customFields`	object \| null	Arbitrary custom key/value data
`followUpDate`	string \| null	Scheduled follow-up (ISO 8601)
`lastContactAt`	string \| null	Last contact timestamp (ISO 8601)
`convertedAt`	string \| null	Conversion timestamp (ISO 8601)
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)
`discord`	string \| null	Discord username
`preferredMethod`	string	Preferred contact method: email, phone, or discord
`urgency`	string	Urgency reported by the lead: low, medium, or high
`chatbots`	object	Owning chatbot: { id, name }

Rate Limit Headers

Every successful response includes your current rate limit state (1000 requests per hour per API key):

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1774521600

Error Responses

All errors return success: false with an error code

Status	Code	When
401	`AUTHENTICATION_FAILED`	Missing, malformed, invalid, or inactive API key.
404	`CHATBOT_NOT_FOUND`	The chatbot does not exist or does not belong to your workspace.
404	`LEAD_NOT_FOUND`	The lead does not exist or does not belong to this chatbot.
429	`RATE_LIMIT_EXCEEDED`	More than 1000 requests in an hour with this API key.
500	`INTERNAL_ERROR`	Unexpected server error.

404 Not Found (lead)

{
  "success": false,
  "error": "Lead not found",
  "code": "LEAD_NOT_FOUND"
}

404 Not Found (chatbot)

{
  "success": false,
  "error": "Chatbot not found or access denied",
  "code": "CHATBOT_NOT_FOUND"
}

List Leads Update Lead