Customers

People whose calls have been analysed. Unlike nextneural_converse, customers here are mostly a by-product: they are created automatically from uploads, matched by phone number, so a person's history accumulates without any linking step.

List customers

GET /api/customers

Takes search, limit, offset, and segment filters.

{
  "customers": [
    {
      "id": 87,
      "uuid": "cu1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
      "name": "Priya Kumar",
      "phone": "+918888888888",
      "email": "[email protected]",
      "segment": "winback",
      "tags": ["north"],
      "attributes": { "plan": "pro" },
      "external_ids": { "salesforce": "003XX000004TmiQ" },
      "context_summary": "Long-standing customer, price-sensitive, prefers evening calls.",
      "total_calls": 4,
      "last_contact": "2026-09-20T14:33:54Z",
      "segments": [{ "uuid": "sg1a…", "name": "winback" }],
      "alternate_phones": [{ "uuid": "ph1a…", "phone": "+919876500000", "label": "office" }]
    }
  ],
  "total": 240
}

Get a customer

GET /api/customers/{id}

Update a customer

PATCH /api/customers/{id}

{
  "name": "Priya Kumar",
  "phone": "+918888888888",
  "segment": "winback",
  "context_summary": "Long-standing customer, price-sensitive.",
  "attributes": { "plan": "pro" },
  "tags": ["north"]
}

Field	Type	Notes
name	string
phone	string
segment	string
context_summary	string	Overwrites the generated brief
attributes	object	String values only
tags	string[]	Replaces the existing list

All optional. email, external_ids, total_calls, and last_contact are not settable here — the first two are populated by the ingestion source, the last two by the pipeline.

Follow-ups

GET /api/customers/followups

Customers whose last call ended in a commitment — follow_up_scheduled, visit_scheduled — that has not yet been met. This is the work queue a rep should start their day from.

{
  "customers": [
    {
      "customer_id": 87,
      "customer_uuid": "cu1a2b3c-…",
      "name": "Priya Kumar",
      "phone": "+918888888888",
      "tags": ["north"],
      "total_calls": 4,
      "last_call_at": "2026-09-20T14:33:54Z",
      "last_contact": "2026-09-20T14:33:54Z",
      "next_action": null,
      "outcome": "follow_up_scheduled",
      "sentiment": "positive",
      "summary": "Asked to be called back after the 27th."
    }
  ]
}

Customer events

A timeline of what happened with a person, beyond the calls themselves.

List events

GET /api/customers/{id}/events

Add an event

POST /api/customers/{id}/events

{
  "text": "Sent the revised quote by email.",
  "event_type": "note",
  "author": "Arjun Rao"
}

Field	Required	Notes
text	✓	What happened
event_type	—	Free-form category, e.g. note, email, meeting
author	—	Who recorded it

The stored event also carries uuid, origin, payload, occurred_at, and synced_at, which are set server-side and returned by the list endpoint.

Use this to record things that happened off the phone — an email, a meeting, a contract sent — so the context summary and the follow-up queue reflect the whole relationship rather than only the calls.

Context summary

POST /api/customers/{id}/generate-summary

Regenerates context_summary from the customer's call history and events: a short brief on who this person is and where the relationship stands, for a rep about to call them.

Regenerate after a significant call rather than on a schedule — it reads the full history each time.

Alternate phone numbers

One person, several numbers. Adding them here means calls from any of them attach to the same customer instead of creating duplicates.

List

GET /api/customers/{id}/phones

Add

POST /api/customers/{id}/phones

{ "phone": "+919876500000", "label": "office" }

Remove

DELETE /api/customers/{id}/phones/{phoneId}

Merging duplicates

There is no merge endpoint. If the same person exists twice under different numbers, add the second number as an alternate on the record you want to keep, then move any calls across with PATCH /api/calls/{id} before deleting the duplicate.

Bulk segment assignment

POST /api/customers/bulk-segment

{
  "customer_ids": [87, 88, 91],
  "segment": "winback"
}

Field	Required	Notes
customer_ids	✓	Which customers to reassign
segment	—	The segment name. Omit or send null to clear it

See Segments for the call-side equivalent.