Create engagement

View as Markdown
Creates a new `CALL` or `MEETING` engagement by ingesting either a media recording from an external URL or a structured transcript timeline. **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`). **Recording imports:** Provide `media_url` when you want AskElephant to fetch and transcribe a recording. The 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. **Transcript-only imports:** If you do not have recording media, omit `media_url` and provide `transcript_timeline`. The timeline must include declared speakers plus timed transcript entries whose `speaker_index` values reference those speakers. **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. **Owner participant:** Optionally mark exactly one participant with `is_owner: true` to assign engagement ownership to that user instead of the API-key-associated user. The marked participant must resolve to an active AskElephant user in the authenticated workspace. Resolution matches `email` first, then `phone`; users with `INACTIVE` or `NOT_INVITED` roles are not valid targets. When exactly one `is_owner: true` participant resolves successfully, the created engagement's `owner_user_id` and downstream processing use that user as owner and host. When no participant has `is_owner: true`, ownership defaults to the user associated with the API key or OAuth credential. Requests with more than one `is_owner: true` participant, or with a single owner participant that cannot resolve to an active workspace user, return HTTP `400` and do not ingest media, persist an engagement, or publish processing events. API keys or OAuth credentials without an associated user may create an engagement only when a valid explicit owner participant is provided. **Timestamps:** If `start_at` is omitted, the current server time is used. When `transcript_timeline` is provided, `end_at` is derived from the largest `transcript_timeline.entries[].end_seconds` value, even if `media_url` is also supplied. For media-only imports (no timeline), `end_at` 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.

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).

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.

media_urlstringOptionalformat: "uri"

Publicly accessible HTTPS URL pointing to the audio or video recording. Required unless transcript_timeline is provided for a structured transcript-only import. 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.

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_timelineobjectOptional

Structured transcript timeline for transcript-only engagement imports. Use this when you already have diarized transcript turns and no recording media. Each entry references a declared speaker by speaker_index; entry and sentence time ranges must be non-negative, no longer than 7 days, and sentence windows must stay within their parent entry window.

external_urlstringOptional<=2048 characters

Optional URL linking back to this engagement in the originating system (e.g. a dialer’s call detail page). Accepts https://, http://, and custom app deep-link schemes such as wavv://call/123. Dangerous schemes (javascript:, data:, vbscript:, blob:, file:) are rejected. The value is stored as-is and returned in API responses and webhook payloads.

transcript_textstringOptional<=900000 charactersDeprecated

Deprecated. Use structured transcript_timeline for transcript imports. If provided, stored alongside the media recording; the media will still be processed through the transcription pipeline. 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
idstringformat: "^ngmt_[A-Za-z0-9]+$"
titlestring
engagement_typeenum
processing_statusenum
is_privateboolean
Indicates whether the engagement is marked private in AskElephant.
created_atdatetime
updated_atdatetime
transcript_timelineobject

Structured transcript timeline returned by POST /v2/engagements. When no structured timeline exists yet, this is returned as an empty transcript timeline with no speakers or entries. For read-after-create retrieval, use GET /v2/engagements/{engagement_id}/transcript_timeline.

descriptionstring
data_sourcestring
is_internalboolean
engagement_atdatetime
start_atdatetime
end_atdatetime
duration_secondsinteger
meeting_urlstringformat: "uri"
external_urlstring

URL linking back to this engagement in the originating external system (e.g. a dialer’s call detail page). Accepts https://, http://, and custom app deep-link schemes such as wavv://call/123. Present only when the engagement was created with an external_url value.

crm_associationobject
CRM record linked to this engagement. Present when the engagement has been matched to a CRM record via integration or API.
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