v1.0 • Lead Management
Add a new lead to a specific chatbot
Leads are scoped to a chatbot — the chatbot ID is part of the URL
chatbotIdThe chatbot the lead belongs to. Must belong to the workspace of your API key.
JSON object. Only name is required.
| Field | Type | Required | Constraints | Default |
|---|---|---|---|---|
name | string | Yes | 1–100 characters | — |
email | string | No | Valid email. Must be unique among this chatbot's leads | — |
phone | string | No | Max 20 characters | — |
discord | string | No | Max 50 characters | — |
company | string | No | Max 100 characters | — |
message | string | No | Max 1000 characters | — |
preferredMethod | enum | No | email | phone | discord | "email" |
urgency | enum | No | low | medium | high | "low" |
source | string | No | Max 50 characters | "api" |
customFields | object | No | Arbitrary key–value pairs | — |
tags | string[] | No | Max 10 tags, each max 50 characters | [] |
curl -X POST "https://pollybot.app/api/v1/chatbots/cmq8h2xkp0031jrnghg5wq9d2/leads" \
-H "Authorization: Bearer sk-workspace_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Cooper",
"email": "jane.cooper@acme.com",
"phone": "+14155550132",
"company": "Acme Inc.",
"message": "Interested in the enterprise plan.",
"preferredMethod": "email",
"urgency": "high",
"source": "landing-page",
"customFields": { "plan": "enterprise" },
"tags": ["enterprise", "pricing"]
}'Returns the full lead record, including the connected chatbot. New leads start with status NEW and priority MEDIUM. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
{
"success": true,
"data": {
"id": "cmqjwkljc00892znge0tk4c37",
"chatbotId": "cmq8h2xkp0031jrnghg5wq9d2",
"conversationId": null,
"name": "Jane Cooper",
"email": "jane.cooper@acme.com",
"phone": "+14155550132",
"company": "Acme Inc.",
"message": "Interested in the enterprise plan.",
"source": "landing-page",
"status": "NEW",
"priority": "MEDIUM",
"assignedAgentId": null,
"notes": null,
"tags": ["enterprise", "pricing"],
"customFields": { "plan": "enterprise" },
"followUpDate": null,
"lastContactAt": null,
"convertedAt": null,
"createdAt": "2026-08-19T09:14:32.118Z",
"updatedAt": "2026-08-19T09:14:32.118Z",
"discord": null,
"preferredMethod": "email",
"urgency": "high",
"chatbots": {
"id": "cmq8h2xkp0031jrnghg5wq9d2",
"name": "Support Bot"
}
}
}Creating a lead fires the LEAD_CREATED webhook event for the chatbot. Webhook delivery failures do not fail the request — the lead is still created.
All error responses have the shape { success: false, error, code }
| Status | Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | Request body failed validation. The details field contains per-field Zod errors. |
401 | AUTHENTICATION_FAILED | Missing, malformed, or invalid API key. |
404 | CHATBOT_NOT_FOUND | Chatbot does not exist or does not belong to your workspace. |
409 | DUPLICATE_EMAIL | A lead with this email already exists for this chatbot. Response includes existingLeadId. |
429 | RATE_LIMIT_EXCEEDED | More than 1000 requests in the past hour for this API key. |
500 | INTERNAL_ERROR | Unexpected server error. |
{
"success": false,
"error": "Validation failed",
"code": "VALIDATION_ERROR",
"details": {
"_errors": [],
"name": { "_errors": ["Name is required"] },
"email": { "_errors": ["Invalid email"] }
}
}{
"success": false,
"error": "Lead with this email already exists for this chatbot",
"code": "DUPLICATE_EMAIL",
"existingLeadId": "cmqhx2p4d00312zngq7rv8m1k"
}