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

> ## Agent Instructions
> Use the public API base URL: https://api.teamfollowup.ai/api.
> Authenticate public API requests with Authorization: Bearer YOUR_API_KEY.
> Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers.
> Scope requests by locationId rather than projectName.
> Read the guide linked from each API reference group before recommending an endpoint.

# Caller ID registration

> Register the businesses behind your calling numbers with Twilio, so carriers know who is calling and label your calls as spam less often.

Carriers decide whether to show **Spam Likely** partly on whether they know who
owns a number. Registering a business tells them. Twilio files three things for
each registered number:

| Product | Field | What it does for your calls |
| - | - | - |
| Voice Integrity | `voiceIntegrity` | Registers the numbers with the spam screening the major US carriers use, so they are labelled as spam less often. |
| SHAKEN/STIR | `shakenStir` | Marks each call as coming from a verified business. |
| Caller name | `cnam` | Asks carriers to show the business name, up to 15 characters, instead of only the number. Local numbers only. |

Registration is free. Twilio reviews each business, usually over one or more
business days.

## Whose name the calls carry

A number belongs to one registered business. Register each client as its own
business when its leads know the client's name, which is usually the case. In
the dashboard this is **A client** under **Whose name shows on calls?**. The
API registers client businesses only.

## What a registration needs

The summary's `fields` lists every detail, with its allowed values in
`options`. They describe two people and one business:

* **The business**: legal name exactly as on its tax registration, business
  type, industry, EIN or DUNS, an `https://` website, a US address, and the
  caller name.
* **Its authorised representative**: name, work email, a US phone number in
  `+1` format, job title and position. Twilio may contact them.
* **The person who confirmed the details** (`confirmedBy`): someone at your
  agency. In the dashboard that is whoever is signed in and ticks **I'm
  authorised**. Through the API you name them, and they are kept with the
  submission as its consent record. They are never sent to Twilio.

`businessIdentity` defaults to `direct_customer`, a business that operates its
own calls, which is how a client registered by its agency is filed.

## Where a number stands

Each number in the summary says whether it can be registered (`supported`) and,
when it cannot, why (`reason`). A registration moves through these states:

| `state` | Meaning |
| - | - |
| `draft` | Saved in the dashboard, not sent. |
| `queued` | Accepted, waiting to be sent to Twilio. |
| `under_review` | Twilio is reviewing it. |
| `complete` | Every product approved. |
| `partial` | Some products approved. |
| `needs_attention` | Something was rejected. `problem` says what to fix. |

Each product in `products` has its own `status`, so a caller name can be
rejected while Voice Integrity is approved.

## New numbers

With `futureNumbers` on (the API default), a number bought later for the same
business joins its registration automatically, so numbers you swap in do not
need a new registration.

## Two businesses with one EIN

Twilio registers one EIN once in each Twilio account. Two locations of one
company often share an EIN. Register the first location as usual. The second
location's call answers `identity_conflict`. Send it again with
`linkExisting: true`, and its numbers join the first registration. Both
locations then use the first registration's details and caller name.
`linkedLocations` on the registration lists the businesses it covers.
`references` on the refusal names the registration it ran into.

In the dashboard, the registration form offers **Link to** that business
instead of sending. The agency can **Unlink** a linked business. Its numbers
then leave the registration and lose its caller ID. A linked business that
is removed from your account leaves the registration by itself.

## Boundaries

* No registration guarantees a number is never labelled as spam. Each carrier
  decides, and some phones block anything marked as spam.
* Whether the caller name shows depends on the receiving carrier and the phone.
* Only US numbers can be registered. A number outside the US comes back in
  `excluded` with `reasonCode` `us_numbers_only`.
* A number held by a provider other than Twilio shows `supported: false` until
  it is moved.
* Changing an approved business's details needs our support team.

## In the API

The [Caller ID API](https://docs.teamfollowup.ai/api-reference/caller-id.md) covers both operations and their
scopes.

* [Get caller ID status](https://docs.teamfollowup.ai/api-reference/caller-id/get-caller-id-status.md) reads
  every number and registration. It needs the `phone_numbers:read` scope.
* [Register a business for caller ID](https://docs.teamfollowup.ai/api-reference/caller-id/register-a-business-for-caller-id.md)
  registers one business in one call. It needs `phone_numbers:write`. Send a new
  `submissionId` per registration and reuse it on retries, and the same request
  never registers twice.
* Refusals: `invalid_details` (the `errors` list names each field),
  `consent_required`, `no_eligible_numbers`, `selection_changed`,
  `assignment_conflict`, `identity_conflict`, `forbidden` and
  `registration_unavailable`.
* Every field above is defined in the [Glossary](https://docs.teamfollowup.ai/glossary.md#caller-id).

## Related

* [Phone numbers and caller ID](https://docs.teamfollowup.ai/phone-numbers/overview.md)
* [Authentication](https://docs.teamfollowup.ai/authentication.md)


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