Contacts

List Contact History

Unified timeline of conversations, flow runs, flow-sent messages, scheduled sends, all messages, and AI ticket summaries for a single contact.

Powers the contact-detail "History" card (Activity + Messages view modes). Returns a single keyset-paginated, time-descending stream merged from multiple SHARD tables — see :class:app.services.contact_history_service.ContactHistoryService for the per-source query strategy and batch lookups.

Event types:

  • conversation — one row per conversation (Activity mode).
  • flow_run — one row per flow run (Activity mode).
  • flow_message — flow-attributed messages only (legacy).
  • message — every message for the contact regardless of flow attribution (Messages mode).
  • scheduler — pending or fired scheduled sends (reminders, recurring sends, segment-blast materializations).
  • ticket_summary — AI conversation summaries persisted as editable KB documents (knowledge_base_documents filtered by the indexed contact_id column, document_type='ticket_summary'). The document_id deep-links to the KB editor / raw GET-PUT endpoints.

Required Scopes: contacts:read AND flows:read AND conversations:read AND scheduler:read AND knowledge_base:read

get/api/v1/contacts/{contact_id}/history

Request

  • Base URL: https://api.sendseven.com
  • URL: https://api.sendseven.com/api/v1/contacts/{contact_id}/history
  • Auth: HTTP bearer

Path parameters

contact_idstring required

Query parameters

typesstring[] nullable

Filter by event_type. Repeatable. Allowed values: conversation, flow_run, flow_message, message, scheduler, ticket_summary. Omit to include all known types (current FE behavior). Use message for the flat all-messages stream that powers the Messages view mode; use scheduler for pending/fired scheduled sends; use ticket_summary for the contact's AI conversation summaries (editable KB documents).

date_fromstring nullable

ISO8601 lower bound on each source's sort column.

date_tostring nullable

ISO8601 upper bound on each source's sort column.

qstring nullable

Substring filter (LIKE %q%). Ignored when shorter than 2 chars. Matches conversation.subject + last message text, flow.name, and message.text depending on the event_type.

cursorstring nullable

Opaque cursor from a previous page's next_cursor.

page_sizeinteger

Page size (default 50, max 100).

Response

Successful Response

next_cursorstring nullable

Opaque cursor for the next page. null when has_more is False.

has_moreboolean

Whether more rows exist after this page.

Changes

No recorded changes to this operation across all 3 revisions of this API.