Replace engagement tags | AskElephant

curl -X PUT https://app.askelephant.ai/api/v2/engagements/engagement_id/tags \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "tag_ids": [
    "string"
  ]
}'

{
  "object": "engagement",
  "id": "string",
  "title": "string",
  "engagement_type": "MEETING",
  "processing_status": "PENDING",
  "is_private": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "description": "string",
  "data_source": "string",
  "is_internal": true,
  "engagement_at": "2024-01-15T09:30:00Z",
  "start_at": "2024-01-15T09:30:00Z",
  "end_at": "2024-01-15T09:30:00Z",
  "duration_seconds": 1,
  "meeting_url": "string",
  "external_url": "string",
  "crm_association": {
    "object_type": "string",
    "crm_object_id": "string",
    "source": "string"
  },
  "owner_user_id": "string",
  "host_user_id": "string",
  "transcript": "string",
  "transcript_timeline": {
    "object": "transcript_timeline",
    "engagement_id": "string",
    "speakers": [
      {
        "id": "string",
        "type": "contact",
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "phone": "string",
        "speaking_percentage": 1.1,
        "sentiment": 1.1
      }
    ],
    "entries": [
      {
        "speaker": {
          "type": "contact",
          "id": "string",
          "name": "string"
        },
        "text": "string",
        "start_seconds": 1.1,
        "end_seconds": 1.1,
        "num_words": 1,
        "sentences": [
          {
            "text": "string",
            "start_seconds": 1.1,
            "end_seconds": 1.1
          }
        ]
      }
    ],
    "overall_sentiment": 1.1
  },
  "media_url": "string",
  "companies": [
    {
      "object": "engagement_company",
      "id": "string",
      "name": "string",
      "domains": [
        "string"
      ],
      "crm_association": {
        "object_type": "string",
        "crm_object_id": "string",
        "source": "string"
      }
    }
  ],
  "contacts": [
    {
      "object": "contact",
      "id": "cnt_01HQY3JMS2QAXJGX6X7CH7CM6X",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-04T18:25:00Z",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "description": "Primary customer contact for analytical projects.",
      "company": {
        "id": "string",
        "object": "string"
      },
      "emails": [
        {
          "email": "ada@analytical.engine",
          "is_primary": true
        }
      ],
      "phone_numbers": [
        {
          "phone_number": "+1-555-0100",
          "is_primary": true
        }
      ],
      "crm_association": {
        "object_type": "string",
        "crm_object_id": "string",
        "source": "string"
      },
      "time_zone": "America/Los_Angeles"
    }
  ],
  "owner": {
    "object": "user",
    "id": "string",
    "role": "OWNER",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "first_name": "string",
    "last_name": "string",
    "job_title": "string",
    "emails": [
      {
        "email": "string",
        "is_primary": true
      }
    ],
    "time_zone": "string",
    "last_activity_at": "2024-01-15T09:30:00Z"
  },
  "action_items": [
    {
      "object": "engagement_action_item",
      "id": "string",
      "title": "string",
      "description": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "due_on": "string",
      "assigned_to_user_id": "string",
      "assigned_to_user_name": "string",
      "assigned_to_user_email": "string"
    }
  ],
  "signals": [
    {
      "object": "engagement_signal",
      "id": "string",
      "annotation_definition_id": "string",
      "name": "string",
      "data_type": "string",
      "description": "string"
    }
  ],
  "tags": [
    {
      "object": "tag",
      "id": "string",
      "name": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "hex_color": "string",
      "description": "string",
      "auto_tagging_enabled": true
    }
  ]
}

Replaces the full set of tags applied to an engagement. Send an empty tag_ids array to clear all tags. Requires the engagements:write scope. Updating a private engagement also requires engagements:private:write. When the credential can also read the updated engagement, the response returns the engagement payload. Otherwise the update succeeds with 204 No Content.

Replaces the full set of tags applied to an engagement. Send an empty `tag_ids` array to clear all tags. Requires the `engagements:write` scope. Updating a private engagement also requires `engagements:private:write`. When the credential can also read the updated engagement, the response returns the engagement payload. Otherwise the update succeeds with `204 No Content`.

Authentication

AuthorizationBearer

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

Path parameters

engagement_idstringRequired

Request

This endpoint expects an object.

tag_idslist of stringsRequired

Response headers

X-RateLimit-Limitinteger

Maximum number of authenticated requests allowed for the workspace in the current 60-second window. The limit is 1000 and applies to all /api/v2 resource routes (GET, POST, PATCH, and DELETE), shared across every credential for the workspace.

X-RateLimit-Remaininginteger

Number of requests remaining in the current window before the limit is exceeded.

X-RateLimit-Resetinteger

Unix epoch seconds when the current rate-limit window resets.

X-Api-VersionstringOptional

Response

Updated engagement response.

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

descriptionstringOptional

data_sourcestringOptional

is_internalbooleanOptional

engagement_atdatetimeOptional

start_atdatetimeOptional

end_atdatetimeOptional

duration_secondsintegerOptional

meeting_urlstringOptionalformat: "uri"

external_urlstringOptional

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_associationobjectOptional

CRM record linked to this engagement. Present when the engagement has been matched to a CRM record via integration or API.

owner_user_idstringOptionalformat: "^usr_[A-Za-z0-9]+$"

host_user_idstringOptionalformat: "^usr_[A-Za-z0-9]+$"

transcriptstring or nullOptional

Aggregated engagement text as a single string. Depending on the engagement, this can include Markdown or HTML content plus extracted text from completed attachments; it is not guaranteed to contain only spoken transcript. For speaker-aware or time-aligned ingest, use GET /v2/engagements/{engagement_id}/transcript_timeline. Only included when expand contains transcript. Does not include speaker timing or structured entries; use expand=transcript_timeline for the structured timeline object.

transcript_timelineobject or nullOptional

Structured transcript timeline with timed speaker entries. Only included when expand contains transcript_timeline. Returns null when the engagement has no primary timeline or when timeline serialization fails for that engagement (the surrounding engagement response still succeeds). Requires transcript_timelines:read. Matches the object returned by GET /v2/engagements/{engagement_id}/transcript_timeline.

media_urlstring or nullOptionalformat: "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 objectsOptional

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

contactslist of objectsOptional

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

ownerobject or nullOptional

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

action_itemslist of objectsOptional

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

signalslist of objectsOptional

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

tagslist of objectsOptional

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

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error