Skip to content
DashboardGet API key

Get regulatory requirements

View .md
GET

Get the regulatory information needed to buy a phone number, for one specific number or for a country and number type. Prefer phoneNumber: the response is then exactly the list the purchase of that number validates against. Pass each requirementTypes[].id back as requirementType in regulatoryRequirements on POST /v1/phone-numbers.

For phoneNumber, the requirements of that exact number are returned. When they cannot be resolved for the number itself, the list for its country and type is returned instead, and the purchase uses the same list. An empty items array means the number needs no regulatory information. If the requirements cannot be retrieved at all, the response is 502 requirements_unavailable, never an empty list.

URL-encode the + of phoneNumber as %2B. An unencoded + is also accepted.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • countryCodestring

    Two-letter ISO country code. Required unless phoneNumber is given.

    Limitsmin length 2 · max length 2
  • typestring

    Type of phone number (local, national, mobile, tollFree). Defaults to local. With phoneNumber, used only when the number's own requirements cannot be resolved and the country list is returned.

    One oflocalnationaltollFreemobile
  • phoneNumberstring

    E.164 number from GET /v1/phone-numbers/available, with + encoded as %2B. Returns the requirements the purchase of that number checks. Takes precedence over countryCode.

Responses

200Requirements for the number, or for the country and type.
  • itemsobject[]required
    5 properties
    • idstringrequired
    • countryCodestringrequired
    • phoneNumberTypestringrequired
    • actionstringrequired
    • requirementTypesobject[]required
      6 properties
      • idstringrequired

        Send this as requirementType in regulatoryRequirements when purchasing.

      • namestringrequired
      • descriptionstringrequired
      • typestringrequired

        Type of requirement field.

        One oftextualaddressdocumentaction
      • examplestringnullable
      • acceptanceCriteriaobject

        Acceptance criteria for a requirement.

        4 properties
        • minLengthintegernullable
        • maxLengthintegernullable
        • allowedValuesstring[]nullable
        • regexPatternstringnullable
400Neither `countryCode` nor `phoneNumber` was given, one is malformed, or the requirements cannot be looked up for this input (`invalid_request`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
502The requirements could not be retrieved right now. Retry; do not treat this as "no requirements".
  • codestringrequired
  • messagestringrequired
  • detailsobject