Outcomes
Create Outcome
Create an outcome script for your organization.
POST
/
v1
/
dispositions
Create Outcome
curl --request POST \
--url https://api.bland.ai/v1/dispositions \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"name": "<string>",
"script": "<string>",
"metadata": {}
}
'import requests
url = "https://api.bland.ai/v1/dispositions"
payload = {
"name": "<string>",
"script": "<string>",
"metadata": {}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', script: '<string>', metadata: {}})
};
fetch('https://api.bland.ai/v1/dispositions', 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.bland.ai/v1/dispositions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'script' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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.bland.ai/v1/dispositions"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"script\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
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.post("https://api.bland.ai/v1/dispositions")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"script\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/dispositions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"script\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "51b2f9ae-4162-4880-9920-10308352c55f",
"org_id": "9b51b0fc-4127-446a-9ffb-21b1f006e6b5",
"name": "appointment_outcome",
"metadata": {},
"snippet_id": "44468cc3-d31f-47cd-8cff-94476b904a28",
"snippet_version": 1,
"created_at": "2026-10-26T15:04:12.381Z",
"updated_at": "2026-10-26T15:04:12.381Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/name: Expected string to match '^[a-zA-Z_]+$'\"]}"
}
]
}
An outcome is a JavaScript script that reads a finished call or SMS conversation and returns structured data. The API calls outcomes dispositions. Pass outcome IDs in
Docs for agents: llms.txt
disposition_ids on Send Call or Send SMS, and they run when the conversation ends. See Outcomes for how they work.
Outcomes are available on enterprise plans. Creating, updating, deleting and running an outcome requires the Owner, Admin or Operator role. Dispositions on V2 agents are a separate feature with their own endpoints.
Headers
string
required
Your API key for authentication.
Body Parameters
string
required
A name for the outcome. 1 to 100 characters, letters and underscores only (for example,
appointment_outcome).string
required
The JavaScript source, up to 200,000 characters. The script exports a The request body is the same JSON that Call Details returns for that call. Scripts can’t make network calls: a script that uses
fetch handler, reads the call from the request body and returns a JSON response:export default {
async fetch(request) {
const call = await request.json();
return Response.json({
booked: call.summary?.includes("booked") ?? false,
minutes: call.call_length,
});
},
};
fetch(), XMLHttpRequest or WebSocket is rejected with a 400.object
default:"{}"
Any key-value data you want stored with the outcome.
Response
object
The new outcome.
Show Outcome fields
Show Outcome fields
string
The outcome ID.
string
The organization that owns the outcome.
string
The outcome name.
object
The metadata you stored with the outcome.
string
The ID of the stored script.
integer
The script version. Starts at
1 and goes up each time you update the script.string
When the outcome was created (ISO 8601).
string
When the outcome was last updated (ISO 8601).
null | array
null on success, otherwise an array of error objects.{
"data": {
"id": "51b2f9ae-4162-4880-9920-10308352c55f",
"org_id": "9b51b0fc-4127-446a-9ffb-21b1f006e6b5",
"name": "appointment_outcome",
"metadata": {},
"snippet_id": "44468cc3-d31f-47cd-8cff-94476b904a28",
"snippet_version": 1,
"created_at": "2026-10-26T15:04:12.381Z",
"updated_at": "2026-10-26T15:04:12.381Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/name: Expected string to match '^[a-zA-Z_]+$'\"]}"
}
]
}
Docs for agents: llms.txt
Was this page helpful?
⌘I
Create Outcome
curl --request POST \
--url https://api.bland.ai/v1/dispositions \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"name": "<string>",
"script": "<string>",
"metadata": {}
}
'import requests
url = "https://api.bland.ai/v1/dispositions"
payload = {
"name": "<string>",
"script": "<string>",
"metadata": {}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', script: '<string>', metadata: {}})
};
fetch('https://api.bland.ai/v1/dispositions', 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.bland.ai/v1/dispositions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'script' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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.bland.ai/v1/dispositions"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"script\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
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.post("https://api.bland.ai/v1/dispositions")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"script\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/dispositions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"script\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "51b2f9ae-4162-4880-9920-10308352c55f",
"org_id": "9b51b0fc-4127-446a-9ffb-21b1f006e6b5",
"name": "appointment_outcome",
"metadata": {},
"snippet_id": "44468cc3-d31f-47cd-8cff-94476b904a28",
"snippet_version": 1,
"created_at": "2026-10-26T15:04:12.381Z",
"updated_at": "2026-10-26T15:04:12.381Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "Invalid request body",
"ext": "{\"errors\":[\"/name: Expected string to match '^[a-zA-Z_]+$'\"]}"
}
]
}