API ReferenceEngagements

Create engagement

View as Markdown
Creates a new `CALL` or `MEETING` engagement by ingesting a media recording from an external URL. **Idempotency:** The `external_id` field is the idempotency key. Submitting the same `external_id` again — even with a different `source_system` — returns the existing engagement with a `200` response instead of creating a duplicate. If you need per-source-system uniqueness, prefix your `external_id` (e.g. `my-crm:12345`). **Media requirements:** The `media_url` must be a publicly accessible HTTPS URL serving an `audio/*` or `video/*` content type. HTTP URLs, private/internal IP addresses, and non-media content types are rejected with a `422` error. The server fetches the media synchronously during request processing, so the URL must remain accessible for the duration of the request. **Workflow control:** Set `run_workflows` to `true` for normal automation (workflow triggers, recap emails) or `false` to suppress workflows (e.g. for historical imports). Transcription, summarization, and tagging always run regardless. **Timestamps:** If `start_at` is omitted, the current server time is used. The `ended_at` timestamp is derived automatically from the media duration during processing. This operation requires the `engagements:write` scope.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
typeenumRequired

The engagement type. Only CALL and MEETING are supported for creation via the public API.

Allowed values:
titlestringRequired1-500 characters
Display title for the engagement.
source_systemstringRequired1-100 characters

Identifier for the external system that produced this recording (e.g. salesforce, custom-dialer). Stored as metadata for traceability but not part of the idempotency key — see external_id.

external_idstringRequired1-500 characters

Unique identifier for this engagement in the external system. Used as the idempotency key scoped to the workspace (not per source_system). Submitting the same external_id again — even with a different source_system — returns the existing engagement instead of creating a duplicate. If you need per-source uniqueness, prefix the ID yourself (e.g. my-crm:12345).

media_urlstringRequiredformat: "uri"

Publicly accessible HTTPS URL pointing to the audio or video recording. The server fetches this URL during request processing, so it must be reachable at call time. Requirements: must use the https scheme (no http), must not resolve to private or internal IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x, 169.254.x.x, or IPv6 link-local/loopback), and must serve an audio/* or video/* content type.

run_workflowsbooleanRequired

Controls whether downstream automations (workflow triggers, post-meeting recap emails) fire for this engagement. Set to true to enable normal automation; set to false to suppress workflows (useful for historical imports). Transcription, summarization, and tagging always run regardless of this flag.

start_atdatetimeOptional
ISO 8601 timestamp for when the engagement started. Defaults to the current server time if omitted.
is_privatebooleanOptional

Controls whether the engagement is marked as private. When true, only participants and users with engagements:private:read scope can view the engagement. Defaults to the workspace’s configured privacy behavior if omitted.

participantslist of objectsOptional
Optional list of participants in the engagement. Each participant may have a name, email, or both.
transcript_textstringOptional<=900000 characters

Optional plain-text transcript content. If provided, stored alongside the media recording. The media will still be processed through the transcription pipeline; this text serves as supplementary content. Limited to 900,000 characters and 950,000 bytes (UTF-8). Multi-byte content (e.g. CJK, emoji) may hit the byte limit before the character limit.

Response headers

X-Api-Versionstring

Response

An engagement with the same external_id already exists in this workspace. The existing engagement is returned unchanged.

objectenum
Allowed values:
idstringformat: "^ngmt_[A-Za-z0-9]+$"
titlestring
engagement_typeenum
processing_statusenum
Allowed values:
is_privateboolean
Indicates whether the engagement is marked private in AskElephant.
created_atdatetime
updated_atdatetime
descriptionstring
data_sourcestring
is_internalboolean
engagement_atdatetime
start_atdatetime
end_atdatetime
duration_secondsinteger
meeting_urlstringformat: "uri"
owner_user_idstringformat: "^usr_[A-Za-z0-9]+$"
host_user_idstringformat: "^usr_[A-Za-z0-9]+$"
transcriptstring or null

Full text transcript of the engagement. Only included when expand contains transcript.

media_urlstring or nullformat: "uri"

Temporary signed URL for downloading the engagement recording media. Only included when expand contains media_url. The URL expires after a short period.

companieslist of objects

Companies associated with this engagement. Only included when expand contains companies.

contactslist of objects

Contact participants associated with this engagement. Only included when expand contains contacts.

ownerobject or null

Workspace user who owns this engagement. Only included when expand contains owner.

action_itemslist of objects

Action items created from this engagement. Only included when expand contains action_items.

signalslist of objects

Signals (annotations) extracted from this engagement. Only included when expand contains signals.

tagslist of objects

Tags applied to this engagement. Only included when expand contains tags.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error