> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversation history > Read every call, text and email your workspace has had with a person. 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](/api-reference/mcp)). ## 1. Find the person ```bash theme={null} curl "https://api.lumisreach.com/api/v1/history/people?limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```json theme={null} { "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 ```bash theme={null} curl "https://api.lumisreach.com/api/v1/contacts/5f25da85-…" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```json theme={null} { "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](/api-reference/sms/webhooks) 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. ```bash theme={null} 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. | ```json theme={null} { "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" } ``` ### Tags | 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. | Tags come from the AI's review after the call ends, so a call that just finished may have none for a few seconds. ### Download the recording `recording_url` needs the same API key as every other request: ```bash theme={null} 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](/api-reference/sms/webhooks) to be told the moment someone texts you, then fetch the thread when you need context. Likewise, a [call webhook](/api-reference/calls/webhooks) 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.