Update Disposition API

PUT

dispositions

{disposition_id}

cURL

curl --request PUT \
  --url https://api.bolna.ai/dispositions/{disposition_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "Next Step Agreed",
  "question": "<string>",
  "category": "Conversion",
  "category_id": "9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42",
  "system_prompt": "<string>",
  "model": "gpt-4.1-mini",
  "is_subjective": true,
  "is_objective": true,
  "subjective_type_config": {
    "pattern": "^\\d{10}$",
    "description": "10-digit phone number"
  },
  "objective_options": [
    {
      "value": "interested",
      "condition": "Customer expressed genuine interest and agreed to a next step",
      "sub_options": "<array>"
    }
  ]
}
'

import requests

url = "https://api.bolna.ai/dispositions/{disposition_id}"

payload = {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Next Step Agreed",
    "question": "<string>",
    "category": "Conversion",
    "category_id": "9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42",
    "system_prompt": "<string>",
    "model": "gpt-4.1-mini",
    "is_subjective": True,
    "is_objective": True,
    "subjective_type_config": {
        "pattern": "^\d{10}$",
        "description": "10-digit phone number"
    },
    "objective_options": [
        {
            "value": "interested",
            "condition": "Customer expressed genuine interest and agreed to a next step",
            "sub_options": "<array>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    name: 'Next Step Agreed',
    question: '<string>',
    category: 'Conversion',
    category_id: '9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42',
    system_prompt: '<string>',
    model: 'gpt-4.1-mini',
    is_subjective: true,
    is_objective: true,
    subjective_type_config: {pattern: '^\d{10}$', description: '10-digit phone number'},
    objective_options: [
      {
        value: 'interested',
        condition: 'Customer expressed genuine interest and agreed to a next step',
        sub_options: '<array>'
      }
    ]
  })
};

fetch('https://api.bolna.ai/dispositions/{disposition_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/dispositions/{disposition_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'name' => 'Next Step Agreed',
    'question' => '<string>',
    'category' => 'Conversion',
    'category_id' => '9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42',
    'system_prompt' => '<string>',
    'model' => 'gpt-4.1-mini',
    'is_subjective' => true,
    'is_objective' => true,
    'subjective_type_config' => [
        'pattern' => '^\\d{10}$',
        'description' => '10-digit phone number'
    ],
    'objective_options' => [
        [
                'value' => 'interested',
                'condition' => 'Customer expressed genuine interest and agreed to a next step',
                'sub_options' => '<array>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/dispositions/{disposition_id}"

	payload := strings.NewReader("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"Next Step Agreed\",\n  \"question\": \"<string>\",\n  \"category\": \"Conversion\",\n  \"category_id\": \"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42\",\n  \"system_prompt\": \"<string>\",\n  \"model\": \"gpt-4.1-mini\",\n  \"is_subjective\": true,\n  \"is_objective\": true,\n  \"subjective_type_config\": {\n    \"pattern\": \"^\\\\d{10}$\",\n    \"description\": \"10-digit phone number\"\n  },\n  \"objective_options\": [\n    {\n      \"value\": \"interested\",\n      \"condition\": \"Customer expressed genuine interest and agreed to a next step\",\n      \"sub_options\": \"<array>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.bolna.ai/dispositions/{disposition_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"Next Step Agreed\",\n  \"question\": \"<string>\",\n  \"category\": \"Conversion\",\n  \"category_id\": \"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42\",\n  \"system_prompt\": \"<string>\",\n  \"model\": \"gpt-4.1-mini\",\n  \"is_subjective\": true,\n  \"is_objective\": true,\n  \"subjective_type_config\": {\n    \"pattern\": \"^\\\\d{10}$\",\n    \"description\": \"10-digit phone number\"\n  },\n  \"objective_options\": [\n    {\n      \"value\": \"interested\",\n      \"condition\": \"Customer expressed genuine interest and agreed to a next step\",\n      \"sub_options\": \"<array>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/dispositions/{disposition_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"Next Step Agreed\",\n  \"question\": \"<string>\",\n  \"category\": \"Conversion\",\n  \"category_id\": \"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42\",\n  \"system_prompt\": \"<string>\",\n  \"model\": \"gpt-4.1-mini\",\n  \"is_subjective\": true,\n  \"is_objective\": true,\n  \"subjective_type_config\": {\n    \"pattern\": \"^\\\\d{10}$\",\n    \"description\": \"10-digit phone number\"\n  },\n  \"objective_options\": [\n    {\n      \"value\": \"interested\",\n      \"condition\": \"Customer expressed genuine interest and agreed to a next step\",\n      \"sub_options\": \"<array>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Disposition updated successfully",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "message": "Disposition copy created and linked to agent",
  "id": "9ab12c34-5678-4321-b3fc-7d852f33caf1"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

Scoped vs. Unscoped Mode

Scoped mode (recommended) — `agent_id` provided

The API checks whether the disposition is exclusive to the specified agent (i.e., not shared with other agents):

Case 1: Disposition is exclusive to this agent → Edit in place. Returns 200 OK.
Case 2: Disposition is shared → Copy-on-write. A new private copy is created for this agent, and the agent is re-linked to the copy. The original disposition is unchanged. Returns 201 Created.

A 201 response means a new disposition ID was created. If you’re storing the disposition ID (e.g., in your own database), update your reference to the new ID returned in the response. The original disposition_id now belongs to other agents; your agent uses the new copy.

Unscoped mode — no `agent_id`

Admins can update any disposition in place.
Non-admin users can only update dispositions they own.

Moving a Disposition Between Categories

Send the new category in the update body:

category_id (preferred) — the ID of an existing category attached to the agent.
category — a category name, resolved against the agent’s attached categories; an unmatched name creates a fresh category.

Send at most one of the two — a payload with both fails with a 400 error. Copy-on-write behavior is unchanged: the category placement applies to whichever disposition row the update produces. When the move empties the source category, the emptied category is deleted automatically. See Extraction Categories for category lifecycle rules.

Authorizations

Authorization

string

header

required

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

Path Parameters

disposition_id

string<uuid>

required

The ID of the disposition to update.

Body

application/json

Fields to update on the disposition.

Request body for updating a disposition. All fields are optional — only included fields are changed.

agent_id

string<uuid>

If provided, enables scoped (copy-on-write) mode.

name

string

New display name.

Example:

"Next Step Agreed"

question

string

Updated LLM evaluation prompt.

Response

Disposition updated in place

Standard response for create/update operations on a single disposition.

message

string

Example:

"Disposition created successfully"

string<uuid>

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

category_id

string<uuid>

ID of the extraction category the disposition belongs to.

Example:

"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42"

cURL

curl --request PUT \
  --url https://api.bolna.ai/dispositions/{disposition_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "Next Step Agreed",
  "question": "<string>",
  "category": "Conversion",
  "category_id": "9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42",
  "system_prompt": "<string>",
  "model": "gpt-4.1-mini",
  "is_subjective": true,
  "is_objective": true,
  "subjective_type_config": {
    "pattern": "^\\d{10}$",
    "description": "10-digit phone number"
  },
  "objective_options": [
    {
      "value": "interested",
      "condition": "Customer expressed genuine interest and agreed to a next step",
      "sub_options": "<array>"
    }
  ]
}
'

import requests

url = "https://api.bolna.ai/dispositions/{disposition_id}"

payload = {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Next Step Agreed",
    "question": "<string>",
    "category": "Conversion",
    "category_id": "9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42",
    "system_prompt": "<string>",
    "model": "gpt-4.1-mini",
    "is_subjective": True,
    "is_objective": True,
    "subjective_type_config": {
        "pattern": "^\d{10}$",
        "description": "10-digit phone number"
    },
    "objective_options": [
        {
            "value": "interested",
            "condition": "Customer expressed genuine interest and agreed to a next step",
            "sub_options": "<array>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    name: 'Next Step Agreed',
    question: '<string>',
    category: 'Conversion',
    category_id: '9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42',
    system_prompt: '<string>',
    model: 'gpt-4.1-mini',
    is_subjective: true,
    is_objective: true,
    subjective_type_config: {pattern: '^\d{10}$', description: '10-digit phone number'},
    objective_options: [
      {
        value: 'interested',
        condition: 'Customer expressed genuine interest and agreed to a next step',
        sub_options: '<array>'
      }
    ]
  })
};

fetch('https://api.bolna.ai/dispositions/{disposition_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/dispositions/{disposition_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'name' => 'Next Step Agreed',
    'question' => '<string>',
    'category' => 'Conversion',
    'category_id' => '9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42',
    'system_prompt' => '<string>',
    'model' => 'gpt-4.1-mini',
    'is_subjective' => true,
    'is_objective' => true,
    'subjective_type_config' => [
        'pattern' => '^\\d{10}$',
        'description' => '10-digit phone number'
    ],
    'objective_options' => [
        [
                'value' => 'interested',
                'condition' => 'Customer expressed genuine interest and agreed to a next step',
                'sub_options' => '<array>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/dispositions/{disposition_id}"

	payload := strings.NewReader("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"Next Step Agreed\",\n  \"question\": \"<string>\",\n  \"category\": \"Conversion\",\n  \"category_id\": \"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42\",\n  \"system_prompt\": \"<string>\",\n  \"model\": \"gpt-4.1-mini\",\n  \"is_subjective\": true,\n  \"is_objective\": true,\n  \"subjective_type_config\": {\n    \"pattern\": \"^\\\\d{10}$\",\n    \"description\": \"10-digit phone number\"\n  },\n  \"objective_options\": [\n    {\n      \"value\": \"interested\",\n      \"condition\": \"Customer expressed genuine interest and agreed to a next step\",\n      \"sub_options\": \"<array>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.bolna.ai/dispositions/{disposition_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"Next Step Agreed\",\n  \"question\": \"<string>\",\n  \"category\": \"Conversion\",\n  \"category_id\": \"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42\",\n  \"system_prompt\": \"<string>\",\n  \"model\": \"gpt-4.1-mini\",\n  \"is_subjective\": true,\n  \"is_objective\": true,\n  \"subjective_type_config\": {\n    \"pattern\": \"^\\\\d{10}$\",\n    \"description\": \"10-digit phone number\"\n  },\n  \"objective_options\": [\n    {\n      \"value\": \"interested\",\n      \"condition\": \"Customer expressed genuine interest and agreed to a next step\",\n      \"sub_options\": \"<array>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/dispositions/{disposition_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"Next Step Agreed\",\n  \"question\": \"<string>\",\n  \"category\": \"Conversion\",\n  \"category_id\": \"9b2e8f10-4c7d-4e2a-9f31-6a8d5c1b0e42\",\n  \"system_prompt\": \"<string>\",\n  \"model\": \"gpt-4.1-mini\",\n  \"is_subjective\": true,\n  \"is_objective\": true,\n  \"subjective_type_config\": {\n    \"pattern\": \"^\\\\d{10}$\",\n    \"description\": \"10-digit phone number\"\n  },\n  \"objective_options\": [\n    {\n      \"value\": \"interested\",\n      \"condition\": \"Customer expressed genuine interest and agreed to a next step\",\n      \"sub_options\": \"<array>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Disposition updated successfully",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "message": "Disposition copy created and linked to agent",
  "id": "9ab12c34-5678-4321-b3fc-7d852f33caf1"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

Overview

Agents

Calls

Executions

Tasks

Batches

Workflows

Workflow Campaigns

Workflow Executions

Inbound

Phone Numbers

Knowledgebases

Dispositions

Extraction Categories

Providers

Sub-Accounts

Voice

User

SIP Trunks (BYOT)

Violations

Legacy APIs

Update Disposition API

Scoped vs. Unscoped Mode

Scoped mode (recommended) — `agent_id` provided

Unscoped mode — no `agent_id`

Moving a Disposition Between Categories

Authorizations

Path Parameters

Body

Response

​Scoped vs. Unscoped Mode

​Scoped mode (recommended) — agent_id provided

​Unscoped mode — no agent_id

​Moving a Disposition Between Categories

Authorizations

Path Parameters

Body

Response

Scoped vs. Unscoped Mode

Scoped mode (recommended) — `agent_id` provided

Unscoped mode — no `agent_id`

Moving a Disposition Between Categories