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

# Create Disposition

> Create a disposition with an initial draft definition.

### Overview

> [!NOTE]
>
> Dispositions are enabled per organization. If your organization does not have access, these endpoints return `404`.

Creates a disposition on the agent with the supplied definition as its draft. The disposition starts `disabled` and does not run on calls until you [estimate](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-estimates.md) and [publish](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-publish.md) it. Edit the draft later with [Update Disposition Draft](https://docs.bland.ai/api-v2/patch/agents-id-dispositions-disposition-id-draft.md).

Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**agent\_id** `string` *required*

The agent's unique identifier. Must be a UUID; otherwise returns `400` with the message `agentId must be a valid UUID`. Returns `404 Agent not found` if the agent is not in your organization.

### Body Parameters

Unknown fields anywhere in the body are rejected.

**key** `string` *required*

Stable slug for the disposition, 1 to 64 characters matching `^[a-z][a-z0-9_]*$`. Unique per agent; returns `409 CONFLICT` if another live disposition on this agent already uses it. Cannot be changed after creation.

**definition** `object` *required*

The full disposition definition. Schema violations return `400 BAD_REQUEST` with message `Invalid request body` and an `ext` string listing each failing path. Rule violations (a judge pin that does not exist, a duplicate value key, a transformation that references an unknown value id) return `400 BAD_REQUEST` with message `Definition failed validation` and an `ext` string carrying `problems`, each with `valueId` and `message`. Drafts are validated less strictly than publishing: a `structured_extraction` value may omit its version pin, and judge or extractor pins may still be editable.

```json theme={null}
{
  "name": "Appointment outcome",
  "description": "Did the caller book, and did they ask for a callback?",
  "timing": "immediate",
  "values": [
    {
      "id": "c60ed698-7680-4a76-8bf9-da4de408460b",
      "key": "booked",
      "label": "Appointment booked",
      "schema": { "kind": "boolean" },
      "source": {
        "kind": "judge",
        "judgeId": "3fec6d8e-053b-4d6b-9544-4bf559a13a1a",
        "judgeVersionId": "f3a84fb2-81d9-41e7-95e3-3d1f7e44fb31",
        "execution": { "reasoningEffort": "auto", "inputSourceIds": ["transcript"] }
      }
    },
    {
      "id": "e515708f-fa72-4786-90cd-3f4d3696ffcd",
      "key": "callback_window",
      "label": "Requested callback window",
      "schema": { "kind": "string", "description": "Preferred callback time in the caller's words" },
      "source": {
        "kind": "structured_extraction",
        "extractorId": "8986922b-f300-47c5-8c5d-f506d59c82ab",
        "extractorVersionId": "8e503b95-67ca-4754-a058-d3ac7b88a217",
        "execution": { "reasoningEffort": "medium", "inputSourceIds": ["transcript"] }
      }
    }
  ],
  "transformation": {
    "version": 1,
    "root": {
      "kind": "object",
      "fields": {
        "booked": { "kind": "value", "valueId": "c60ed698-7680-4a76-8bf9-da4de408460b" },
        "callback_window": { "kind": "value", "valueId": "e515708f-fa72-4786-90cd-3f4d3696ffcd" }
      }
    }
  },
  "postCallWebhook": { "mode": "emit_followup" }
}
```

**definition object**

**name** `string` *required*

Display name, 1 to 120 characters.

**description** `string` *required*

Free-text description, up to 2000 characters. May be empty.

**timing** `string` *required*

`immediate` runs within 30 minutes of call completion. `within_24h` queues the run with a 24-hour deadline.

**values** `array` *required*

Up to 50 value objects. Each value produces one field of the result. Value `id`s and `key`s must be unique within the definition. A definition with no values can be saved but not published or tested.

**values\[].id** `string` *required*

A UUID you generate. It is the value's permanent identity: results, corrections, and the transformation all refer to it. Keep it stable across draft edits.

**values\[].key** `string` *required*

Payload field name, 1 to 64 characters matching `^[a-z][a-z0-9_]*$`. May change between drafts.

**values\[].label** `string` *required*

Human-readable label, 1 to 120 characters.

**values\[].schema** `object` *required*

The value's output shape. `kind` is one of `boolean`, `string`, `number`, `enum`, `array`, or `object`; every kind accepts an optional `description` up to 2000 characters. `string` accepts `format: "date-time"`. `enum` requires `options`: 1 to 24 entries of `{ "key", "label" }` with `key` 1 to 64 characters, `label` 1 to 120, and keys unique. `array` requires `items` (a nested schema) and accepts `minItems` (at least 0) and `maxItems` (at least 1); neither may exceed 1000 and `minItems` may not exceed `maxItems`. `object` requires `properties` (a map of names up to 64 characters to nested schemas, at most 64 of them) and `required` (unique names that all appear in `properties`). A schema may not exceed 200 nodes, 8 levels of nesting, or 64 KB.

**values\[].source** `object` *required*

How the value is produced. `kind` selects one of four shapes; the fields for each kind are listed below. A `judge` value's schema must be `boolean` or an `enum` whose keys exactly match the judge's level keys (a pass/fail judge maps to `boolean` or a two-option `pass` and `fail` enum). A `structured_extraction` value's schema must exactly match the pinned extractor's output schema. A `variable_extraction` value's schema must exactly match the `outputSchema` of the matching entry in [Get Variable Catalog](https://docs.bland.ai/api-v2/get/agents-id-dispositions-variable-catalog.md).

**values\[].source.kind** `string` *required*

One of `variable_extraction`, `structured_extraction`, `judge`, or `custom_code`.

**values\[].source.variableKey** `string`

`variable_extraction` only, required. Key of an existing variable on the agent, 1 to 128 characters matching `^[A-Za-z_][A-Za-z0-9_.-]{0,127}$`. The variable's extraction is re-run against the corrected post-call transcript. The variable must exist in the agent's current configuration.

**values\[].source.execution** `object`

For `variable_extraction`, optional `{ "reasoningEffort" }` defaulting to `auto`. For `structured_extraction` and `judge`, required `{ "reasoningEffort", "inputSourceIds" }`. `reasoningEffort` is `auto`, `low`, `medium`, or `high`. `inputSourceIds` is 1 to 8 of `transcript`, `audio_recording`, `call_metadata`, `pathway_logs`, `tool_logs`, `variables`, `agent_config`, `call_config`. An audio judge must include `audio_recording`. A structured extraction cannot combine `low` effort with `audio_recording`.

**values\[].source.extractorId** `string`

`structured_extraction` only, required. UUID of an extractor from [List Extractors](https://docs.bland.ai/api-v2/get/agents-id-dispositions-extractors.md) that is org-wide or scoped to this agent.

**values\[].source.extractorVersionId** `string`

`structured_extraction` only. UUID of a version of that extractor. Optional while drafting; required to publish or run a test, and publish requires a published (archived) version.

**values\[].source.frozen** `object`

`structured_extraction` only. Written by the server at publish time with a copy of the pinned extractor's prompt, output schema, and inference configuration. Omit it.

**values\[].source.judgeId** `string`

`judge` only, required. UUID of a judge from [Get Judge Catalog](https://docs.bland.ai/api-v2/get/agents-id-dispositions-judge-catalog.md) that is org-wide or scoped to this agent.

**values\[].source.judgeVersionId** `string`

`judge` only, required. UUID of a version of that judge. Publish and test runs require a published (archived) version; a draft may temporarily reference an editable one.

**values\[].source.snippetId** `string`

`custom_code` only, required. UUID of a code snippet owned by your organization. The snippet must be JavaScript.

**values\[].source.snippetVersion** `integer`

`custom_code` only, required. Snippet version number, at least `1`.

**values\[].source.timeoutSeconds** `integer`

`custom_code` only, required. 1 to 60.

**values\[].source.connections** `object`

`custom_code` only, required (may be `{}`). Up to 20 entries keyed by an alias matching `^[A-Za-z_][A-Za-z0-9_]{0,63}$`, each `{ "resourceId": "uuid", "integration": "optional string" }`. Resources must belong to your organization.

**values\[].source.secrets** `object`

`custom_code` only, required (may be `{}`). Up to 20 entries keyed by an alias with the same pattern, each `{ "secretId": "uuid" }`.

**values\[].source.dependencyValueIds** `array`

`custom_code` only, required (may be `[]`). Up to 20 unique value ids whose results are passed to the code. Only `variable_extraction`, `structured_extraction`, and `judge` values may be referenced; a code value cannot depend on itself or on another code value.

**transformation** `object` *required*

`{ "version": 1, "root": node }`. A node is one of `{ "kind": "value", "valueId" }`, `{ "kind": "literal", "value" }`, `{ "kind": "object", "fields": { name: node } }` with names up to 64 characters, or `{ "kind": "array", "items": [node] }` with up to 50 items. Every referenced `valueId` must exist in `values`. At most 2000 nodes.

**postCallWebhook** `object` *required*

`{ "mode": "hold" }` or `{ "mode": "emit_followup" }`. `hold` delays the call's post-call webhook until this disposition's results are ready and is only valid with `timing: "immediate"`. `emit_followup` sends results in a separate follow-up webhook.

### Response

Returns `201` on success.

**data** `object`

The new disposition summary.

**disposition object**

**id** `string`

Unique identifier for the disposition.

**agentId** `string`

The agent this disposition belongs to.

**key** `string`

The slug you supplied.

**state** `string`

Always `disabled` on a new disposition.

**publishedVersionId** `null`

Always `null` on a new disposition.

**publishedVersionNumber** `null`

Always `null` on a new disposition.

**draftRevision** `number`

Always `1` on a new disposition. Pass it as `expectedDraftRevision` on the first draft update.

**draftValueCount** `number`

Number of values in the definition you supplied.

**hasUnpublishedChanges** `boolean`

Always `true` on a new disposition.

**name** `string`

The definition's name.

**description** `string`

The definition's description.

**createdAt** `string`

ISO 8601 timestamp of creation.

**updatedAt** `string`

ISO 8601 timestamp of creation.

**errors** `null | array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "id": "cdc753be-4f30-454f-99bf-aec7ba366875",
    "agentId": "7b72e5e3-362d-4b98-acd6-6929e9ed3995",
    "key": "appointment_outcome",
    "state": "disabled",
    "publishedVersionId": null,
    "publishedVersionNumber": null,
    "draftRevision": 1,
    "draftValueCount": 2,
    "hasUnpublishedChanges": true,
    "name": "Appointment outcome",
    "description": "Did the caller book, and did they ask for a callback?",
    "createdAt": "2026-09-10T18:02:11.418Z",
    "updatedAt": "2026-09-10T18:02:11.418Z"
  },
  "errors": null
}
```

```json Invalid Body theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "Invalid request body",
      "ext": "{\"errors\":[\"/key: Expected string to match '^[a-z][a-z0-9_]*$'\"]}"
    }
  ]
}
```

```json Definition Invalid theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "Definition failed validation",
      "ext": "{\"problems\":[{\"valueId\":\"c60ed698-7680-4a76-8bf9-da4de408460b\",\"message\":\"Pinned judge version does not exist\"}]}"
    }
  ]
}
```

```json Conflict theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CONFLICT",
      "message": "A disposition with key \"appointment_outcome\" already exists"
    }
  ]
}
```

***

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.