Skip to main content

​
Telnyx Numbers: Regulatory & Documents — Full Documentation

Complete page content for Regulatory & Documents (Numbers section) of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://developers.telnyx.com/development/llms/numbers-regulatory-documents-llms-txt.md

​
Regulatory

​
Regulatory Requirements

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements.md
Prior to number activation, some phone numbers need additional information to satisfy regulatory requirements.  These requirements are defined per:
  • Country
  • Phone number type
  • Action (ordering a phone number, or porting a phone number)
For example, porting a GB local phone number may have one set of requirements, while ordering a GB local phone number may have another set of requirements. Use the GET /requirements endpoint and accompanying filters to see what regulatory requirements need to be met to purchase/port a phone number. The API response will have two different record_type:
  • ”record_type”: “requirement”: This is the parent record. It indicates which country, phone number type, and action combination that the regulatory requirements apply to. For example, DE local ordering.
  • ”record_type”: “requirement_type”: Communicates the actual regulatory requirements that need to be fulfilled to unblock number activation in that particular country + phone number type + action combination. For example, a Proof of address.
Note: The regulatory landscape is constantly evolving. The regulatory requirements for phone numbers may change.

​
Fulfilling a requirement_type

To complete your order, all regulatory requirements requirement_type) must be fulfilled and approved. You can satisfy these requirements individually for each order, or you can use a requirement group to apply all the values at once. To view additional information on a regulatory requirement (description, examples, etc.), perform a GET /requirement_types/ request. If a requirement_type includes acceptance criteria, ensure the value provided meets those criteria. Each requirement_type has a type classification. There are four possible types:
  • textual
  • address
  • document
  • action
Each type has different rules for fulfillment.

​
Textual type

To fulfill a textual type, any string can be provided (assuming it complies with the acceptance_criteria of the requirement_type)

​
Address type

To fulfill an address requirement, an address id must be provided as the field value. Create an address using the POST v2/addresses endpoint. Upon successful creation, the address will have a unique id associated with it (for example 1293384261075731499). Pass that id as the field_value for the address ordering requirement. You cannot write out the address as a string (i.e. “312 W Superior St, Chicago, IL, 60654, US”). You must create the address with the POST v2/addresses endpoint, and pass the address id as the field_value.

​
Document type

To fulfill a document requirement, a document id must be provided as the field value. Upload the document using the POST /documents endpoint. Upon successful upload, an id will be returned in the response that corresponds to the document (for example 6a09cdc3-8948-47f0-aa62-74ac943d6c58). Pass that id as the field_value for the document ordering requirement.

​
Action type

An action requirement is unique, and very rare. Please see our separate developer guide to learn more about how to handle action requirement types.

​
Requirement groups

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/requirement-groups.md

​
Overview

Requirement groups allow you to view, manage, and fulfill regulatory requirements in advance for a particular order type. By creating a requirement group, you can pre-fill all necessary information and documentation just once, and then reuse this group across multiple orders. Each requirement group is specific to a combination of country_code, phone_number_type, and action (ordering or porting). Once created and fulfilled, the group can be associated with any number order or porting order that matches those criteria. The pre-filled requirements are automatically applied to the order, which then undergoes the standard regulatory review process.

​
Constraints

  • Requirement groups are optional in most countries. You can fulfill requirements individually on each order or use requirement groups to pre-fill requirements.
  • In the following countries, it is mandatory to use fulfilled requirement groups when placing a number order: CH (Switzerland), DK (Denmark), IT (Italy), NO (Norway), PT (Portugal), and SE (Sweden).
  • A fulfilled requirement group means that every requirement in the group has an associated value. You cannot create an order with an empty requirement group in countries where requirement groups are mandatory.
  • Requirement groups can only be associated with orders that match the group’s country_code, phone_number_type, and action combination. For example, a DE local ordering requirement group can only be applied to DE local number orders.
  • Number orders do not automatically synchronize with requirement group changes. You must make another API request to apply updated requirement group values to existing orders.

​
Requirement group statuses

Each requirement group has a status that indicates its current state and what review process orders using it will undergo. All requirement groups except no-longer-eligible can be used for orders.

​
Pre-approval

By default, orders using requirement groups go through standard review, where Number Ops manually reviews the requirements on each individual order after it is placed. This review process can take time before numbers activate. Pre-approval is an optional feature that allows you to submit a requirement group for review before placing orders. Once a requirement group is pre-approved, orders using it can activate automatically within a few minutes, bypassing the standard review process. You do not need to pre-approve a requirement group to use it for ordering. Any requirement group (except no-longer-eligible) can be associated with orders immediately after creation and fulfillment. When to use pre-approval: Pre-approval makes sense when you will reuse the same requirement group for multiple orders AND you need quick number activation. Orders using approved requirement groups will activate automatically within a few minutes, bypassing the standard review process. When to skip pre-approval: If you’re only using a requirement group for a few orders or don’t need immediate activation, you can skip pre-approval entirely. Orders using unapproved, pending-approval, declined, or expired requirement groups will go through the standard review process. Pre-approval limitations:
  • Country coverage: Requirement group pre-approval is supported in most countries, but not all. Some countries, such as Italy, do not support pre-approval. If you attempt to submit a requirement group for pre-approval in a country where it is not supported, you will receive an error.
  • Address validation: If the requirement group has an address requirement, ensure that ordered phone numbers comply with that address requirement. For example, if the requirement specifies an address matching the DID area code and the approved address is in Munich, order a phone number in Munich. Ordering a number in a different area (e.g., Berlin) will cause the order to undergo standard review instead of immediate activation. If the requirement specifies a national address, the address must be within the same country as the ordered phone number.

​
How it works

​
Step 1: Create a requirement group

Use the POST /v2/requirement_groups endpoint to create a requirement group. Each group requires country_code (ISO Alpha-2 format), phone_number_type (local, toll_free, national, mobile, or shared_cost), and action (ordering or porting). Optionally include a customer_reference to label the requirement group for your own tracking purposes.

​
Step 2: View the requirement group

List all requirement groups using GET /v2/requirement_groups, or retrieve a specific group by ID using GET /v2/requirement_groups/:id. The regulatory_requirements array lists each requirement that needs to be fulfilled for your order. Each requirement has a unique requirement_id. For detailed information about requirement types, see the regulatory requirements guide.

​
Step 3: Fulfill the requirement group

Update the requirement group with values using PATCH /v2/requirement_groups/:id. In the request body, specify each requirement_id and its associated value. For more information, check out the regulatory requirements guide.

​
Step 4: Associate the requirement group with an order

You can associate a requirement group with number orders or porting orders. For new number orders: First, search for available phone numbers and identify the number(s) you would like to purchase. Then create a number order using POST /v2/number_orders, including the requirement_group_id in each phone_number object. The requirement group values will populate the order and undergo regulatory review. For existing pending sub number orders: Update a pending sub number order using POST /v2/sub_number_orders/:id/requirement_group. Include the requirement_group_id in the request body. When updating an existing order, the requirement group must be fulfilled. The request will only update non-approved requirements. If a requirement is already approved, its value remains unchanged. For porting orders: Associate a requirement group with a porting order using PATCH /v2/porting_orders/:id, including the requirement_group_id in the request body. This request can be performed when the order is in draft, in-process, or exception status. Any existing requirement values will be overwritten by the requirement group.

​
Step 5 (Optional): Submit for pre-approval

To submit a requirement group for pre-approval, use the POST /v2/requirement_groups/:id/submit_for_approval endpoint. The requirement group will transition to pending-approval status after submission. Telnyx will review the submitted group. If all requirements are met, the group’s status is set to approved. If requirements are rejected, the status will move to declined. If the requirement group is rejected, Number Ops will communicate feedback via comments on the requirement group. You can view and respond to these comments using the comments API: When using the comments API for requirement groups, set comment_record_type to requirement_group and comment_record_id to the requirement_group_id. Once a requirement group is approved, associate the requirement_group_id with orders following the process described in Step 4.

​
Webhook notifications

You can configure webhook notifications to receive updates about requirement group status changes. Follow this support article to set up webhook notifications. Select the “Requirement Group Status Change” notification setting to receive webhooks when a requirement group transitions between statuses (e.g., from pending-approval to approved or declined).

​
Action requirements

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/action-ordering-requirement.md

​
Overview

Action requirements are a special type of regulatory requirement for international phone number orders that cannot be fulfilled by submitting documents or text information. Instead, these requirements need the end user to complete an external action, such as identity verification through a third-party service. Each action requirement type may have different fulfillment steps depending on the specific verification needed. This guide provides detailed instructions for completing each action requirement. As new action requirement types are introduced, this guide will be updated with their specific fulfillment processes.

​
Australia mobile ID verification

Australia mobile number orders require end user identity verification to comply with local telecommunications regulations. To facilitate a secure and efficient verification experience, Telnyx has partnered with Onfido, a trusted identity verification provider.

​
Requirement ID

The Australia mobile ID verification requirement has the following identifier:
  • Requirement ID: b7c72fb8-fa08-4529-aaf6-b9117d3f3698
This ID is used when initiating the verification process through the external requirements endpoint.

​
Verification process

To complete ID verification for an Australia mobile number order:
  1. Generate a unique verification link by making a request to the POST /v2/external_requirements/{requirement_id}/sub_number_orders/{sub_order_id} endpoint. Include the end user’s first_name and last_name in the request body.
  2. The API returns a URL in the requirement_action.value field. Share this URL with the end user to access Onfido’s secure ID verification portal.
  3. The end user visits the provided URL and completes the identity verification process by submitting required identification documents through the Onfido portal.
  4. Once submitted, the verification is reviewed. Upon approval, the requirement is automatically marked as completed on the number order.
  5. The order’s requirements_met field updates to true, allowing the order to proceed to the next stage.

​
Documents

​
Documents

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/documents.md

​
Overview

The Documents API allows you to upload and manage files that are required for regulatory compliance, identity verification, and other services on your Telnyx account. Documents are commonly used when ordering phone numbers in countries that require proof of identity, proof of address, or other supporting documentation. Once uploaded, documents must be linked to a service (such as a number order or regulatory requirement) within 30 minutes, or they will be automatically deleted. This ensures that only actively used documents are retained on your account. You can upload documents by sending base64-encoded file content or by uploading the file directly via multipart form data.

​
Constraints

  • Maximum file size is 20 MB.
  • Maximum filename length is 512 characters.
  • Filenames must contain only printable Unicode characters. Non-printable characters (control characters) are not allowed.
  • Spaces in filenames are automatically removed. For example, my document.pdf becomes mydocument.pdf.
  • The file extension is automatically appended based on the detected MIME type, even if omitted from the filename.
  • Uploaded documents must be linked to a service within 30 minutes or they will be automatically deleted.
  • Documents that are linked to a service cannot be deleted until they are unlinked.
  • All uploaded documents are scanned for malware. Documents flagged as infected will be denied.

​
Accepted file types

The following file types are accepted for upload:

​
Upload methods

Documents can be uploaded using any of three methods through the POST /documents endpoint:
  • Base64: Provide the file content as a base64-encoded string in the file field, along with a filename.
  • Multipart form data: Upload the file directly as binary data using multipart/form-data.
You can optionally include a customer_reference with any upload method to associate your own tracking identifier with the document.

​
Antivirus scan statuses

All uploaded documents are scanned for malware. The av_scan_status field indicates the scan result: When a document is attached to a service on your account (such as a number order or regulatory requirement), a document link is automatically created. You do not need to create these links manually — they are managed by the services that use the document. You can use the GET /document_links endpoint to view which services a document is currently associated with. You can filter results by document_id, linked_record_type, or linked_resource_id.

​
API Reference (Regulatory & Documents)

​
Requirements

​
Requirement Types

​
Regulatory Requirements

​
Requirement Groups

​
Verified Numbers

​
Documents

​
Bundles

​
User Bundles

​
Voicemail

​
Voice Channels

​
Dynamic Emergency Addresses

​
Dynamic Emergency Endpoints