# Get a number

A number is what your texts come from. Carriers want to know who is behind it before they deliver your texts, so every number goes through a short registration first.

## Which kind

| Kind | Reaches | Price | Registration |
| --- | --- | --- | --- |
| Toll-free | US and Canada | First one included on paid plans, then $2 a month each | Verified number by number |
| Local | US | $2 a month, plus $15 a month for your business's registration | Your business and one campaign, registered once |
| Short code | US and Canada | On Enterprise, by contract | Set up with us |

Start with toll-free. It reaches both countries, and it is the only way to text people in Canada from an application. Local numbers are for the US only.

## Pick and register one

List a few numbers, then buy one with your business details and how you will text.

List available numbers:

```sh
curl -X GET "https://api.rasket.com/sms/senders/available?country=US&type=toll_free" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"
```

```ts
const response = await fetch("https://api.rasket.com/sms/senders/available?country=US&type=toll_free", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();
```

```python
import os

import requests

response = requests.get(
    "https://api.rasket.com/sms/senders/available?country=US&type=toll_free",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())
```

Get a number:

```sh
curl -X POST "https://api.rasket.com/sms/senders" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "toll_free",
  "country": "US",
  "use": "both",
  "name": "Support line",
  "business": {
    "legal_name": "Acme Corporation",
    "website": "https://example.com",
    "address": {
      "line1": "1 Main St",
      "city": "Portland",
      "region": "OR",
      "postal_code": "97201",
      "country": "US"
    },
    "registration_number": "12-3456789",
    "entity_type": "private_profit",
    "vertical": "retail",
    "contact": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "phone": "+15035550123"
    }
  },
  "messages": {
    "sample_messages": ["Acme: your order #1042 has shipped. Reply STOP to opt out."],
    "opt_in_description": "Customers tick a box at checkout to get order updates by text.",
    "opt_in_url": "https://example.com/checkout",
    "monthly_volume": 2000
  }
}'
```

```ts
const response = await fetch("https://api.rasket.com/sms/senders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "toll_free",
    country: "US",
    use: "both",
    name: "Support line",
    business: {
      legal_name: "Acme Corporation",
      website: "https://example.com",
      address: {
        line1: "1 Main St",
        city: "Portland",
        region: "OR",
        postal_code: "97201",
        country: "US"
      },
      registration_number: "12-3456789",
      entity_type: "private_profit",
      vertical: "retail",
      contact: {
        first_name: "Ada",
        last_name: "Lovelace",
        email: "ada@example.com",
        phone: "+15035550123"
      }
    },
    messages: {
      sample_messages: ["Acme: your order #1042 has shipped. Reply STOP to opt out."],
      opt_in_description: "Customers tick a box at checkout to get order updates by text.",
      opt_in_url: "https://example.com/checkout",
      monthly_volume: 2000
    }
  }),
});

const { id } = await response.json();
```

```python
import os

import requests

response = requests.post(
    "https://api.rasket.com/sms/senders",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "type": "toll_free",
    "country": "US",
    "use": "both",
    "name": "Support line",
    "business": {
      "legal_name": "Acme Corporation",
      "website": "https://example.com",
      "address": {
        "line1": "1 Main St",
        "city": "Portland",
        "region": "OR",
        "postal_code": "97201",
        "country": "US"
      },
      "registration_number": "12-3456789",
      "entity_type": "private_profit",
      "vertical": "retail",
      "contact": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "phone": "+15035550123"
      }
    },
    "messages": {
      "sample_messages": ["Acme: your order #1042 has shipped. Reply STOP to opt out."],
      "opt_in_description": "Customers tick a box at checkout to get order updates by text.",
      "opt_in_url": "https://example.com/checkout",
      "monthly_volume": 2000
    }
  },
)

id = response.json()["id"]
```

- `registration_number` is your EIN in the US or your BN in Canada.
- `opt_in_url` is the page where people agree to your texts. Reviewers open it.
- Some kinds of business cannot register: high-risk lending, debt collection, lead generation, gambling, and texts on behalf of other companies.

## While it is reviewed

| Status | What it means |
| --- | --- |
| `testing` | Created; texts go only to your test phones. |
| `in_review` | Registration sent. Usually 1 to 5 business days. |
| `active` | Approved. It can text anyone who agreed. |
| `rejected` | Not approved. registration.rejection_reason says why. |
| `paused` | Stopped for now, for example after a move to Free. It can resume. |
| `released` | Given up. It cannot come back. |

Until your number is `active`, you can still test: texts go to the phones in `/sms/verified-phones`, from our shared test number, with `[Test]` in front. A rejected registration can be corrected and sent back with `POST /sms/senders/{sender_id}/refresh`; three corrections are included.

## Cancel a registration or release a number

Canceling withdraws a number's registration and keeps the number: it goes back to `testing`, still billed, with `registration.status` `draft` and `registration.canceled_at` set, until you send it again with `POST /sms/senders/{sender_id}/refresh` and a `business` or `messages` block.

Cancel a registration:

```sh
curl -X POST "https://api.rasket.com/sms/senders/{sender_id}/cancel-registration" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"
```

```ts
const response = await fetch("https://api.rasket.com/sms/senders/{sender_id}/cancel-registration", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const { id } = await response.json();
```

```python
import os

import requests

response = requests.post(
    "https://api.rasket.com/sms/senders/{sender_id}/cancel-registration",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

id = response.json()["id"]
```

- A registration the carriers are reviewing can't be withdrawn, and neither can an approved one: the answer is a `422` that says why. A rejected one, or one not sent yet, can.
- Your local numbers share one registration, so canceling it sends all of them back to `testing`.
- Sending a canceled registration again uses one of the three included corrections if it had already reached the carriers.

Releasing a number (`DELETE /sms/senders/{sender_id}`) gives it up for good: its texts that have not gone yet are canceled and its monthly price stops. Its registration is withdrawn first where the carriers allow it. You can do both from the dashboard too, on SMS → Numbers.

## Naming numbers

Give each number a name that says what it is for, like `Support line`, `Marketing` or `2FA codes`: up to 60 characters, in `name` when you get the number or later with `PATCH /sms/senders/{sender_id}`. Send `null` to remove it. The name is yours alone: the people you text never see it.

Rename a number or make it the default:

```sh
curl -X PATCH "https://api.rasket.com/sms/senders/{sender_id}" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support line",
  "is_default": true
}'
```

```ts
const response = await fetch("https://api.rasket.com/sms/senders/{sender_id}", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support line",
    is_default: true
  }),
});

const { id } = await response.json();
```

```python
import os

import requests

response = requests.patch(
    "https://api.rasket.com/sms/senders/{sender_id}",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "name": "Support line",
    "is_default": True
  },
)

id = response.json()["id"]
```

## Which number a text comes from

`from` is optional on every send. Leave it out and the text comes from your default number for the destination's country. Set it to one of your `active` numbers to choose.

Your first number becomes the default while it is still being set up. To move the default, send `is_default: true` to `PATCH /sms/senders/{sender_id}` once the number you want is `active`. A toll-free number becomes the default for the US and Canada, a local number for the US alone, and `default_for` on each number says which countries it is the default for. Automations and campaigns send from the default too. See the [SMS reference](https://www.rasket.com/docs/api-reference/sms) for every field.