Number campaigns

Which registration campaign and account a number belongs to.

#List registration campaigns a number can move to

The registration campaign (the carrier campaign from your Registration page) the number sends under now, and the approved registration campaigns on your account it can move to. Needs the manage_phones permission.

Path parameters

idintegerRequired: The number id.

Returns

data.currentstring | null: The carrier id of the registration campaign the number is on, the same as campaign_id on the number.
data.choices[]object[]: Each { campaign_id, name }. Send a campaign_id to Move a number to another registration campaign.

Errors

HTTP	Code	When
404	`NUMBER_NOT_FOUND`	No number with this id on your account.
500	`REGISTRATIONS_UNAVAILABLE`	Ready couldn’t load your registration campaigns. Try again.

curl "https://api.tryready.com/v1/numbers/2647/registrations" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/2647/registrations', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/numbers/2647/registrations",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "current": "C3RX0NA",
    "choices": [
      {
        "campaign_id": "C3RX0NA",
        "name": "Acme Plumbing (Customer care)"
      },
      {
        "campaign_id": "CK2Q7ZB",
        "name": "Acme Plumbing (Marketing)"
      }
    ]
  }
}

#Move a number to another registration campaign

Moves the number onto another of your approved registration campaigns. A registration campaign’s only number stays where it is, because the carriers pause a registration campaign with no numbers. Needs the manage_phones permission.

Path parameters

idintegerRequired: The number id.

Body parameters

campaign_idstringRequired: One of the choices[].campaign_id from List registration campaigns a number can move to.

Errors

HTTP	Code	When
400	`REGISTRATION_NOT_ALLOWED`	That registration campaign isn’t approved on your account.
404	`NUMBER_NOT_FOUND`	No number with this id on your account.
409	`NUMBER_NOT_MOVABLE`	The number isn’t active on a registration campaign yet, so it can’t be moved here. Contact support and we’ll move it for you.
409	`only_number_on_brand`	It’s the only number on its registration campaign. Buy a new number for the other registration campaign instead.
409	`campaign_number_limit`	The target registration campaign already has the most numbers US carriers allow. Move or release one of its numbers first.
500	`REGISTRATION_MOVE_UNCONFIRMED`	Ready couldn’t confirm the move. Read the number to see which registration campaign it’s on.

curl -X PUT "https://api.tryready.com/v1/numbers/2647/registration" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "CK2Q7ZB"
  }'

const res = await fetch('https://api.tryready.com/v1/numbers/2647/registration', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "campaign_id": "CK2Q7ZB"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/v1/numbers/2647/registration",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "campaign_id": "CK2Q7ZB"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#Take a number back from a sub-account

The reverse of Move a number to a sub-account: the number moves from one of your sub-accounts back to your account. Only a number held by a sub-account directly under yours. Needs the manage_phones permission.

Path parameters

idintegerRequired: The number id.

Returns

messagestring: Number moved back to your main account., or Number already belongs to you when it’s already yours.
registrationobject | null: The registration campaign the number now sends under, when it moved onto one.

Errors

HTTP	Code	When
404	`NUMBER_NOT_FOUND`	Not a number on your account or on a sub-account directly under it.
500	`UNASSIGN_NOT_APPLIED`	The move didn’t apply. Try again.
500	`MOVE_UNCONFIRMED`	Ready couldn’t confirm the move. Read the number before you try again.

curl -X POST "https://api.tryready.com/v1/numbers/2647/unassign" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/numbers/2647/unassign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/numbers/2647/unassign",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "registration": null,
  "message": "Number moved back to your main account."
}