Timeline

The timeline is a feed of recent activity, newest first, drawn from several kinds of record: comments, tags being applied, email threads, files, tasks, and deals moving between stages. Use it to show what has happened lately with a person, a company, or a deal.

You choose whose activity to include. A scope selects a set of contacts, such as the ones you have pinned. A record narrows the feed to the contacts of one organization or space, to a single contact, or to one deal’s stage history. A request with neither returns an empty timeline.

#The timeline item object

One event in the feed. Every item has the same attributes; which ones are filled in depends on its type, and the rest are null.

Attributes

  • typestring

    What happened.

    commenttaggingthreadfiletaskdeal
  • idstring · uuid

    Id of the underlying record: the comment, the tagging, the thread, the attachment that carried the file, the task, or the deal’s stage change.

  • kindstring · nullable

    For deal items, what the stage change was: the deal was created, moved to another open stage, or closed. Null for other types.

    startedstage_movedwonlost
  • timestampstring · date-time

    When it happened. For a thread, the time of its latest message; for a task, when it was last updated; for a file, when the message carrying it was sent.

  • titlestring · nullable

    A short heading: the thread’s subject, the task’s assignment, or the deal’s name. Comment and Tagged for those types. Null for files.

  • descriptionstring · nullable

    A line of detail: the comment’s text, the tag that was applied, the thread’s snippet, the task’s description, or the stage change, such as Moved from Proposal sent to Negotiation. Null for files.

  • contactcontact · nullable

    The contact a comment, tagging, or task is attached to.

  • useruser · nullable

    Who wrote the comment, applied the tag, or moved the deal.

  • tagtag · nullable

    For tagging items, the tag that was applied.

  • fileobject · nullable

    For file items, the file.

    Show 5 child attributesHide child attributes
    • idstring · uuid
    • namestring · nullable
    • file_namestring · nullable
    • extensionstring · nullable
    • descriptionstring · nullable
  • dealobject · nullable

    For deal items, the deal and the stages it moved between.

    Show 7 child attributesHide child attributes
    • idstring · uuid
    • namestring
    • amountnumber · nullable
    • currencystring
    • pipeline_idstring · uuid
    • from_stageobject · nullable

      The stage the deal left, with its id, name, and position. Null when the deal was created.

    • to_stageobject

      The stage the deal entered, with the same three attributes.

  • agentstring · nullable

    For deal items, the agent whose proposal produced the stage change, such as auto_deal. Null when a person made the change, including a change they asked Carom’s chat assistant to make.

  • proposal_idstring · uuid · nullable

    The proposal behind an agent’s stage change. Look it up with Retrieve a proposal. Only the proposal’s approver can retrieve it; for anyone else that returns 404.

The timeline item object 
{
  "type": "deal",
  "id": "b5d7f9b1-3d5f-4b7d-9f1b-7d9f1b3d5f08",
  "kind": "stage_moved",
  "timestamp": "2026-09-17T15:42:10.038Z",
  "title": "Wildgrove portfolio renewal",
  "description": "Moved from Proposal sent to Negotiation",
  "deal": {
    "id": "8f2b6d4a-1c9e-4a7b-b3d5-0e6f8a2c4d17",
    "name": "Wildgrove portfolio renewal",
    "amount": 48000.0,
    "currency": "USD",
    "pipeline_id": "5e8a1c3f-7b2d-4f6e-a9c0-3d1b7e4f2a86",
    "from_stage": {
      "id": "8b3d5f7a-9c1e-4a2b-b4d6-0e8f1a3c5b77",
      "name": "Proposal sent",
      "position": 2
    },
    "to_stage": {
      "id": "4f6a8c0e-2b4d-4c6e-8f0a-3b5d7e9f1c28",
      "name": "Negotiation",
      "position": 3
    }
  },
  "agent": "auto_deal",
  "proposal_id": "c3e5a7b9-1d3f-4a5b-9c7e-2f4a6b8d0e61",
  "contact": null,
  "user": {
    "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "first_name": "Dana",
    "last_name": "Whitfield",
    …
  },
  "tag": null,
  "file": null
}
get/timeline Read key

#List timeline items

Returns up to 50 items, newest first, for the scope or record you name. Name at most one record: contact_id, organization_id, space_id, or deal_id. A record outranks scope.

To fetch the next page, pass the response’s oldest_timestamp as before.

A deal’s timeline holds only that deal’s stage changes. To read the comments on a deal, use its discussion.

Query parameters

  • scopestring

    Which contacts to include: every contact visible to your key, the contacts your key’s user has corresponded with, or the contacts they have pinned.

    allinteractedpinned
  • contact_idstring · uuid

    Only this contact’s activity.

  • organization_idstring · uuid

    Activity for the contacts employed at this organization that your key can see, plus stage changes on the organization’s deals.

  • space_idstring · uuid

    Activity for the contacts in this space that your key can see.

  • deal_idstring · uuid

    Only this deal’s stage changes.

  • typesstring

    Comma-separated kinds of activity to include. Omit to include all of them. The names are plural, unlike the singular type on each item.

    commentstaggingsthreadsfilestasksdeals
  • beforestring · date-time

    Return only items older than this time. To fetch the next page, pass the previous response’s oldest_timestamp.

Returns

  • itemsarray of timeline items

    Up to 50 items, newest first.

  • has_moreboolean

    True when this page is full, meaning older items may exist. Fetch them by passing oldest_timestamp as before.

  • oldest_timestampstring · date-time · nullable

    The time of the last item, with microsecond precision. Pass it as before for the next page; use it rather than the item’s timestamp, which has only millisecond precision. Null when items is empty.

Errors

  • 400invalid_requestscope isn’t one of the listed values, before isn’t a valid time, or more than one record is named.
  • 404record_not_foundThe contact, organization, space, or deal you named isn’t visible to your key.
get/timeline 
curl "https://api.carom.io/timeline?organization_id=6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3&types=comments,deals" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "items": [
    {
      "type": "deal",
      "id": "b5d7f9b1-3d5f-4b7d-9f1b-7d9f1b3d5f08",
      "kind": "stage_moved",
      "timestamp": "2026-09-17T15:42:10.038Z",
      "title": "Wildgrove portfolio renewal",
      "description": "Moved from Proposal sent to Negotiation",
      …
    },
    {
      "type": "comment",
      "id": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",
      "kind": null,
      "timestamp": "2026-09-03T18:44:12.885Z",
      "title": "Comment",
      "description": "Priya wants the renewal numbers before the 15th. She's out the week after.",
      "deal": null,
      "agent": null,
      "proposal_id": null,
      "contact": {
        "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
        "name": "Priya Natarajan",
        …
      },
      "user": {
        "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
        "first_name": "Dana",
        "last_name": "Whitfield",
        …
      },
      "tag": null,
      "file": null
    }
  ],
  "has_more": false,
  "oldest_timestamp": "2026-09-03T18:44:12.885417Z"
}