Conversation history

These read-only endpoints return everything your workspace knows about each person and has said to them: their contact details, calls (with transcripts, tags and audio recordings), texts and emails. Reads are free, never billed.

Endpoint	Returns	Scope
`GET /v1/history/people`	Everyone you’ve called, texted or emailed, most recent first, with counts	`contacts:read`
`GET /v1/contacts/{id}`	One contact’s full details: name, phone, email, company, notes, consent	`contacts:read`
`GET /v1/history/calls`	Every call with one person, with transcripts, summaries and tags	`calls:read`
`GET /v1/history/calls/{id}`	One call, by id	`calls:read`
`GET /v1/history/calls/{id}/recording`	The call’s audio file	`calls:read`
`GET /v1/history/texts`	The whole SMS thread with one person	`sms:read`
`GET /v1/history/emails`	Every email with one person, including Quick Emails	`email:read`

The same reads are available to agents as MCP tools: list_contacted_people, get_contact, get_call_transcripts, get_text_history and get_email_history (see MCP server).

1. Find the person

curl "https://api.lumisreach.com/api/v1/history/people?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "contact_id": "5f25da85-…",
      "name": "Jane Doe",
      "phone_number": "+14155550123",
      "email": "jane@example.com",
      "call_count": 2,
      "text_count": 14,
      "email_count": 1,
      "first_contacted_at": "2026-09-02T16:11:40.000Z",
      "last_contacted_at": "2026-09-25T17:04:12.102Z"
    }
  ],
  "meta": { "cursor": "…", "page_size": 20 }
}

contact_id is null for someone you reached who has no contact record yet.

2. Get their details

curl "https://api.lumisreach.com/api/v1/contacts/5f25da85-…" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "id": "5f25da85-…",
    "name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "+14155550123",
    "email": "jane@example.com",
    "company": "Doe Dental",
    "job_title": "Office Manager",
    "industry": null,
    "location": "San Francisco, CA",
    "preferred_language": "en",
    "date_of_birth": null,
    "notes": "Prefers texts after 5pm.",
    "tags": ["vip"],
    "subscription_plan": null,
    "purchase_history": null,
    "product_preferences": null,
    "custom_fields": { "source": "website" },
    "consent": { "sms_opted_in": true, "voice_opted_in": false, "email_opted_in": false, "email_subscribed": true },
    "first_inbound_call_at": "2026-09-02T16:11:40.000Z",
    "first_inbound_text_at": null,
    "first_inbound_email_at": null,
    "crm": null,
    "created_at": "2026-09-02T16:11:41.000Z",
    "updated_at": "2026-09-25T17:04:12.381Z"
  }
}

The contact id also arrives on every inbound SMS webhook as data.contact.id. crm is set when the contact is synced with a CRM, and holds the provider and its record id.

3. Read the conversation

Name the person with exactly one of contact_id or their address: phone_number (E.164) for calls and texts, email for emails.

curl "https://api.lumisreach.com/api/v1/history/texts?phone_number=%2B14155550123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each text carries a sender:

`sender`	Who wrote it
`contact`	The person.
`ai_agent`	Your AI agent: inbox auto-replies, SMS campaign agents, Quick AI Text threads.
`business`	Someone at your business: dashboard inbox, the API, workflows, single quick texts.

Emails carry a source of inbox or quick (sent with Quick Email).

4. Calls: transcripts, tags and recordings

Each call from GET /v1/history/calls (or one call from GET /v1/history/calls/{id}) carries:

Field	Meaning
`summary`	The AI’s summary of the call.
`transcript`	The full transcript as plain text.
`transcript_turns`	The same, split into turns labelled `agent` or `person`, with `seconds_from_start` when known.
`tags`	Labels on the call, the same ones your dashboard shows as badges (below).
`has_recording`	Whether there is audio for this call.
`recording_url`	Where to download the audio, or `null` when there is none.

{
  "id": "3b0c1f8e-…",
  "direction": "inbound",
  "status": "COMPLETED",
  "from_number": "+14155550123",
  "to_number": "+14157279482",
  "duration_seconds": 94,
  "summary": "Jane asked to move her cleaning to Thursday afternoon.",
  "transcript": "Thanks for calling Doe Dental, how can I help? …",
  "transcript_turns": [
    { "speaker": "agent", "text": "Thanks for calling Doe Dental, how can I help?", "seconds_from_start": 0.4 },
    { "speaker": "person", "text": "Hi, can I move my cleaning to Thursday?", "seconds_from_start": 3.1 }
  ],
  "tags": ["booking_requested", "qualified"],
  "has_recording": true,
  "recording_url": "https://api.lumisreach.com/api/v1/history/calls/3b0c1f8e-…/recording",
  "created_at": "2026-09-25T17:02:37.000Z"
}

Tag	Meaning
`booking_requested`	The person asked to book an appointment.
`callback_requested`	The person asked to be called back.
`complaint`	The person made a complaint.
`purchase_interest`	The person showed interest in buying.
`interested`	The AI judged the person interested overall.
`qualified`	The call produced a qualified lead.
`not_interested`	The person said they are not interested.
`transferred`	The AI transferred the call to a person on your team.

Download the recording

recording_url needs the same API key as every other request:

curl "https://api.lumisreach.com/api/v1/history/calls/3b0c1f8e-…/recording" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o call.mp3

The response is the raw audio (usually audio/mpeg), never cached. It returns 404 when the call has no recording, when recording was turned off for it by your compliance settings, or when the call is not in your workspace. Every download is written to your compliance audit log, attributed to the API key’s owner.

Pagination

Results come newest first. Pass meta.cursor from one response as cursor on the next request; there are no more pages when meta.cursor is absent. limit defaults to 20 and caps at 100 (50 for calls, since each one carries a full transcript).

Keeping up to date

Rather than polling /v1/history/texts, register an inbound SMS webhook to be told the moment someone texts you, then fetch the thread when you need context. Likewise, a call webhook sends you each call’s full transcript as soon as the call ends, so you never need to poll /v1/history/calls for new calls.

Getting Started

Concepts

Quick Agent Actions