Contacts
Get a contact's timeline
Returns a contact's activity across all their tickets in order, including messages, calls, emails and notes. Page back with before and limit, or centre the page on one entry with at.
Requires: desk.read scope, Converse or Contacts licence.
Authorization
bearerAuth AuthorizationBearer <token>
A SautiDesk API key. An owner or admin makes it under Settings in SautiDesk for a named person and picks the scopes. The key is shown once. Send it as Authorization: Bearer <key>. It acts as that person and as nobody else.
In: header
Path Parameters
id*string
The contact's id (a UUID).
Query Parameters
cursor?string
next_cursor from the previous page. Leave it out for the first page.
limit?integer
Page size: 100 by default, 100 at most.
Response
OK
Example
{ "data": [ { "id": "3f2b8c1e-5a4d-4e7b-9c10-2d6a8e4f1b37", "ticket_id": "b1e8bf6f-7f06-4c91-96dd-a1eb7abe504b", "ticket_ref": "TCK-4471", "kind": "billing", "divider_kind": "date", "channel": "sms", "direction": "inbound", "author": "Wanjiku Mwangi", "body": "Hi Amina, your order has shipped.", "subject": "Order 1182 has not arrived", "occurred_at": "2026-10-14T08:30:00Z", "recording_seconds": 60, "no_recording_reason": "Recording is off for this number", "recording_url": "https://example.com/file", "recording_bytes": 1, "call_leg_id": "c314e328-b417-48b4-95fe-e9b71a13dede", "handled_by": "Wanjiku Mwangi", "placed_by_name": "Wanjiku Mwangi", "placed_by_system": false, "outcome": "billing", "category": "billing", "local_address": "help", "remote_address": "example", "delivery": "delivered", "delivery_error": "", "body_full": "example", "body_html_url": "https://example.com/file", "body_html_omitted": "example", "attachments": [ { "id": null, "filename": null, "content_type": null, "size": null, "content_id": null, "inline": null } ], "cc": [ "amina@example.com" ], "bcc": [ "amina@example.com" ], "to": [ "+254712345678" ], "media": { "id": "3f2b8c1e-5a4d-4e7b-9c10-2d6a8e4f1b37", "type": "billing", "mime_type": "application/pdf", "filename": "invoice-1182.pdf", "url": "https://example.com/file", "status": "open", "retention_days": 1 }, "reply_to": { "activity_id": "0d6c4f09-7095-4291-9bdb-50991c39602c", "author": "Wanjiku Mwangi", "body": "Hi Amina, your order has shipped." }, "comments": { "count": 3, "last_at": "2026-10-14T08:30:00Z", "authors": [ null ], "unread": false }, "mentions": [ "af55b8ed-074f-478d-9661-0c5ccc54d6d5" ] } ], "next_cursor": "eyJvIjoyNX0", "has_more": false}FieldTypeDescription
datarequiredobject[]idrequiredstring (uuid)ticket_idrequiredstring (uuid)The id of the ticket this is about.ticket_refrequiredstringkindrequiredstringWhat kind it is.divider_kindstring | nullchannelstring | nullThe channel to use: sms, whatsapp or email.directionstring | nullauthorrequiredstringbodyrequiredstringThe message text.subjectstringThe subject line.occurred_atrequiredstring (date-time)recording_secondsinteger | nullno_recording_reasonstring | nullrecording_urlstringrecording_bytesinteger | nullcall_leg_idstring (uuid) | nullThe id of the call leg being wrapped up.handled_bystringplaced_by_namestringplaced_by_systembooleanoutcomestringHow it ended: the name or id of one of your outcomes.categorystringThe name of the category.local_addressstringremote_addressstringdeliveryrequiredstringdelivery_errorstringbody_fullstringbody_html_urlrequiredstring | nullbody_html_omittedrequiredstring | nullattachmentsrequiredobject[]idrequiredstring (uuid)filenamerequiredstringcontent_typerequiredstringsizerequiredintegercontent_idrequiredstringinlinerequiredbooleanccrequiredstring[]Email addresses to copy on the message.bccrequiredstring[]Email addresses to copy privately.torequiredstring[]Who to send to: a phone number in international format or, for email, an address.mediaanyidrequiredstringtyperequiredstringmime_typestringfilenamestringurlstringstatusrequiredstringThe status to set.retention_daysintegerHow many days the activity log is kept before it is cleared.reply_toanyactivity_idrequiredstring (uuid)The id of the message on the ticket to forward.authorrequiredstringbodyrequiredstringThe message text.commentsanycountrequiredintegerWhat the table says about its own size, in its own words, for example 4 channels or 42 contacts. Left out when it is the number of rows.last_atrequiredstring (date-time)authorsrequiredstring (uuid)[]unreadrequiredbooleanmentionsstring (uuid)[]The ids of the teammates to notify about the comment.next_cursorrequiredstring | nullhas_morerequiredbooleancurl -X GET "https://api.sautidesk.com/v1/desk/contacts/string/timeline"