Back to Home
Dashboard

Update Lead

Modify an existing lead with a partial update

PUT
4 min read

Endpoint

The lead must belong to the chatbot in the URL

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

Required Headers

Authorization: Bearer sk-workspace_your_api_key_here
Content-Type: application/json

Path Parameters

chatbotId

The chatbot the lead belongs to. Must belong to the workspace of your API key.

string
id

The ID of the lead to update.

string

Request Body

JSON object. Every field is optional — send only the fields you want to change; omitted fields keep their current values.

FieldTypeRequiredConstraints
namestringNo1–100 characters
emailstringNoValid email. Must be unique among this chatbot's leads
phonestringNoMax 20 characters
discordstringNoMax 50 characters
companystringNoMax 100 characters
messagestringNoMax 1000 characters
preferredMethodenumNoemail | phone | discord
urgencyenumNolow | medium | high
statusenumNoNEW | CONTACTED | QUALIFIED | NEGOTIATING | CONVERTED | LOST | UNRESPONSIVE
priorityenumNoLOW | MEDIUM | HIGH | URGENT
notesstringNoMax 2000 characters
customFieldsobjectNoArbitrary key–value pairs. Replaces the stored object entirely
tagsstring[]NoMax 10 tags, each max 50 characters. Replaces the stored array entirely

Example Request

Move a lead forward in the pipeline and attach notes

curl -X PUT "https://pollybot.app/api/v1/chatbots/cmq8h2xkp0031jrnghg5wq9d2/leads/cmqjwkljc00892znge0tk4c37" \
  -H "Authorization: Bearer sk-workspace_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "QUALIFIED",
    "priority": "HIGH",
    "notes": "Demo scheduled for Friday. Decision maker on the call.",
    "tags": ["enterprise", "pricing", "demo-scheduled"]
  }'
200 OK

Success Response

Returns the full updated lead record, including the connected chatbot. 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": "QUALIFIED",
    "priority": "HIGH",
    "assignedAgentId": null,
    "notes": "Demo scheduled for Friday. Decision maker on the call.",
    "tags": ["enterprise", "pricing", "demo-scheduled"],
    "customFields": { "plan": "enterprise" },
    "followUpDate": null,
    "lastContactAt": null,
    "convertedAt": null,
    "createdAt": "2026-08-19T09:14:32.118Z",
    "updatedAt": "2026-08-19T10:02:51.407Z",
    "discord": null,
    "preferredMethod": "email",
    "urgency": "high",
    "chatbots": {
      "id": "cmq8h2xkp0031jrnghg5wq9d2",
      "name": "Support Bot"
    }
  }
}

Errors

All error responses have the shape { success: false, error, code }

StatusCodeDescription
400
VALIDATION_ERRORRequest body failed validation. The details field contains per-field Zod errors.
401
AUTHENTICATION_FAILEDMissing, malformed, or invalid API key.
404
CHATBOT_NOT_FOUNDChatbot does not exist or does not belong to your workspace.
404
LEAD_NOT_FOUNDLead does not exist or does not belong to this chatbot.
409
DUPLICATE_EMAILAnother lead of this chatbot already uses the new email address.
429
RATE_LIMIT_EXCEEDEDMore than 1000 requests in the past hour for this API key.
500
INTERNAL_ERRORUnexpected server error.

404 — Lead not found

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

409 — Duplicate email

{
  "success": false,
  "error": "Lead with this email already exists for this chatbot",
  "code": "DUPLICATE_EMAIL"
}
Create LeadDelete Lead