> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Flag

> Flag a moment on an attached call.

## Overview

Flags pinpoint where on a call something went wrong. The `call_id` must already be attached as a resource on this issue, otherwise the request fails with `409 conflict` and `{ error: "call_not_attached" }`. Flag types accumulate into a reusable per-org catalog (see [List Flag Types](https://docs.bland.ai/api-v1/get/triage-flag-types.md)).

***

## Headers

**authorization** `string` *required*

Your API key for authentication.

***

## Path Parameters

**id** `string` *required*

Internal UUID of the issue.

***

## Body Parameters

**call\_id** `string` *required*

ID of the attached call this flag points at. Must already be attached as a resource on this issue.

**type** `string` *required*

Flag type. Free-form, but normalized to lower\_snake\_case before storage. Reusing a type increments its `usage_count` in [List Flag Types](https://docs.bland.ai/api-v1/get/triage-flag-types.md).

**note** `string`

Free-text note explaining why this moment was flagged. 1-4000 characters.

**node\_id** `string`

ID of the pathway node the flag is attached to, if known.

**node\_name** `string`

Display name of the pathway node, captured at flag time so the dashboard can render the node name even if the pathway later changes.

**message\_index** `integer`

Zero-based index of the message turn in the call transcript that this flag points at.

**message\_text** `string`

Verbatim text of the flagged message, captured at flag time.

***

## Response

Returns `201 Created` with the new flag.

**data** `object`

**Flag fields**

**id** `string`

Internal UUID of the flag.

**org\_id** `string`

**issue\_id** `string`

**call\_id** `string`

**type** `string`

The normalized flag type (lower\_snake\_case).

**note** `string`

Empty string if no note was provided.

**node\_id** `string | null`

**node\_name** `string | null`

**message\_index** `number | null`

**message\_text** `string | null`

**author\_id** `string`

User ID of the caller that filed the flag.

**created\_at** `string`

**errors** `null | array`

`null` on success.

```json Response theme={null}
{
  "data": {
    "id": "ad0931e4-b0e1-4bd6-a5b1-09e7c9123dba",
    "org_id": "f5b40b9e-bc05-4b8a-9af1-d8f6a8a3a201",
    "issue_id": "9bbe5547-d5b1-4b83-9f80-87c4af7c6b34",
    "call_id": "3aefc79d-1870-4514-b32b-b9212ae32bc8",
    "type": "missed_handoff",
    "note": "Agent transferred without confirming the email.",
    "node_id": null,
    "node_name": null,
    "message_index": 12,
    "message_text": "OK, transferring you now.",
    "author_id": "75c5c7da-a5d6-4e26-a51e-1ae8ef2bfa4a",
    "created_at": "2026-05-07T05:26:11.327Z"
  },
  "errors": null
}
```

```json Call Not Attached theme={null}
{
  "data": null,
  "errors": [
    { "error": "call_not_attached", "message": "Call must be attached to issue first" }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.