Update Lead

PUT /leads/{id}

Update any field on an existing lead. Metadata updates use shallow merge semantics: existing keys are preserved, new keys are added, and matching keys are overwritten. Non-metadata fields (first_name, phone, campaign_id, etc.) are replaced directly.

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Yes	Lead ID

Request Body

All fields are optional. Only include the fields you want to update.

Field	Type	Description
first_name	string	Lead's first name
last_name	string | null	Lead's last name
email	string | null	Lead's email address
phone	string | null	Lead's phone number
company	string | null	Lead's company name
title	string | null	Lead's job title
source	string	Lead source
campaign_id	string (uuid) | null	Campaign ID. Set to null to remove campaign
metadata	object	Key-value pairs to merge into existing metadata

Examples

Update basic fields

curl -X PUT https://api.getnexor.ai/api/public/leads/123e4567-e89b-12d3-a456-426614174000 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "first_name": "Carlos",
    "last_name": "Rodriguez",
    "company": "New Corp"
  }'

Update a single metadata key

Other existing metadata keys are preserved.

curl -X PUT https://api.getnexor.ai/api/public/leads/123e4567-e89b-12d3-a456-426614174000 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "metadata": {
      "estado_lead": "calificado"
    }
  }'

Update fields and metadata together

curl -X PUT https://api.getnexor.ai/api/public/leads/123e4567-e89b-12d3-a456-426614174000 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "phone": "+56987654321",
    "campaign_id": "123e4567-e89b-12d3-a456-426614174001",
    "metadata": {
      "estado_lead": "calificado",
      "broker_asociado": "Maria Gonzalez"
    }
  }'

Responses

200 — Lead updated successfully

{
  "success": true,
  "lead": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "Carlos",
    "last_name": "Rodriguez",
    "phone": "+56987654321",
    "metadata": {
      "edad": 35,
      "utm_source": "google",
      "estado_lead": "calificado",
      "broker_asociado": "Maria Gonzalez"
    },
    "created_at": "2026-02-10T12:00:00Z"
  }
}

400 — Validation error

{
  "error": "Validation error",
  "message": "No fields to update"
}

401 — Authentication error

See Authentication.

404 — Lead not found

{
  "error": "Not found",
  "message": "Lead not found or does not belong to your account"
}

500 — Internal server error