GuidesGet a number

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

SMS number kinds
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.

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"

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();

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())

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
  }
}'

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();

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

Number statuses
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.

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"

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();

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.

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
}'

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();

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 for every field.