Get Lead History

GET /leads/{id}/history

Returns the full conversation and activity history for a lead in chronological order. Merges WhatsApp messages, email messages, call transcripts, and system activity events into a unified timeline.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
channel	string	(all)	Comma-separated channel filter. Valid values: call, whatsapp, email
limit	integer	50	Max items to return (1–200)
offset	integer	0	Pagination offset

Examples

# Full history
curl https://api.getnexor.ai/api/public/leads/550e8400-e29b-41d4-a716-446655440000/history \
  -H "X-API-Key: nxr_live_your_api_key"

# Calls and WhatsApp only
curl "https://api.getnexor.ai/api/public/leads/550e8400-e29b-41d4-a716-446655440000/history?channel=call,whatsapp" \
  -H "X-API-Key: nxr_live_your_api_key"

# Paginated
curl "https://api.getnexor.ai/api/public/leads/550e8400-e29b-41d4-a716-446655440000/history?limit=20&offset=40" \
  -H "X-API-Key: nxr_live_your_api_key"

Responses

200 — History retrieved successfully

{
  "success": true,
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "source": "api",
    "created_at": "2026-01-10T08:00:00Z"
  },
  "history": [
    {
      "type": "activity",
      "channel": "system",
      "activity_type": "workflow_assigned",
      "title": "Assigned to Sales Outreach",
      "description": "Lead enrolled via API",
      "actor_type": "system",
      "timestamp": "2026-01-10T08:00:00Z"
    },
    {
      "type": "message",
      "channel": "whatsapp",
      "direction": "outbound",
      "content": "Hi John, thanks for your interest!",
      "message_type": "template",
      "status": "delivered",
      "timestamp": "2026-01-10T09:00:00Z"
    },
    {
      "type": "message",
      "channel": "whatsapp",
      "direction": "inbound",
      "content": "Yes, I'd like to learn more about pricing",
      "message_type": "text",
      "status": "read",
      "timestamp": "2026-01-10T09:05:00Z"
    },
    {
      "type": "call",
      "channel": "call",
      "duration_seconds": 185,
      "call_status": "ended",
      "summary": "Discussed pricing tiers and scheduled a demo for next week",
      "recording_url": "https://storage.example.com/recordings/abc123.wav",
      "sentiment": "positive",
      "timestamp": "2026-01-10T14:00:00Z"
    },
    {
      "type": "activity",
      "channel": "call",
      "activity_type": "status_changed",
      "title": "Status changed to Qualified",
      "description": "Lead qualified after discovery call",
      "actor_type": "ai",
      "timestamp": "2026-01-10T14:03:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

History Entry Types

Each item in the history array has a type field that determines which fields are populated:

type: "message" — WhatsApp, email, or call messages

Field	Type	Description
channel	string	whatsapp, call, or email
direction	string	inbound or outbound
content	string	Message text content
message_type	string	text, template, or media
status	string	sent, delivered, read, or failed

type: "call" — Call transcript summaries

Field	Type	Description
duration_seconds	integer	Call duration in seconds
call_status	string	Call outcome status
summary	string	AI-generated call summary
recording_url	string	URL to the call recording
sentiment	string	positive, neutral, or negative

type: "activity" — System events

Field	Type	Description
channel	string	Channel that triggered the activity, or system
activity_type	string	Event type (e.g., status_changed, workflow_assigned)
title	string	Human-readable event title
description	string	Event description
actor_type	string	user, system, or ai

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