Carom · Calendar events · API reference

#The calendar event object

Returned by every calendar event endpoint. List and retrieve responses carry the same fields. A timed event sets start_datetime and end_datetime; an all-day event sets all_day_start_date and all_day_end_date instead, and leaves the other pair null.

Attributes

idstring · uuid

Unique identifier for the event.
namestring · nullable

The event’s title.
descriptionstring · nullable

The event’s description as written in the calendar.
locationstring · nullable
statusstring · nullable

The provider’s status for the event. tentative occurs only on Google calendars. Cancelled events are not returned.

confirmedtentative
calendar_idsarray of strings · uuid · nullable

Every calendar the event appears on. The same meeting on two teammates’ calendars is one event.
time_zonestring · nullable

The IANA zone the event was scheduled in, such as America/Los_Angeles, as the calendar provider reported it. The start and end times are in UTC regardless.
start_datetimestring · date-time · nullable

When a timed event starts. Null for an all-day event.
end_datetimestring · date-time · nullable

When a timed event ends. Null for an all-day event.
all_day_start_datestring · date · nullable

The first day of an all-day event. Null for a timed event.
all_day_end_datestring · date · nullable

The day after the last day of an all-day event. A one-day event on September 18 ends on 2026-09-19.
attendeesarray of objects · nullable

Everyone invited, including the organizer.
Show 9 child attributesHide child attributes
- idstring · uuid
- email_addressstring · nullable
- display_namestring · nullable
  The attendee’s name as the calendar provider gave it. Null when the provider has none.
- organizerboolean · nullable
  True for the attendee who organized the event.
- responsestring · nullable
  
  The attendee’s reply to the invitation. Null when they haven’t replied.
  
  accepteddeclinedtentative
- optionalboolean · nullable
  Whether the organizer marked the attendee optional.
- responded_atstring · date-time · nullable
- contactcontact · nullable
  
  The contact with this email address, when one is visible to your key. When several match, a global contact is preferred.
- calendar_event_idstring · uuid · nullable
calendarsarray of calendars · nullable

The calendars in calendar_ids that are visible to your key.
meeting_transcriptobject · nullable

A summary of the meeting’s transcript, or null when there is none. The spoken lines are not included; fetch them with Retrieve a transcript.
Show 5 child attributesHide child attributes
- idstring · uuid
- sourcestring
- summarystring · nullable
  As on the transcript.
- entry_countinteger
  Number of spoken lines.
- analyzed_atstring · date-time · nullable
  When Carom wrote the summary. Null until then.
tasksarray of tasks · nullable

Tasks attached to this event that are visible to your key.
commentsarray of comments · nullable

Comments your team has left on this event.
tagsarray of tags · nullable

Tags applied to this event.
created_atstring · date-time · nullable

When Carom first imported the event.
updated_atstring · date-time · nullable

The calendar event object

{
  "id": "0536399a-56d2-420b-be01-5405977017de",
  "name": "Wildgrove renewal review",
  "description": "Walk through the 2027 renewal terms and the Oakland expansion.",
  "location": "Harborline office, 3rd floor",
  "status": "confirmed",
  "calendar_ids": ["eaa47c21-17fa-456b-a381-db96b0191f5b"],
  "time_zone": "America/Los_Angeles",
  "start_datetime": "2026-09-22T17:00:00.000Z",
  "end_datetime": "2026-09-22T17:45:00.000Z",
  "all_day_start_date": null,
  "all_day_end_date": null,
  "attendees": [
    {
      "id": "de87624f-3440-4f9d-a245-3e938a3cbc14",
      "email_address": "dana@harborline.example",
      "display_name": "Dana Whitfield",
      "organizer": true,
      "response": "accepted",
      "optional": false,
      "responded_at": null,
      "contact": null,
      "calendar_event_id": "0536399a-56d2-420b-be01-5405977017de"
    },
    {
      "id": "8bd4aed8-fba5-4ac7-bba0-404146a52d46",
      "email_address": "priya@wildgrove.example",
      "display_name": "Priya Natarajan",
      "organizer": false,
      "response": "tentative",
      "optional": false,
      "responded_at": null,
      "contact": {
        "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
        "name": "Priya Natarajan",
        …
      },
      "calendar_event_id": "0536399a-56d2-420b-be01-5405977017de"
    }
  ],
  "calendars": [
    {
      "id": "eaa47c21-17fa-456b-a381-db96b0191f5b",
      "name": "dana@harborline.example",
      "description": null,
      "access_role": "owner",
      "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
      "sync_enabled": true,
      "primary": true
    }
  ],
  "meeting_transcript": null,
  "tasks": [
    {
      "id": "7c6dc498-83ce-44ae-8afd-8b1a3641ed8f",
      "description": "Send Priya the renewal redline before the call",
      "due": "2026-09-21",
      …
    }
  ],
  "comments": [],
  "tags": [
    {
      "id": "0f1e2d3c-4b5a-4968-8776-655443322110",
      "name": "Customer",
      "color": "#66b185"
    }
  ],
  "created_at": "2026-09-08T17:21:04.748Z",
  "updated_at": "2026-09-10T09:02:47.914Z"
}

get/calendar_events Read key

#List calendar events

Returns the events visible to your key in order of start time, earliest first, 100 per page unless you set limit. Filter by date range, calendar, the people or records involved, or tags. This list pages in both directions: next_cursor moves forward and prev_cursor moves back.

Query parameters

start_datestring

An ISO 8601 date or date-time. With end_date, returns events that overlap the range. On its own, returns events that start on or after it. A date without a time means midnight in your key’s user’s time zone when start_date is sent alone, and midnight UTC when it is sent with end_date.
end_datestring

An ISO 8601 date or date-time. Returns events that start on or before it. A date without a time means midnight UTC at the start of that day, so timed events later that day aren’t included; send the next day, or a date-time, to include them.
calendar_idstring · uuid

Only events on this calendar.
scopestring

Restrict by whose calendars an event is on. personal is the calendars of your key’s user’s own mailboxes; subscribed is every calendar that user follows; shared is events visible to your key that are on none of those, such as events shared with that user. Omit to include everything.

personalsubscribedshared
slicestring

A preset view, in terms of your key’s user. tasked: events with an incomplete task of that user’s. by-you: events organized from one of that user’s mailboxes. to-you: events someone else organized that one of that user’s mailboxes was invited to. pinned-contacts: events attended by a contact that user has pinned.

taskedby-youto-youpinned-contacts
querystring

Match against event names and descriptions. Up to 500 characters.
contact_idstring · uuid

Only events this contact was invited to, matched by any of their email addresses.
organization_idstring · uuid

Only events attended by someone employed at this organization.
deal_idstring · uuid

Only events attended by the deal’s counterparty: its contact, or the people at its organization.
space_idstring · uuid

Only events in this space.
tagsstring

Comma-separated tag ids, at most 50.
tag_operatorstringdefault any

Whether an event must carry any of the given tags, or all of them.

anyall
limitintegerdefault 100

Events per page, from 1 to 250. Values outside that range are clamped to it.
next_cursorstring

Opaque token from the previous page’s page_info.next_cursor. Omit to start from the earliest matching event. See Pagination.
prev_cursorstring

Token from page_info.prev_cursor, to fetch the page of earlier events before this one. Takes precedence over next_cursor.

Returns

collectionobject

A page of events and the cursors around it.
Show 4 child attributesHide child attributes
- recordsarray of calendar events
  
  Up to limit events, earliest first.
- page_infopage info
  
  Send next_cursor back while has_more_after is true, or prev_cursor while has_more_before is true, as the parameter of the same name.
- filtersobject · nullable
  
  The filters that were applied, echoed back.
- slice_keystring · nullable
  
  The slice that was applied.

Errors

400invalid_requestA parameter is malformed, for example a date that isn’t ISO 8601 or more than 50 tag ids.
400invalid_cursorThe cursor is unreadable, or came from another list or sort.
404record_not_foundcontact_id, organization_id, deal_id, or space_id names a record that isn’t visible to your key.

get/calendar_events

curl "https://api.carom.io/calendar_events?start_date=2026-09-21&end_date=2026-09-27&scope=personal" \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "collection": {
    "records": [
      {
        "id": "0536399a-56d2-420b-be01-5405977017de",
        "name": "Wildgrove renewal review",
        "start_datetime": "2026-09-22T17:00:00.000Z",
        "end_datetime": "2026-09-22T17:45:00.000Z",
        …
      },
      {
        "id": "b871441e-4505-4fd8-8494-c23ed45b4ce0",
        "name": "Board offsite",
        "start_datetime": null,
        "end_datetime": null,
        "all_day_start_date": "2026-09-24",
        "all_day_end_date": "2026-09-26",
        …
      }
    ],
    "page_info": {
      "limit": 100,
      "next_cursor": null,
      "prev_cursor": null,
      "has_more_after": false,
      "has_more_before": false
    },
    "filters": {
      "start_date": "2026-09-21",
      "end_date": "2026-09-27",
      "scope": "personal"
    },
    "slice_key": null
  }
}

get/calendar_events/{id} Read key

#Retrieve a calendar event

Returns a single event with its attendees, calendars, tasks, comments, tags, and transcript summary.

Path parameters

idstring · uuidrequired

The event’s id.

Returns

The calendar event object, wrapped in calendar_event.

Errors

404record_not_foundNo event with that id is visible to your key.

get/calendar_events/{id}

curl https://api.carom.io/calendar_events/0536399a-56d2-420b-be01-5405977017de \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "calendar_event": {
    "id": "0536399a-56d2-420b-be01-5405977017de",
    "name": "Wildgrove renewal review",
    "status": "confirmed",
    "start_datetime": "2026-09-22T17:00:00.000Z",
    "end_datetime": "2026-09-22T17:45:00.000Z",
    "attendees": [
      {
        "email_address": "priya@wildgrove.example",
        "response": "tentative",
        …
      }
    ],
    "meeting_transcript": null,
    …
  }
}

get/calendar_events/count Read key

#Count calendar events

Counts the events that List calendar events would return for the same filters, without fetching them. The count is never capped, so exact is true, capped is false, and cap is null.

Query parameters

start_date, end_date, calendar_id, scope, slice, query, contact_id, organization_id, deal_id, space_id, tags, tag_operator

As on List calendar events.

Returns

countcount
Show 4 child attributesHide child attributes
- totalinteger
- exactboolean
- cappedboolean
- capinteger · nullable

Errors

400invalid_requestA parameter is malformed, for example a date that isn’t ISO 8601.
404record_not_foundcontact_id, organization_id, deal_id, or space_id names a record that isn’t visible to your key.

get/calendar_events/count

curl "https://api.carom.io/calendar_events/count?contact_id=1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41" \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "count": {
    "total": 12,
    "exact": true,
    "capped": false,
    "cap": null
  }
}

get/calendar_events/{id}/discussion Read key

#Retrieve a calendar event’s discussion

Returns the comments your team has left on this event together with the comments on the people and organizations it involves, grouped into scopes. The first scope is always the event itself, even with no comments yet. An attendees scope holds the contacts among the attendees, excluding your own teammates, and an organizations scope holds the organizations that employ them; each appears only when someone has commented on one of its records.

Path parameters

idstring · uuidrequired

Returns

discussionobject
Show 1 child attributeHide child attributes
- scopesarray of objects
  
  In display order, the event’s own scope first.
  Show 6 child attributesHide child attributes
  - keystring
    
    calendar_eventattendeesorganizations
  - labelstring
    A display label, such as This meeting.
  - unitstring
    A plural noun for the records in the scope: meetings, people, or organizations.
  - primaryboolean
    True for the event’s own scope.
  - total_commentsinteger
  - recordsarray of objects
    
    The records in the scope that have comments, most recently discussed first. Records that aren’t visible to your key are left out and not counted.
    
    Show 6 child attributesHide child attributes
    
    keystring
    
    record_typestring
    calendar_event, contact, or organization.
    
    record_idstring · uuid
    
    namestring · nullable
    
    total_commentsinteger
    
    commentsarray of comments
    Oldest first.

Errors

404record_not_foundNo event with that id is visible to your key.

get/calendar_events/{id}/discussion

curl https://api.carom.io/calendar_events/0536399a-56d2-420b-be01-5405977017de/discussion \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "discussion": {
    "scopes": [
      {
        "key": "calendar_event",
        "label": "This meeting",
        "unit": "meetings",
        "primary": true,
        "total_comments": 0,
        "records": [
          {
            "key": "calendar_event-0536399a-56d2-420b-be01-5405977017de",
            "record_type": "calendar_event",
            "record_id": "0536399a-56d2-420b-be01-5405977017de",
            "name": "Wildgrove renewal review",
            "total_comments": 0,
            "comments": []
          }
        ]
      },
      {
        "key": "attendees",
        "label": "Attendees",
        "unit": "people",
        "primary": false,
        "total_comments": 1,
        "records": [
          {
            "key": "contact-1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "record_type": "contact",
            "record_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "name": "Priya Natarajan",
            "total_comments": 1,
            "comments": [
              {
                "id": "d979bb0b-ef8b-4355-8eee-48e1f7f64902",
                "body": "Priya wants the renewal numbers before the 15th. She's out the week after.",
                "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
                "created_at": "2026-09-03T18:44:12.639Z",
                …
              }
            ]
          }
        ]
      }
    ]
  }
}

#The brief object

A brief is a short, AI-written note to read before a meeting: what the meeting is for, the state of the relationship, what is unresolved, and what to raise. Carom writes it from the correspondence, tasks, and comments your team has with the attendees who are contacts.

Each time a brief is generated, Carom adds a new version. A version is private to the user who generated it unless it was created with shared set to true, in which case everyone who can see the event can read it.

Attributes

idstring · uuid
subject_typestring

Always calendar_event.
subject_idstring · uuid

The event the brief is about.
statusstring

The generation status. content is filled in when the status reaches ready.

pendinggeneratingreadyfailed
sharedboolean

Whether everyone who can see the event can read this version. False means only its generator can.
generated_by_user_idstring · uuid

The user who requested this version.
contentobject · nullable

The brief itself. Null until status is ready. Every field is empty when the source material doesn’t support it.
Show 6 child attributesHide child attributes
- purposestring
  What the meeting is for, in one or two sentences.
- sentimentobject
  
  The tone of the relationship: a value and a one-sentence note. unknown means the material gave no signal.
  
  positiveneutralnegativemixedunknown
- outstandingstring
  What is unresolved going into the meeting.
- historystring
  One sentence on past and upcoming meetings with the same people.
- peoplearray of objects
  One entry per attendee who is a contact, each with a name and a note.
- raisearray of strings
  Short points to raise or watch for.
errorstring · nullable

A short code for why generation failed, when status is failed.
citationsarray of objects

The records the brief was written from that are visible to your key, each with a type (contact, thread, task, or comment) and an id. Empty until the brief is ready.
hidden_source_countinteger

How many source records aren’t visible to your key. Their identities are never returned.
created_atstring · date-time
updated_atstring · date-time

The brief object

{
  "id": "8f2e6968-fdfc-41b3-8e80-d48fd7d87ffc",
  "subject_type": "calendar_event",
  "subject_id": "0536399a-56d2-420b-be01-5405977017de",
  "status": "ready",
  "shared": true,
  "generated_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
  "content": {
    "purpose": "Review the 2027 renewal terms and scope the Oakland expansion.",
    "sentiment": {
      "value": "positive",
      "note": "Priya replies quickly and has asked twice about adding properties."
    },
    "outstanding": "The renewal redline has not been sent, and pricing for the four Oakland buildings is still open.",
    "history": "Third meeting since July; the last one covered onboarding for the Fremont sites.",
    "people": [
      {
        "name": "Priya Natarajan",
        "note": "Decision maker for the renewal. Wants numbers in writing before she commits."
      }
    ],
    "raise": [
      "Confirm the renewal start date",
      "Ask who signs off on the Oakland budget"
    ]
  },
  "error": null,
  "citations": [
    { "type": "contact", "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41" },
    { "type": "thread", "id": "dfb41d12-01d4-4981-9c9a-4ac29e195715" }
  ],
  "hidden_source_count": 1,
  "created_at": "2026-09-18T15:10:32.299Z",
  "updated_at": "2026-09-18T15:10:51.266Z"
}

get/calendar_events/{calendar_event_id}/brief Read key

#List briefs

Returns every version of the event’s brief that your key can read, newest first: all shared versions, plus the private versions generated by your key’s user. Returns every version in one response; the list isn’t paginated.

Path parameters

calendar_event_idstring · uuidrequired

Returns

briefsarray of briefs

Empty when no brief has been generated.

Errors

404record_not_foundNo event with that id is visible to your key.

get/calendar_events/{calendar_event_id}/brief

curl https://api.carom.io/calendar_events/0536399a-56d2-420b-be01-5405977017de/brief \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "briefs": [
    {
      "id": "8f2e6968-fdfc-41b3-8e80-d48fd7d87ffc",
      "status": "ready",
      "shared": true,
      "created_at": "2026-09-18T15:10:32.299Z",
      …
    },
    {
      "id": "c544745b-b22b-4f1e-8e8b-1c4adf10ab88",
      "status": "ready",
      "shared": false,
      "created_at": "2026-09-11T20:02:15.290Z",
      …
    }
  ]
}

post/calendar_events/{calendar_event_id}/brief Write key

#Generate a brief

Starts writing a new version of the event’s brief and returns it at once with status pending and HTTP 202. Generation runs in the background. Poll List briefs until the version’s status is ready or failed.

Requests are limited to one per event every two minutes and 30 per user per hour. A limited request returns rate_limited with a Retry-After header in seconds.

Path parameters

calendar_event_idstring · uuidrequired

Request body application/json

sharedbooleandefault false

true to let everyone who can see the event read this version. The body may be omitted.

Returns

The new brief object with status pending, wrapped in brief.

Errors

403permission_deniedYour account’s subscription doesn’t currently allow generating briefs.
404record_not_foundNo event with that id is visible to your key.
429rate_limitedA brief for this event was requested in the past two minutes, or your key’s user has requested 30 briefs in the past hour.

post/calendar_events/{calendar_event_id}/brief

curl https://api.carom.io/calendar_events/0536399a-56d2-420b-be01-5405977017de/brief \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "shared": true }'

Response202

{
  "brief": {
    "id": "32ab7d3b-ba42-4554-9e78-7c408d20f934",
    "subject_type": "calendar_event",
    "subject_id": "0536399a-56d2-420b-be01-5405977017de",
    "status": "pending",
    "shared": true,
    "generated_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "content": null,
    "error": null,
    "citations": [],
    "hidden_source_count": 0,
    "created_at": "2026-09-19T14:03:26.354Z",
    "updated_at": "2026-09-19T14:03:26.354Z"
  }
}

get/calendar_events/{calendar_event_id}/transcript Read key

#Retrieve a transcript

Returns the transcript of a meeting: every line spoken, in order, and a summary Carom writes after analyzing it. A meeting has at most one transcript, and anyone who can see the event can read it.

An event visible to your key that has no transcript returns no_transcript. Check meeting_transcript on the calendar event first to avoid the request.

Path parameters

calendar_event_idstring · uuidrequired

Returns

meeting_transcriptobject
Show 12 child attributesHide child attributes
- idstring · uuid
- calendar_event_idstring · uuid
- sourcestring
  
  Where the transcript came from.
  
  google_meetmicrosoft_teamsupload
- languagestring · nullable
- summarystring · nullable
  
  Two to four short paragraphs separated by a blank line. Each sentence carries one Markdown link of the form [phrase](entry:<id>), where the id is the entry the sentence draws on. Null until analyzed_at is set.
- entry_countinteger
- started_atstring · date-time · nullable
- ended_atstring · date-time · nullable
- analyzed_atstring · date-time · nullable
  When Carom wrote the summary.
- created_atstring · date-time
- updated_atstring · date-time
- entriesarray of objects
  
  One per spoken line, in order.
  Show 7 child attributesHide child attributes
  - idstring · uuid
  - positioninteger
    The line’s place in the transcript, counting from 0.
  - speaker_namestring · nullable
  - speaker_emailstring · nullable
    As the source reported it. Not linked to a contact; match it against the attendees’ email_address.
  - textstring
  - started_atstring · date-time · nullable
  - ended_atstring · date-time · nullable

Errors

404no_transcriptThe event is visible to your key but has no transcript.
404record_not_foundNo event with that id is visible to your key.

get/calendar_events/{calendar_event_id}/transcript

curl https://api.carom.io/calendar_events/a4aa17fa-d75a-445e-a1db-22b41bce0909/transcript \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "meeting_transcript": {
    "id": "5648cd5b-fabe-438b-b354-000afaed0e61",
    "calendar_event_id": "a4aa17fa-d75a-445e-a1db-22b41bce0909",
    "source": "google_meet",
    "language": "en",
    "summary": "Priya confirmed [Wildgrove will add the four Oakland buildings](entry:0bd03f2f-11fe-4b36-a6e3-b1a88bb4f228) once the renewal is signed.",
    "entry_count": 214,
    "started_at": "2026-09-03T16:00:12.683Z",
    "ended_at": "2026-09-03T16:41:55.774Z",
    "analyzed_at": "2026-09-03T16:49:08.086Z",
    "created_at": "2026-09-03T16:47:30.550Z",
    "updated_at": "2026-09-03T16:49:08.086Z",
    "entries": [
      {
        "id": "10471029-7a53-4157-b596-e338010b7426",
        "position": 0,
        "speaker_name": "Dana Whitfield",
        "speaker_email": "dana@harborline.example",
        "text": "Thanks for making time. I wanted to start with Oakland.",
        "started_at": "2026-09-03T16:00:12.683Z",
        "ended_at": "2026-09-03T16:00:17.026Z"
      },
      {
        "id": "0bd03f2f-11fe-4b36-a6e3-b1a88bb4f228",
        "position": 1,
        "speaker_name": "Priya Natarajan",
        "speaker_email": "priya@wildgrove.example",
        "text": "Once the renewal is signed we'd bring all four Oakland buildings over.",
        "started_at": "2026-09-03T16:00:19.130Z",
        "ended_at": "2026-09-03T16:00:25.429Z"
      },
      …
    ]
  }
}