Leads

Update a lead's name, email or custom fields

PATCH /v1/leads/{lead_id}

Scope

leads:write

Tier

Tier 1

Data

Personal data

Idempotency

Idempotency-Key: optional

Only full_name, email and custom_fields can change. The phone number can never change: import the new number as a new lead. In custom_fields, a key set to null is removed and keys you do not send are kept. Send If-Match with the lead's ETag to refuse the update (412) when someone changed the lead since you read it.

Parameters

Request body

The fields to change.

JSON: LeadUpdateRequest

Response

200: The updated lead.

Examples

Request example

curl

curl -sS -X PATCH \
  "https://app.dialerbee.com/api/v1/leads/lead_0f8fad5b-d9cb-469f-a165-70867728950e" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "email": "[email protected]",
  "custom_fields": {
    "tier": "platinum"
  }
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.leads.update(
    "lead_0f8fad5b-d9cb-469f-a165-70867728950e",
    email="[email protected]",
    custom_fields={"tier": "platinum"},
)

Response example

200

{
  "id": "lead_0f8fad5b-d9cb-469f-a165-70867728950e",
  "campaign_id": "cmp_0f8fad5b-d9cb-469f-a165-70867728950e",
  "external_id": "CRM-1001",
  "phone": "+12125550101",
  "full_name": "Ann Lee",
  "email": "[email protected]",
  "status": "contacted",
  "attempts": 1,
  "custom_fields": {
    "tier": "platinum"
  },
  "last_attempt_at": "2026-09-29T11:58:00Z",
  "next_attempt_at": "2026-09-30T10:00:00Z",
  "disposition_code": "interested",
  "hangup_cause": "NORMAL_CLEARING",
  "created_at": "2026-09-29T09:15:00Z",
  "updated_at": "2026-09-29T09:20:00Z"
}

Error examples

403 insufficient_scope

{
  "type": "https://docs.dialerbee.com/errors/insufficient-scope",
  "title": "Not permitted",
  "status": 403,
  "detail": "The API client does not hold the scope this operation requires.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "insufficient_scope",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

400 validation_failed

{
  "type": "https://docs.dialerbee.com/errors/validation-failed",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request is not valid.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "validation_failed",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "errors": [
    {
      "pointer": "/leads/1/phone",
      "code": "missing"
    }
  ]
}

401 invalid_api_key

{
  "type": "https://docs.dialerbee.com/errors/invalid-api-key",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The Authorization header is missing, is not Bearer dbk_live_..., or the key is not recognised, has expired or was revoked (one answer for every key problem, so a key's state is never revealed).",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "invalid_api_key",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

LeadUpdateRequest

Lead