Start Agent Onboarding

POST

agent

onboarding

start

curl --request POST \
  --url https://api.bland.ai/v1/agent/onboarding/start \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_name": "<string>",
  "prefill": {},
  "prefill.name": "<string>",
  "prefill.first_name": "<string>",
  "prefill.last_name": "<string>",
  "prefill.email": "<string>",
  "prefill.phone": "<string>"
}
'

import requests

url = "https://api.bland.ai/v1/agent/onboarding/start"

payload = {
    "client_name": "<string>",
    "prefill": {},
    "prefill.name": "<string>",
    "prefill.first_name": "<string>",
    "prefill.last_name": "<string>",
    "prefill.email": "<string>",
    "prefill.phone": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_name: '<string>',
    prefill: {},
    'prefill.name': '<string>',
    'prefill.first_name': '<string>',
    'prefill.last_name': '<string>',
    'prefill.email': '<string>',
    'prefill.phone': '<string>'
  })
};

fetch('https://api.bland.ai/v1/agent/onboarding/start', 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/agent/onboarding/start",
  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([
    'client_name' => '<string>',
    'prefill' => [
        
    ],
    'prefill.name' => '<string>',
    'prefill.first_name' => '<string>',
    'prefill.last_name' => '<string>',
    'prefill.email' => '<string>',
    'prefill.phone' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "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.bland.ai/v1/agent/onboarding/start"

	payload := strings.NewReader("{\n  \"client_name\": \"<string>\",\n  \"prefill\": {},\n  \"prefill.name\": \"<string>\",\n  \"prefill.first_name\": \"<string>\",\n  \"prefill.last_name\": \"<string>\",\n  \"prefill.email\": \"<string>\",\n  \"prefill.phone\": \"<string>\"\n}")

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

	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/agent/onboarding/start")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_name\": \"<string>\",\n  \"prefill\": {},\n  \"prefill.name\": \"<string>\",\n  \"prefill.first_name\": \"<string>\",\n  \"prefill.last_name\": \"<string>\",\n  \"prefill.email\": \"<string>\",\n  \"prefill.phone\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/agent/onboarding/start")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"client_name\": \"<string>\",\n  \"prefill\": {},\n  \"prefill.name\": \"<string>\",\n  \"prefill.first_name\": \"<string>\",\n  \"prefill.last_name\": \"<string>\",\n  \"prefill.email\": \"<string>\",\n  \"prefill.phone\": \"<string>\"\n}"

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

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR#first_name=Sam&last_name=Lee&email=sam%40example.com&phone=%2B14155550123",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "FEATURE_DISABLED",
      "message": "Agent onboarding is temporarily unavailable."
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many requests. Try again later."
    }
  ]
}

Overview

No authentication is required for this endpoint, it’s how a bot gets an API key in the first place. See the Agent onboarding API for the full flow.

Requests are rate-limited globally and per IP. A 429 includes a Retry-After header in seconds.

Body Parameters

string

A name for the bot starting the flow, shown to the owner during signup so they know what’s asking. Max length 64. Allowed characters: letters, numbers, spaces, and ._/-.

object

Values to pre-fill the owner’s sign-up form. Pass what the bot already knows. Invalid values are dropped silently, never a 400. Values that survive validation are appended to verification_url_complete as a URL fragment, form-encoded the way URLSearchParams does it (@ becomes %40, + becomes %2B, a space becomes +). The fragment stays in the owner’s browser; Bland never stores or logs pre-fill values.

string

Full name, up to 128 characters. Split on its first space into first and last name when first_name and last_name are absent.

string

First name, up to 128 characters.

string

Last name, up to 128 characters.

string

Email address, up to 128 characters. Dropped unless it has the shape x@y.z.

string

Phone number, up to 128 characters, normalized to E.164 with US as the default region. Dropped when it can’t be normalized.

Response

object

Device and user codes for the flow.

string

Opaque code your bot polls with at /v1/agent/onboarding/poll. Keep this private.

string

Short code to show the owner. They enter this at verification_url if it isn’t already pre-filled.

string

The page where the owner completes signup, without the code embedded.

string

The same page with user_code pre-filled. When prefill values survive validation, they are appended as a URL fragment, for example ...?code=BQPL-7VXR#first_name=Sam&last_name=Lee&email=sam%40example.com&phone=%2B14155550123. Prefer this when you can show a clickable link.

number

Seconds until the codes expire (900, 15 minutes).

number

Minimum seconds to wait between calls to /poll.

null | array

null on success.

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR#first_name=Sam&last_name=Lee&email=sam%40example.com&phone=%2B14155550123",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "FEATURE_DISABLED",
      "message": "Agent onboarding is temporarily unavailable."
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many requests. Try again later."
    }
  ]
}

Docs for agents: llms.txt

⌘I

Start Agent Onboarding

curl --request POST \
  --url https://api.bland.ai/v1/agent/onboarding/start \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_name": "<string>",
  "prefill": {},
  "prefill.name": "<string>",
  "prefill.first_name": "<string>",
  "prefill.last_name": "<string>",
  "prefill.email": "<string>",
  "prefill.phone": "<string>"
}
'

import requests

url = "https://api.bland.ai/v1/agent/onboarding/start"

payload = {
    "client_name": "<string>",
    "prefill": {},
    "prefill.name": "<string>",
    "prefill.first_name": "<string>",
    "prefill.last_name": "<string>",
    "prefill.email": "<string>",
    "prefill.phone": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_name: '<string>',
    prefill: {},
    'prefill.name': '<string>',
    'prefill.first_name': '<string>',
    'prefill.last_name': '<string>',
    'prefill.email': '<string>',
    'prefill.phone': '<string>'
  })
};

fetch('https://api.bland.ai/v1/agent/onboarding/start', 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/agent/onboarding/start",
  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([
    'client_name' => '<string>',
    'prefill' => [
        
    ],
    'prefill.name' => '<string>',
    'prefill.first_name' => '<string>',
    'prefill.last_name' => '<string>',
    'prefill.email' => '<string>',
    'prefill.phone' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "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.bland.ai/v1/agent/onboarding/start"

	payload := strings.NewReader("{\n  \"client_name\": \"<string>\",\n  \"prefill\": {},\n  \"prefill.name\": \"<string>\",\n  \"prefill.first_name\": \"<string>\",\n  \"prefill.last_name\": \"<string>\",\n  \"prefill.email\": \"<string>\",\n  \"prefill.phone\": \"<string>\"\n}")

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

	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/agent/onboarding/start")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_name\": \"<string>\",\n  \"prefill\": {},\n  \"prefill.name\": \"<string>\",\n  \"prefill.first_name\": \"<string>\",\n  \"prefill.last_name\": \"<string>\",\n  \"prefill.email\": \"<string>\",\n  \"prefill.phone\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/agent/onboarding/start")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"client_name\": \"<string>\",\n  \"prefill\": {},\n  \"prefill.name\": \"<string>\",\n  \"prefill.first_name\": \"<string>\",\n  \"prefill.last_name\": \"<string>\",\n  \"prefill.email\": \"<string>\",\n  \"prefill.phone\": \"<string>\"\n}"

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

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR#first_name=Sam&last_name=Lee&email=sam%40example.com&phone=%2B14155550123",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "FEATURE_DISABLED",
      "message": "Agent onboarding is temporarily unavailable."
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many requests. Try again later."
    }
  ]
}

Basic Tutorials

Agent Onboarding

Calls

Conversational Pathways

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Node tests

Agent Testing

Evals

Guard Rails

Web Agents

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Personas

Citation Schemas

Alarms

Triage

Start Agent Onboarding

Overview

Body Parameters

Response

​Overview

​Body Parameters

​Response

Overview

Body Parameters

Response