TextKitDocs

Attach a number to a registration

Ties a live US local number to one of your registrations.

POST/v1/numbers/{id}/registration

Path Parameters

  • idstringrequired

    The E.164 number

Body Parameters

  • registration_idstringrequired

    Example: reg_a1B2c3D4e5F6.

Details

Needed only when you have more than one approved registration, or to retry a link that failed; otherwise numbers follow your registration on their own. If the registration is approved the number is linked with the carriers (sender.state pending, then active); a registration holds at most 49 numbers.

Emits number.sender_updated.

Responses

  • 200Number

    The number with its new sender

  • 400Error

    Unknown registration, or a number that is not registered (sandbox, toll-free)

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 404Error

    Not found

  • 409Error

    The registration already has 49 numbers, or the number is active elsewhere and this registration is not approved yet

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring

    Example: +15005550132.

  • objectnumber
  • phone_numberstring
  • statusactive, released
  • modetest, live
  • created_atstring (date-time)
  • customer_idstring

    The customer this number is assigned to Nullable.

  • labelstring

    Nullable.

  • tagsarray of string
  • poolsarray of string

    Pool ids

  • senderobject

    How the number stands with the carriers. null on sandbox numbers and on numbers that need no registration (toll-free, Canadian). Only an active number can text anyone; in every other state it can text only your verified numbers. Nullable.

  • sender.statetest_only, pending, active, action_needed

    test_only: no registration submitted. pending: a registration is in review, or approved and being linked. active: linked to an approved registration. action_needed: see reason.

  • sender.registration_idstring

    The registration it is (being) linked to Nullable.

  • sender.reasonstring

    What to do, in plain words, when state is action_needed Nullable.

  • sender.updated_atstring (date-time)
  • toll_freeobject

    Toll-free verification, on live toll-free numbers only (null on every other number). Only a verified number texts anyone; its texts and STOP/HELP replies name business. Until the account has live access it texts only your verified numbers, verified or not; the carriers verifying it also verifies its business with us and gives a sandbox account live access. Nullable.

  • toll_free.statusnot_started, pending, verified, rejected
  • toll_free.businessstring

    The business the verification names Nullable.

  • toll_free.use_casestring

    Nullable.

  • toll_free.verified_atstring (date-time)

    Nullable.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 400

    Unknown registration, or a number that is not registered (sandbox, toll-free)

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 404

    Not found

  • 409

    The registration already has 49 numbers, or the number is active elsewhere and this registration is not approved yet

  • 429

    Rate limit or quota exceeded