The Meeting object

Property	Description	Editable?
id	Vitally's unique ID for the Meeting	`id` is not editable via REST API
externalId	Your unique ID for the Meeting	`externalId` is only settable on create
title	The title of the Meeting	`title` is editable via REST API
description	The description or body of the Meeting	`description` is editable via REST API
location	The location of the Meeting	`location` is editable via REST API
startDate	Date-only start value for the Meeting (when time is not applicable)	`startDate` is not editable via REST API
startDateTime	ISO 8601 datetime for when the Meeting starts	`startDateTime` is editable via REST API
startTimeZone	Timezone for the Meeting's start time (e.g. `utc`)	`startTimeZone` is not editable via REST API
endDate	Date-only end value for the Meeting (when time is not applicable)	`endDate` is not editable via REST API
endDateTime	ISO 8601 datetime for when the Meeting ends	`endDateTime` is editable via REST API
endTimeZone	Timezone for the Meeting's end time (e.g. `utc`)	`endTimeZone` is not editable via REST API
externalStatus	Status of the Meeting as reported by the external source (e.g. `cancelled`)	`externalStatus` is not editable via REST API
recordingUrl	URL to the Meeting recording	`recordingUrl` is editable via REST API
recordingUrlFormatted	Formatted version of the recording URL, if available	`recordingUrlFormatted` is not editable via REST API
joiningInstructionsUri	URI for joining the Meeting (e.g. a dial-in page link)	`joiningInstructionsUri` is not editable via REST API
videoConferenceUri	Direct video conference link for the Meeting	`videoConferenceUri` is not editable via REST API
phoneConferenceNumbers	Array of phone conference dial-in numbers for the Meeting	`phoneConferenceNumbers` is not editable via REST API
conferenceSolution	The conferencing platform used (e.g. Zoom, Google Meet)	`conferenceSolution` is not editable via REST API
summary	A summary of the Meeting	`summary` is editable via REST API
keyPoints	An array of key point strings from the Meeting	`keyPoints` is editable via REST API
riskAssessment	A risk assessment string associated with the Meeting	`riskAssessment` is editable via REST API
source	Name of the integration that created the Meeting (e.g. `gong`). `null` if not created by an integration.	`source` is not editable via REST API
participants	An array of Meeting Participant objects. At least one must be a `userId` participant whose User is linked to an account or organization.	`participants` are editable via the participants endpoints
accounts	Array of Vitally Account objects associated with the Meeting, resolved from participants	`accounts` is not editable via REST API
organizations	Array of Vitally Organization objects associated with the Meeting, resolved from participants	`organizations` is not editable via REST API
notes	Array of Note objects linked to the Meeting	`notes` is not editable via REST API
tasks	Array of Task objects linked to the Meeting	`tasks` is not editable via REST API
traits	A key-value JSON object of custom Meeting traits	`traits` are editable via REST API
archivedAt	Datetime the Meeting was archived	`archivedAt` is set when meetings are archived via the DELETE endpoint

The Meeting Participant object

Each participant in the participants array includes the following fields in responses:

Property	Description	Editable?
id	Vitally's unique ID for the participant record	`id` is not editable via REST API
email	The participant's email address	`email` is not editable via REST API
type	The participant's role: `organizer` or `attendee`	`type` is not editable via REST API
responseStatus	The participant's response: `needsAction`, `accepted`, `tentative`, or `declined`	`responseStatus` is not editable via REST API
vitallyUser	If the participant is a Vitally admin/teammate, their resolved `{ id, name, email, licenseStatus }` object. `null` for customer users.	`vitallyUser` is not editable via REST API
user	If the participant is a customer User in Vitally, their resolved User object including `id`, `name`, `email`, `traits`, and other User properties. `null` for Vitally admin participants.	`user` is not editable via REST API

When creating or adding a participant, each participant object in the request requires the following fields.

For each participant, provide exactly one of the following to identify them:

Field	Type	Description
userId	`string`	The customer User's `externalId` in Vitally
vitallyUserId	`string`	Vitally's internal ID for a Vitally admin/teammate
email	`string`	Email address of an external attendee not in Vitally

Each participant also requires the following:

Field	Type	Description
type	`string`	Required. The participant's role: `organizer` or `attendee`
responseStatus	`string`	(optional) `needsAction`, `accepted`, `tentative`, or `declined`
isOrganizer	`boolean`	(optional) Defaults to `true` when `type` is `organizer`

The Meeting Transcript object

Property	Description	Editable?
id	Vitally's unique ID for the Transcript	`id` is not editable via REST API
meetingId	The ID of the Meeting this Transcript belongs to	`meetingId` is not editable via REST API
transcript	An array of monologue objects. Each monologue contains a `speaker` (with `externalId`, `email`, and `name`) and a `sentences` array (each with `text`, `startTime`, and `endTime`). The `speaker.externalId` is an arbitrary, stable key used to correlate speakers across monologues within a single transcript — it is not Vitally's system-wide external ID and is not looked up against any Vitally user record. Any consistent string value works: `"speaker1"`, a Gong `speakerId`, or even an email address. The value just needs to be consistent within a given transcript submission.	`transcript` is replaceable via the POST transcript endpoint
createdAt	Datetime the Transcript was created	`createdAt` is not editable via REST API
updatedAt	Datetime the Transcript was last updated	`updatedAt` is not editable via REST API

Replace {subdomain} in the endpoints below with your Vitally subdomain.

You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io)

List Meetings GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings

Paginated list of Meetings for the authenticated owner, by default ordered by updatedAt descending. Can also be scoped to an Account or Organization using the nested routes below.

Query Params (see Pagination)

Param	Type	Description
limit	`number`	(optional) The number of items to return. Max is 100.
from	`string`	(optional) The cursor returned from a previous request
archived	`boolean`	(optional) If `true`, returns only archived meetings. Defaults to active meetings only.
sortBy	`string`	(optional) Field to sort results by

Example Requests

GET https://{subdomain}.rest.vitally.io/resources/meetings?limit=10&from=cursor

GET https://{subdomain}.rest.vitally.io/resources/meetings?archived=true

Example Response

{
    "results": [
        {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "externalId": "meeting-1",
            "title": "Q1 Business Review",
            "description": "Quarterly review of goals and KPIs.",
            "startDate": null,
            "startDateTime": "2026-01-10T17:00:00.000Z",
            "startTimeZone": "utc",
            "endDate": null,
            "endDateTime": "2026-01-10T18:00:00.000Z",
            "endTimeZone": "utc",
            "externalStatus": null,
            "location": "Zoom",
            "phoneConferenceNumbers": [],
            "joiningInstructionsUri": null,
            "videoConferenceUri": null,
            "conferenceSolution": null,
            "recordingUrlFormatted": null,
            "riskAssessment": null,
            "keyPoints": null,
            "summary": null,
            "participants": [
                {
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "vitallyUser": {
                        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "name": "Bertram Gilfoyle",
                        "email": "gilfoyle@your-org.vitally.io",
                        "licenseStatus": "active"
                    },
                    "user": null,
                    "email": "gilfoyle@your-org.vitally.io",
                    "responseStatus": "accepted",
                    "type": "organizer"
                },
                {
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "vitallyUser": null,
                    "user": {
                        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "createdAt": "2025-10-23T22:59:35.075Z",
                        "updatedAt": "2026-04-09T06:18:47.559Z",
                        "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "name": "Customer Name",
                        "email": "customer@example.com",
                        "avatar": null,
                        "traits": {},
                        "firstKnown": "2025-07-24T22:56:07.716Z",
                        "lastSeenTimestamp": null,
                        "lastInboundMessageTimestamp": null,
                        "lastOutboundMessageTimestamp": null,
                        "npsLastScore": null,
                        "npsLastFeedback": null,
                        "npsLastRespondedAt": null,
                        "unsubscribedFromConversations": false,
                        "unsubscribedFromConversationsAt": null,
                        "deactivatedAt": null,
                        "joinDate": "2025-07-24T22:56:07.716Z"
                    },
                    "email": "customer@example.com",
                    "responseStatus": "accepted",
                    "type": "attendee"
                }
            ],
            "accounts": [
                {
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "name": "Example Account",
                    ...
                }
            ],
            "organizations": [
                {
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "name": "Example Organization",
                    ...
                }
            ],
            "notes": [],
            "tasks": [],
            "traits": {}
        }
    ],
    "next": "...xZDExYmEifQ=="
}

List Meetings For An Account GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/meetings

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/accounts/:accountId/meetings

Paginated list of Meetings for a given Account, ordered by updatedAt descending.

Request Params

Property	Type	Description
accountId	`string`	The Account ID assigned by Vitally

Example Request

GET https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/meetings?limit=10&from=cursor

List Meetings For An Organization GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/meetings

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/organizations/:organizationId/meetings

Paginated list of Meetings for a given Organization, ordered by updatedAt descending.

Request Params

Property	Type	Description
organizationId	`string`	The Organization ID assigned by Vitally

Example Request

GET https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/meetings?limit=10&from=cursor

Create A Meeting POST

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings

Creates a new Meeting. If an externalId is provided and already exists, the Meeting is updated.

Request Body

Property	Type	Description
title	`string`	Required The title of the Meeting
participants	`array`	Required At least one participant required. At least one must be a `userId` participant whose User is linked to an account or organization. See Participant object for field details.
externalId	`string`	Required Your unique ID for the Meeting. Used to check for existing Meetings.
description	`string`	The description or body of the Meeting
location	`string`	The location of the Meeting
startDateTime	`string`	Start date and time of the Meeting
endDateTime	`string`	End date and time of the Meeting
recordingUrl	`string`	URL to the Meeting recording
summary	`string`	A summary of the Meeting
keyPoints	`array`	An array of key point strings from the Meeting
riskAssessment	`string`	A risk assessment for the Meeting
source	`string`	Integration source identifier (e.g. `gong`)
traits	`object`	Custom field values keyed by field path
transcript	`array`	Optionally create the transcript in the same request. See transcript format for details.

Errors

400 — No participants, empty participants array, or no participant is a user linked to an account or organization.
422 — Schema validation failure (missing title, unknown field, etc.).

Example Request

POST https://{subdomain}.rest.vitally.io/resources/meetings
{
  "title": "Q1 Business Review",
  "externalId": "meeting-q1",
  "description": "Quarterly review of goals and KPIs.",
  "location": "Zoom",
  "startDateTime": "2026-05-01T17:00:00.000Z",
  "endDateTime": "2026-05-01T18:00:00.000Z",
  "summary": "Discussed Q1 performance and roadmap priorities.",
  "keyPoints": ["Onboarding complete", "Expansion opportunity identified"],
  "riskAssessment": "Low",
  "source": "gong",
  "participants": [
    {
      "vitallyUserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "organizer"
    },
    {
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "attendee",
      "responseStatus": "accepted"
    }
  ],
  "traits": {}
}

Example Response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "meeting-q1",
  "title": "Q1 Business Review",
  "description": "Quarterly review of goals and KPIs.",
  "startDate": null,
  "startDateTime": "2026-05-01T17:00:00.000Z",
  "startTimeZone": "utc",
  "endDate": null,
  "endDateTime": "2026-05-01T18:00:00.000Z",
  "endTimeZone": "utc",
  "externalStatus": null,
  "location": "Zoom",
  "phoneConferenceNumbers": [],
  "joiningInstructionsUri": null,
  "videoConferenceUri": null,
  "conferenceSolution": null,
  "recordingUrlFormatted": null,
  "riskAssessment": "Low",
  "keyPoints": ["Onboarding complete", "Expansion opportunity identified"],
  "summary": "Discussed Q1 performance and roadmap priorities.",
  "source": "gong",
  "participants": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "vitallyUser": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "Bertram Gilfoyle",
        "email": "gilfoyle@your-org.vitally.io",
        "licenseStatus": "active"
      },
      "user": null,
      "email": "gilfoyle@your-org.vitally.io",
      "responseStatus": null,
      "type": "organizer"
    },
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "vitallyUser": null,
      "user": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "createdAt": "2025-10-23T22:59:35.075Z",
        "updatedAt": "2026-04-09T06:18:47.559Z",
        "externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "Customer Name",
        "email": "customer@example.com",
        "avatar": null,
        "traits": {},
        "firstKnown": "2025-07-24T22:56:07.716Z",
        "lastSeenTimestamp": null,
        "lastInboundMessageTimestamp": null,
        "lastOutboundMessageTimestamp": null,
        "npsLastScore": null,
        "npsLastFeedback": null,
        "npsLastRespondedAt": null,
        "unsubscribedFromConversations": false,
        "unsubscribedFromConversationsAt": null,
        "deactivatedAt": null,
        "joinDate": "2025-07-24T22:56:07.716Z"
      },
      "email": "customer@example.com",
      "responseStatus": "accepted",
      "type": "attendee"
    }
  ],
  "accounts": [...],
  "organizations": [...],
  "notes": [],
  "tasks": [],
  "traits": {}
}

Get A Meeting GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id

Returns a single Meeting by Vitally id or externalId. Also returns archived meetings.

Request Params

Property	Type	Description
id	`string`	The Meeting ID assigned by Vitally, or the Meeting's `externalId`

Example Requests

GET https://{subdomain}.rest.vitally.io/resources/meetings/:id

GET https://{subdomain}.rest.vitally.io/resources/meetings/:externalId

Errors

404 — Meeting not found. Double check the ID.

Update A Meeting PUT

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id

Updates an existing, non-archived Meeting. Accepts the Meeting's Vitally id or externalId. All body fields are optional.

Request Body (all fields optional)

Property	Type	Description
title	`string`	The title of the Meeting
description	`string`	The description or body of the Meeting
location	`string`	The location of the Meeting
startDateTime	`string`	Start date and time of the Meeting
endDateTime	`string`	End date and time of the Meeting
recordingUrl	`string`	URL to the Meeting recording
summary	`string`	A summary of the Meeting
keyPoints	`array`	An array of key point strings from the Meeting
riskAssessment	`string`	A risk assessment for the Meeting
traits	`object`	Custom field values keyed by field path

Errors

400 — Meeting is archived.
404 — Meeting not found. Double check the ID.

Example Request

PUT https://{subdomain}.rest.vitally.io/resources/meetings/:id
{
  "summary": "Updated summary after follow-up.",
  "riskAssessment": "Medium"
}

Delete A Meeting DELETE

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id

Deletes a Meeting. Accepts the Meeting's Vitally id or externalId.

Request Params

Property	Type	Description
id	`string`	The Meeting ID assigned by Vitally, or the Meeting's `externalId`

Add A Participant POST

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id/participants

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id/participants

Adds a participant to an existing, non-deleted Meeting.

Request Body

Identifier (exactly one required)

Field	Type	Description
userId	`string`	The customer User's `externalId` in Vitally
vitallyUserId	`string`	Vitally's internal ID for a Vitally admin/teammate
email	`string`	Email address of an external attendee not in Vitally

Additional fields

Field	Type	Description
type	`string`	Required. The participant's role: `organizer` or `attendee`
responseStatus	`string`	(optional) `needsAction`, `accepted`, `tentative`, or `declined`
isOrganizer	`boolean`	(optional) Defaults to `true` when `type` is `organizer`

Errors

400 — Meeting is archived, multiple identifiers provided, no identifier provided, or userId/vitallyUserId not found.
404 — Meeting not found. Double check the ID.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/meetings/:id/participants
{
  "email": "newattendee@example.com",
  "type": "attendee",
  "responseStatus": "accepted"
}

Remove A Participant DELETE

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id/participants/:participantId

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id/participants/:participantId

Removes a participant from a Meeting. The participantId can be retrieved from the id field of any participant object in the participants array returned by a Get A Meeting or Create A Meeting response.

Request Params

Property	Type	Description
id	`string`	The Meeting ID assigned by Vitally
participantId	`string`	The ID of the participant to remove

Errors

400 — Meeting is archived, or removing this participant would leave the meeting with no participant linked to an account or organization.
404 — Meeting not found, participant not found, or participant belongs to a different meeting. Double check the IDs.

List Transcripts GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetingTranscripts

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetingTranscripts

Paginated list of all Meeting Transcripts, ordered by updatedAt descending.

Query Params (see Pagination)

Param	Type	Description
limit	`number`	(optional) The number of items to return. Max is 100.
from	`string`	(optional) The cursor returned from a previous request
sortBy	`string`	(optional) Field to sort results by

Example Request

GET https://{subdomain}.rest.vitally.io/resources/meetingTranscripts?limit=10&from=cursor

Get A Transcript GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetingTranscripts/:id

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetingTranscripts/:id

Returns a single Transcript by its own ID. The id for a specific Transcript can be retrieved from the id field returned in the response from Create / Replace A Meeting's Transcript or List Transcripts. Note that this is the Transcript's own ID, it's not the Meeting's id.

Errors

400 — id is not a valid UUID.
404 — Transcript not found.

Get A Meeting's Transcript GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id/transcript

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id/transcript

Returns the Transcript for a specific Meeting. Accepts the Meeting's Vitally id or externalId.

Errors

404 — Meeting not found, or Meeting has no transcript. Double check the Meeting ID.

Example Request

GET https://{subdomain}.rest.vitally.io/resources/meetings/:id/transcript

Create / Replace A Meeting's Transcript POST

If the caller doesn't already know the Meeting id, use Find a Meeting and Update / Create Transcript POST instead.

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/meetings/:id/transcript

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/:id/transcript

Creates or replaces the Transcript for a Meeting. Accepts the Meeting's Vitally id or externalId.

Request Body

Property	Type	Description
transcript	`array`	Required An array of monologue objects

Each monologue in the transcript array should follow this format:

{
  "speaker": {
    "externalId": "string (required)",
    "email": "string",
    "name": "string"
  },
  "sentences": [
    {
      "text": "string",
      "startTime": 0,
      "endTime": 1000
    }
  ]
}

Errors

400 — Meeting is deleted, or body fails schema validation.
404 — Meeting not found. Double check the ID.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/meetings/:id/transcript
{
  "transcript": [
    {
      "speaker": {
        "externalId": "speaker-001",
        "email": "monica@example.com",
        "name": "Monica Piper"
      },
      "sentences": [
        {
          "text": "Thanks for joining today's business review.",
          "startTime": 0,
          "endTime": 3200
        },
        {
          "text": "Let's start with a look at your onboarding progress.",
          "startTime": 3500,
          "endTime": 7000
        }
      ]
    }
  ]
}

Example Response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "meetingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "createdAt": "2026-01-10T18:30:00.000Z",
  "updatedAt": "2026-01-10T18:30:00.000Z",
  "transcript": [
    {
      "speaker": {
        "externalId": "speaker-001",
        "email": "monica@example.com",
        "name": "Monica Piper"
      },
      "sentences": [
        {
          "text": "Thanks for joining today's business review.",
          "startTime": 0,
          "endTime": 3200
        },
        {
          "text": "Let's start with a look at your onboarding progress.",
          "startTime": 3500,
          "endTime": 7000
        }
      ]
    }
  ]
}

Find a Meeting POST

Read-only. Matches a recording or calendar hint to an existing Meeting and returns ranked candidates. Does not create a Meeting or write a transcript.

US Data Center:

https://{subdomain}.rest.vitally.io/resources/meetings/find

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/find

Request Body (at least one match hint required)

Property	Type	Description
calendarEventId	string	The meeting's unique ID in the calendar, sent exactly as the provider stores it. Google: the event id — for a recurring meeting, the occurrence id (`{baseId}_{YYYYMMDDTHHMMSSZ}`), not the series master id. Outlook: the event's Microsoft Graph `iCalUId`; prefer `iCalUID` below if you only have the cross-system invite UID.
iCalUID	string	The calendar event UID per RFC 5545 §3.8.4.7. For a recurring invite every occurrence shares the same UID, so include `startDateTime` to match the specific dated occurrence.
recorderCallId	string, max 100	The external recorder's call id. Finds a Meeting already linked to that recording. Not a calendar id.
startDateTime	ISO-8601	The Meeting's scheduled start, not the first spoken word. Required when `calendarEventId`, `iCalUID`, and `recorderCallId` are all omitted.
endDateTime	ISO-8601	The Meeting's scheduled end.
title	string	Heuristic match when there's no calendar id.
participantEmails	array of strings	Heuristic match when there's no calendar id.
conferenceUrl	string	Heuristic match when there's no calendar id.
timeWindowMinutes	integer, 1-60, default 15	Window around `startDateTime` used by the heuristic match.

Response

200 — { matches }. Each item has meeting, confidence (exact, high, medium, low), and matchReasons. Empty array means no match. A valid request always returns 200, including no match.
400 — No match hint sent, or startDateTime omitted when the calendar/recorder hints were also omitted.

Notes

Doesn't write anything — no Meeting creation, recording link, or transcript storage.
calendarEventId must match character-for-character what Vitally already has from calendar sync.
Archived meetings are not matched.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/meetings/find
{
  "calendarEventId": "abc123_20260115T170000Z",
  "startDateTime": "2026-01-15T17:00:00.000Z"
}

Example Response

{
  "matches": [
    { "meeting": { "id": "...", "title": "Q1 Business Review" }, "confidence": "exact", "matchReasons": ["calendarEventId"] }
  ]
}

Find a Meeting and Update / Create Transcript POST

Matches a Meeting, then creates or updates its REST API transcript. Can create the Meeting first when createIfNotFound is true and nothing matched. If the caller already knows the Meeting id, the existing Create / Replace A Meeting's Transcript endpoint above still works — use this one when the caller has match hints instead of an id, or wants Vitally to create the Meeting.

US Data Center:

https://{subdomain}.rest.vitally.io/resources/meetings/transcript

EU Data Center:

https://{subdomain}.rest.vitally-eu.io/resources/meetings/transcript

Request Body

Property	Type	Description
transcript	array	Required. Same monologue shape as the existing transcript endpoint. Sentence `startTime`/`endTime` are milliseconds from the Meeting start, not absolute timestamps.
calendarEventId / iCalUID	string	Same as in POST /resources/meetings/find.
recorderCallId	string, max 100	Used for idempotent retries. Send it on every upload, including a `meetingId` retry, so repeat uploads resolve to the same Meeting.
startDateTime	ISO-8601	Required when `calendarEventId`, `iCalUID`, `recorderCallId`, and `meetingId` are all omitted, and whenever `createIfNotFound` is true.
endDateTime	ISO-8601	The Meeting's scheduled end.
title	string	Heuristic match when there's no calendar id. Optional when creating a Meeting (defaults to "Imported meeting").
participantEmails	array of strings	Heuristic match when there's no calendar id. Required in practice when `createIfNotFound` is true.
conferenceUrl	string	Heuristic match when there's no calendar id.
timeWindowMinutes	integer, 1-60, default 15	Window around `startDateTime`.
meetingId	string	Skips matching, uploads to this Meeting directly. Typical retry after a `409`.
createIfNotFound	boolean	Creates a Meeting only when matching returns zero candidates — not on ambiguous or medium/low-confidence matches.

Response

201 — One exact/high match; Meeting or transcript created. Body: meeting, transcript, meetingCreated, transcriptCreated, optionally confidence/matchReasons.
200 — One exact/high match; transcript already existed and was replaced. Same body as 201.
409 — More than one exact/high match, or only medium/low matches. Body: error, matches. Retry with meetingId set to one of the returned matches.
404 — No Meeting matched. Retry with createIfNotFound: true only if creating a Meeting is acceptable.
400 — createIfNotFound true but no participant resolved to an external User, startDateTime missing when required, or target Meeting archived.

Notes

Doesn't replace a Gong, calendar, or Vitally Recorder transcript — stored under the REST API integration. A repeat upload replaces only that REST API transcript. The UI prefers it when more than one transcript exists.
speaker.externalId is a stable key within that transcript only — not a Vitally user, team member, or Meeting id. Speaker-to-participant linking uses speaker.email, then name.
createIfNotFound requires startDateTime and at least one participantEmails address that already exists as an external User. Owned-domain (internal) emails alone aren't enough.
createIfNotFound does nothing on a 409 — resolve ambiguous/low-confidence matches with meetingId instead.
Archived meetings can't receive a transcript.
A Meeting created this way uses recorderCallId (or a generated id) as its external id. Send a calendar event id too if you have one, so later uploads can match on that key.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/meetings/transcript
{
  "recorderCallId": "granola-note-abc123",
  "startDateTime": "2026-01-15T17:00:00.000Z",
  "participantEmails": ["customer@example.com"],
  "transcript": [
    { "speaker": { "externalId": "speaker-001", "email": "monica@example.com", "name": "Monica Piper" },
      "sentences": [{ "text": "Thanks for joining today's business review.", "startTime": 0, "endTime": 3200 }] }
  ]
}

Example Response

{
  "meeting": { "id": "...", "title": "Q1 Business Review" },
  "transcript": { "id": "..." },
  "meetingCreated": false,
  "transcriptCreated": true,
  "confidence": "exact",
  "matchReasons": ["calendarEventId"]
}

REST API: Meetings

The Meeting object

The Meeting Participant object

The Meeting Transcript object

List Meetings GET

List Meetings For An Account GET

List Meetings For An Organization GET

Create A Meeting POST

Get A Meeting GET

Update A Meeting PUT

Delete A Meeting DELETE

Add A Participant POST

Remove A Participant DELETE

List Transcripts GET

Get A Transcript GET

Get A Meeting's Transcript GET

Create / Replace A Meeting's Transcript POST

Find a Meeting POST

Find a Meeting and Update / Create Transcript POST