> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Caller ID Details

> Read, save and submit the business details the Registered caller ID add-on needs. One set per workspace, shared by every line.

> [!NOTE]
>
> The business details carriers need before calls from a [Registered caller ID](https://docs.tuco.ai/api-reference/endpoint/calling-addons.md) 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](https://docs.tuco.ai/features/registered-caller-id.md).
> 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`

```bash theme={null}
curl https://app.tuco.ai/api/workspace/caller-id-profile \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
```

```json theme={null}
{
  "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
}
```

**profile** `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"]`.

**status** `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.

**submittedAt** `string | null`

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

**needed** `boolean`

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

**prefilled** `boolean`

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

## Save or submit — `PUT`

```bash theme={null}
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`. |

> [!WARNING]
>
> **`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](#call-reasons). 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](#industries). |
| `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`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "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](https://docs.tuco.ai/api-reference/endpoint/calling-addons.md) 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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.