Skip to main content
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: 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: 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 covers both operations and their scopes.
  • Get caller ID status reads every number and registration. It needs the phone_numbers:read scope.
  • Register a business for caller ID 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.