Caller ID Details

curl --request GET \
  --url https://app.tuco.ai/api/workspace/caller-id-profile \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.tuco.ai/api/workspace/caller-id-profile', 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://app.tuco.ai/api/workspace/caller-id-profile",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://app.tuco.ai/api/workspace/caller-id-profile"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.tuco.ai/api/workspace/caller-id-profile")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "profile": {},
  "status": {},
  "submittedAt": {},
  "needed": true,
  "prefilled": true
}

GET

api

workspace

caller-id-profile

Caller ID Details

curl --request GET \
  --url https://app.tuco.ai/api/workspace/caller-id-profile \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.tuco.ai/api/workspace/caller-id-profile', 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://app.tuco.ai/api/workspace/caller-id-profile",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://app.tuco.ai/api/workspace/caller-id-profile"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.tuco.ai/api/workspace/caller-id-profile")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "profile": {},
  "status": {},
  "submittedAt": {},
  "needed": true,
  "prefilled": true
}

The business details carriers need before calls from a Registered caller ID number can show your business name. There is one set per workspace, used by every line with the add-on. This is the same data as the Caller ID details form in the dashboard. See Registered caller ID setup. Use a workspace API key (tuco_…).

Endpoint

Method: GET to read, PUT to save a draft or submit
Path: /api/workspace/caller-id-profile
Auth: Authorization: Bearer tuco_xxxxxxxxxxxxx

Read — `GET`

curl https://app.tuco.ai/api/workspace/caller-id-profile \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"

{
  "profile": {
    "displayName": "Acme Debt Relief",
    "callReasons": ["Sales Call", "Follow-Up Calls"],
    "logoUrl": null,
    "legalName": "Acme Holdings, Inc.",
    "dba": "Acme Debt Relief",
    "website": "https://acme.com",
    "ein": "12-3456789",
    "entityType": "corporation",
    "stateOfIncorporation": "Florida",
    "industry": "financial",
    "employees": "11-50",
    "address": { "street": "100 Main St", "suite": "", "city": "Miami", "state": "FL", "zip": "33101" },
    "billingAddressSame": true,
    "billingAddress": null,
    "contact": { "firstName": "Jane", "lastName": "Doe", "title": "Owner", "email": "jane@acme.com", "phone": "+13055550100" },
    "billingContactSame": true,
    "billingContact": null,
    "callingAreaCode": "305",
    "certified": true
  },
  "status": "submitted",
  "submittedAt": "2026-10-31T14:02:11.000Z",
  "needed": true,
  "prefilled": false
}

object

The saved details. If nothing is saved yet, an empty profile is returned, pre-filled where we can: company legal name and address from the workspace’s newest line order, and the contact’s name and email from the user the request is made as (for an API key, the user who created it). callReasons starts as ["Sales Call"].

string | null

null (nothing saved yet), draft (saved, not submitted) or submitted (sent to us for registration). PUT only ever sets draft or submitted. The dashboard also recognizes in_review, verified and rejected, and treats every value other than null and draft as submitted. Do the same.

string | null

When the details were last submitted (ISO 8601), or null.

boolean

true when the workspace paid for Registered caller ID at checkout or a line has the add-on.

boolean

true when nothing is saved yet and profile was pre-filled from a line order or the user.

Save or submit — `PUT`

curl -X PUT https://app.tuco.ai/api/workspace/caller-id-profile \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "submit": true,
    "profile": {
      "displayName": "Acme Debt Relief",
      "callReasons": ["Sales Call"],
      "legalName": "Acme Holdings, Inc.",
      "dba": "Acme Debt Relief",
      "website": "https://acme.com",
      "ein": "12-3456789",
      "entityType": "corporation",
      "stateOfIncorporation": "Florida",
      "industry": "financial",
      "employees": "11-50",
      "address": { "street": "100 Main St", "city": "Miami", "state": "FL", "zip": "33101" },
      "billingAddressSame": true,
      "contact": { "firstName": "Jane", "lastName": "Doe", "title": "Owner", "email": "jane@acme.com", "phone": "+13055550100" },
      "billingContactSame": true,
      "certified": true
    }
  }'

Body field	Type
`profile`	object	Required. The details. See the fields below. If it’s missing or isn’t an object, you get a `400` and nothing is saved.
`submit`	boolean	`true` submits: every required field must be filled in, and we start registering. Leave it out or send `false` to save a draft. Once the details are submitted, every change must be sent with `submit: true`. A draft save then gets a `409`.

PUT replaces the whole saved profile. A field you leave out is saved as empty. To change one field, GET the profile first, change it, and send it all back.

Profile fields

“Submit” means the field is required when submit is true. Text is trimmed.

Field	Submit	Rules
`displayName`	Required	The name shown on calls. Your company or brand, not a person. 1–35 characters, no emoji.
`callReasons`	Required	1 to 3 values from the call reasons list. Values not on the list are dropped; only the first 3 are kept.
`logoUrl`	Optional	URL of a square logo image.
`legalName`	Required	Company legal name. At least 3 characters.
`dba`	Required	The name customers know you by.
`website`	Required	For example `https://acme.com` or `acme.com`.
`ein`	Required	Federal tax ID: 9 digits, `12-3456789` or `123456789`.
`entityType`	Required	`corporation`, `llc`, `partnership`, `nonprofit` or `other`.
`stateOfIncorporation`	Required	The state where the company is registered, for example `Florida`.
`industry`	Required	One value from the industries list.
`employees`	Required	`1-10`, `11-50`, `51-200`, `201-500`, `501-2000`, `2001-10000` or `10001+`.
`address`	Required	`street`, `city`, `state`, `zip` required. `suite` optional.
`billingAddressSame`	—	Default `true`. Send `false` with a `billingAddress` (`street`, `city`, `state`, `zip` required).
`contact`	Required	The main contact, who signs the authorization letter. `firstName`, `lastName`, `title` (job title), `email`, `phone` all required. `email` must be a valid address. `phone` must be a US or Canada number in any common format; it’s saved as E.164 (`+13055550100`).
`billingContactSame`	—	Default `true`. Send `false` with a `billingContact` (`firstName`, `lastName`, `email`, `phone` required, same email and phone rules as `contact`).
`callingAreaCode`	Optional	3 digits. The area code you’d like for the separate caller ID numbers. Empty = match each line.
`certified`	Required (`true`)	Confirms the name and logo accurately represent your business, you own or are allowed to use them, and your calls contain no sex, hate, alcohol, firearms or tobacco content.

A draft can be half-filled. It is only rejected for values that are present but wrong: a displayName over 35 characters or with emoji, a malformed ein, contact.email or website, an entityType / industry / employees value not on its list, or a callingAreaCode that isn’t 3 digits.

Response (`200`)

{
  "ok": true,
  "status": "submitted",
  "profile": { "displayName": "Acme Debt Relief", "callReasons": ["Sales Call"], "…": "…" },
  "submittedAt": "2026-10-31T14:02:11.000Z"
}

profile is what was saved, after trimming and dropping unknown call reasons. To send changes after submitting, PUT again with submit: true. A later draft save (submit left out) sets status back to draft; submittedAt keeps the time of the last submit.

Rejected (`422`)

{
  "error": "Please fill in: Website, Federal tax ID (EIN). Please check: Name shown on calls.",
  "missing": ["website", "ein"],
  "invalid": ["displayName"]
}

missing and invalid hold field paths such as contact.title or billingAddress.zip. Nothing is saved when the request is rejected.

Error responses

Status	When
`400`	The body isn’t valid JSON, or `profile` is missing or isn’t an object. Nothing is saved
`401`	Missing or invalid key
`403`	An agency key (`tucoagency_…`) was used. This is a per-workspace setting
`404`	Workspace not found
`409`	The details are already submitted and you sent a draft (`submit` not `true`). Send the change with `submit: true`. Nothing is saved
`422`	A required field is missing (on submit) or a value is invalid. See above

What happens after you submit

We register your business with the carriers, which usually takes a few business days. The main contact signs one short authorization letter. Once a line’s Registered caller ID is live, its calling add-ons show status: "active" and the callingNumber its calls go out from.

Call reasons

Sales Call, Follow-Up Calls, Returning Your Call, Responding to Your Inquiry, Customer Service, Account Services, Your Account, Account Notification, Account Alert, Agent Call Back, Appointment Confirmation, Appointment Reminder, Confirm Appointment, Reschedule Request, Response Requested, General Support, Technical Support, Policy Update, Accounting Department, Confirm Status, Identity Verification, Fraud Alert, Confirm Card Use, Confirm Order, Order Confirmation, Your Order, Confirm Receipt, Delivery ETA, Today's Delivery, Upcoming Delivery, Item Ready, Order Ready, Reservation Ready, Rx Ready, Recall, Service Outage Notification, Verification Code, Investor Relations, Flight Arrival, Flight Boarding, Flight Cancellation, Flight Delay, School Closing Alert, Snow Alert, Weather Alert Values are case-sensitive.

Industries

financial, finance, banking, collections, accounting, billing, insurance, legal, law, real estate, property, sales, marketing, business, customer service, support, software, technology, tech, telecom, communications, healthcare, health, medical, pharmacy, education, retail, ecommerce, delivery, shipping, logistics, travel, hospitality, hotel, media, surveys, market research, notifications, scheduling, government, public, charity, nonprofit

Overview

Webhooks

Errors and status codes

iMessage Availability

Messages

Voice / Calling

Replies

Do Not Contact

Lines & Leads

Analytics

Goal Bots

API Tools

Agency

Workspace settings

Caller ID Details

Endpoint

Read — `GET`

Save or submit — `PUT`

Profile fields

Response (`200`)

Rejected (`422`)

Error responses

What happens after you submit

Call reasons

Industries

​Endpoint

​Read — GET

​Save or submit — PUT

​Profile fields

​Response (200)

​Rejected (422)

​Error responses

​What happens after you submit

​Call reasons

​Industries

Endpoint

Read — `GET`

Save or submit — `PUT`

Profile fields

Response (`200`)

Rejected (`422`)

Error responses

What happens after you submit

Call reasons

Industries