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

# Number Registration

> Register phone numbers with the analytics engines behind US carrier spam labels — automated Free Caller Registry submissions, included for RevDesk numbers, $5/number/month for numbers you bring.

## What it is

The **Free Caller Registry** is a joint intake run by the three analytics engines that score
caller reputation for the major US carriers — **Hiya** (T-Mobile), **TNS** (Verizon), and
**First Orion** (AT\&T). Registering a number associates it with your business identity, which
protects legitimate calling from "Spam Likely" labeling before behavior scoring decides on its own.

The registry is free but deliberately manual: a human-paced portal with an email-verification
gate, batch limits, and three separate vendor confirmations to track. RevDesk automates the whole
flow and exposes it as an API.

<Note>
  Registration is **preventive** — it establishes who you are with the engines. To clear labels on
  numbers that are already flagged, use [spam-label remediation](/concepts/caller-trust) (\$2/number);
  remediation requires the number to be hosted on RevDesk (port a flagged number in to unlock it).
  Best practice is both: register everything, remediate the flagged.
</Note>

## Two ways numbers get registered

<Columns cols={2}>
  <Card title="RevDesk-hosted numbers (included)" icon="shield-check">
    Every US number provisioned on RevDesk is registered automatically shortly after purchase —
    included in the number's monthly price, on by default. Opt out per workspace in Settings →
    Call Identity → Reputation.
  </Card>

  <Card title="Bring-your-own numbers ($5/number/mo)" icon="upload">
    Register numbers hosted anywhere — any carrier or CPaaS — through the API. \$5 per number per
    calendar month on your invoice, starting when the registry accepts the submission. No platform
    fee, no minimums.
  </Card>
</Columns>

## Quickstart (BYO numbers)

You don't need any other RevDesk product — sign up, create an API key (Settings → API Keys), add
a payment method, and register:

```bash theme={null}
curl -X POST https://www.revdesk.com/api/v1/number-registrations \
  -H "Authorization: Bearer $REVDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+16893560542", "+16893100649"],
    "attestation": { "authorized_to_register": true }
  }'
```

Business identity (name, address, website, contact) defaults to your workspace's caller-trust
profile; override it per request with `business_identity` when registering on behalf of another
business you're authorized to represent.

## Authorization attestation

The registry's terms require that the submitter is authorized to register the numbers for the
business they belong to. For BYO numbers the API therefore requires an explicit attestation
(`attestation.authorized_to_register: true`), which RevDesk records with the registration — the
exact accepted text, the acting user, and the timestamp. RevDesk-hosted numbers need no
attestation; RevDesk is the service provider of record.

## Lifecycle

| Status      | Meaning                                                                      |
| ----------- | ---------------------------------------------------------------------------- |
| `pending`   | Accepted by RevDesk; the registry run hasn't completed yet                   |
| `submitted` | The registry accepted the submission; engine acknowledgments pending         |
| `active`    | At least one engine acknowledged receipt                                     |
| `failed`    | The registry run failed after retries — RevDesk ops is alerted automatically |
| `cancelled` | You cancelled — billing and tracking stopped                                 |

Per-engine acknowledgments (`hiya`, `tns`, `first_orion`) are exposed on
`GET /v1/number-registrations/{id}`. Propagation into live carrier spam labeling typically
completes within **24–48 hours** of submission. Re-registering a live number is free and simply
refreshes it (the registry dedupes by number).

## Webhooks

Subscribe via [`POST /v1/webhook_subscriptions`](/api-reference/webhooks):

* `registration_submitted` — the registry accepted a submission
* `registration_confirmed` — first engine acknowledgment arrived
* `registration_failed` — a submission failed after retries

## Billing semantics

* \$5 per BYO number per **calendar month**, billed as a "Number Registration" line item on your monthly invoice (quantity = your live registrations). Additions start on your next invoice; no proration.
* First charge when the submission reaches `submitted` — a failed run never bills.
* RevDesk-hosted numbers never bill for registration, even when submitted through the API.
* `DELETE /v1/number-registrations/{id}` stops future charges immediately. The registry has no
  un-register operation, so the number's existing registration with the engines is unaffected —
  cancellation is a billing and monitoring stop. No refund for the current month.