# 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://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/numbers/regulatory-documents.txt ## 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](https://developers.telnyx.com/api-reference/requirements/list-all-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](https://developers.telnyx.com/docs/numbers/phone-numbers/requirement-groups) to apply all the values at once. To view additional information on a regulatory requirement (description, examples, etc.), perform a [GET /requirement_types/](https://developers.telnyx.com/api-reference/requirement-types/retrieve-a-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](https://developers.telnyx.com/api-reference/addresses/creates-an-address) 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](https://developers.telnyx.com/api-reference/documents/upload-a-document) 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](https://developers.telnyx.com/docs/numbers/phone-numbers/action-ordering-requirement) 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](https://developers.telnyx.com/docs/numbers/phone-numbers/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](https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements) 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. | Status | Description | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | unapproved | Default status after creation. Has not been submitted for pre-approval. Orders using this group go through standard review. | | pending-approval | Submitted and under review. Orders using this group go through standard review. | | approved | Passed review. Orders using this group activate automatically within a few minutes. | | declined | One or more requirements were rejected during pre-approval. Orders using this group go through standard review. Expect similar rejections on orders using this group. | | expired | Requirement(s) exceeded validity window. Orders using this group go through standard review. Expect similar rejections on orders using this group. Review `regulatory_requirements.expires_at` for expiration dates. | | no-longer-eligible | Regulatory requirements have changed. Cannot be used for orders. Create a new requirement group with current requirements. | ## 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](/api-reference/requirement-groups/create-a-new-requirement-group) 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](/api-reference/requirement-groups/list-requirement-groups), or retrieve a specific group by ID using [GET /v2/requirement_groups/:id](/api-reference/requirement-groups/get-a-single-requirement-group-by-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](https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements). ### Step 3: Fulfill the requirement group Update the requirement group with values using [PATCH /v2/requirement_groups/:id](/api-reference/requirement-groups/update-requirement-values-in-requirement-group). In the request body, specify each `requirement_id` and its associated value. For more information, check out the [regulatory requirements guide](https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements). ### 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](/api-reference/phone-number-search/list-available-phone-numbers) and identify the number(s) you would like to purchase. Then create a number order using [POST /v2/number_orders](/api-reference/phone-number-orders/create-a-number-order), 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](https://developers.telnyx.com/api-reference/requirement-groups/update-requirement-group-for-a-sub-number-order). 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](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order), 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](/api-reference/requirement-groups/submit-a-requirement-group-for-approval). 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: - [POST /v2/comments](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-comment) to create a comment. - [GET /v2/comments](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-all-comments) to retrieve all comments. 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](https://support.telnyx.com/en/articles/4277896-notification-settings) 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](https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements). 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](https://onfido.com/), 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](https://developers.telnyx.com/api-reference/overview). 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: | File type | MIME type | | :--------------------- | :------------------------------------------------------------------------ | | PDF | `application/pdf` | | PNG | `image/png` | | JPEG | `image/jpeg` | | CSV | `text/csv`, `application/csv` | | Plain text | `text/plain` | | JSON | `application/json` | | Word (.docx) | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | | Word (.doc) | `application/msword` | | Excel (.xlsx) | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | | Excel (.xls) | `application/vnd.ms-excel` | ## Upload methods Documents can be uploaded using any of three methods through the [POST /documents endpoint](https://developers.telnyx.com/api-reference/documents/upload-a-document): - **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: | Status | Description | | :------------- | :----------------------------------------------------------- | | `pending_scan` | The document is queued for scanning. | | `scanned` | The scan completed and no threats were detected. | | `infected` | The scan detected malware. The document will be denied. | | `not_scanned` | The document has not yet been scanned. | ## Document links 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](https://developers.telnyx.com/api-reference/documents/list-all-document-links) 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 - [List all requirements](https://developers.telnyx.com/api-reference/requirements/list-all-requirements.md): List all requirements with filtering, sorting, and pagination - [Retrieve a document requirement](https://developers.telnyx.com/api-reference/requirements/retrieve-a-document-requirement.md): Retrieve a document requirement record ### Requirement Types - [List all requirement types](https://developers.telnyx.com/api-reference/requirement-types/list-all-requirement-types.md): List all requirement types ordered by created_at descending - [Retrieve a requirement types](https://developers.telnyx.com/api-reference/requirement-types/retrieve-a-requirement-types.md): Retrieve a requirement type by id ### Regulatory Requirements - [Retrieve regulatory requirements](https://developers.telnyx.com/api-reference/regulatory-requirements/retrieve-regulatory-requirements.md) ### Requirement Groups - [List requirement groups](https://developers.telnyx.com/api-reference/requirement-groups/list-requirement-groups.md) - [Create a new requirement group](https://developers.telnyx.com/api-reference/requirement-groups/create-a-new-requirement-group.md) - [Get a single requirement group by ID](https://developers.telnyx.com/api-reference/requirement-groups/get-a-single-requirement-group-by-id.md) - [Update requirement values in requirement group](https://developers.telnyx.com/api-reference/requirement-groups/update-requirement-values-in-requirement-group.md) - [Delete a requirement group by ID](https://developers.telnyx.com/api-reference/requirement-groups/delete-a-requirement-group-by-id.md) - [Submit a Requirement Group for Approval](https://developers.telnyx.com/api-reference/requirement-groups/submit-a-requirement-group-for-approval.md) ### Verified Numbers - [List all Verified Numbers](https://developers.telnyx.com/api-reference/verified-numbers/list-all-verified-numbers.md): Gets a paginated list of Verified Numbers. - [Request phone number verification](https://developers.telnyx.com/api-reference/verified-numbers/request-phone-number-verification.md): Initiates phone number verification procedure. Supports DTMF extension dialing for voice calls to numbers behind IVR systems. - [Retrieve a verified number](https://developers.telnyx.com/api-reference/verified-numbers/retrieve-a-verified-number.md) - [Delete a verified number](https://developers.telnyx.com/api-reference/verified-numbers/delete-a-verified-number.md) - [Submit verification code](https://developers.telnyx.com/api-reference/verified-numbers/submit-verification-code.md) ### Documents - [List all document links](https://developers.telnyx.com/api-reference/documents/list-all-document-links.md): List all documents links ordered by created_at descending. - [List all documents](https://developers.telnyx.com/api-reference/documents/list-all-documents.md): List all documents ordered by created_at descending. - [Upload a document](https://developers.telnyx.com/api-reference/documents/upload-a-document.md): Upload a document.

Uploaded files must be linked to a service within 30 minutes or they will be automatically deleted. - [Retrieve a document](https://developers.telnyx.com/api-reference/documents/retrieve-a-document.md): Retrieve a document. - [Update a document](https://developers.telnyx.com/api-reference/documents/update-a-document.md): Update a document. - [Delete a document](https://developers.telnyx.com/api-reference/documents/delete-a-document.md): Delete a document.

A document can only be deleted if it's not linked to a service. If it is linked to a service, it must be unlinked prior to deleti… - [Download a document](https://developers.telnyx.com/api-reference/documents/download-a-document.md): Download a document. - [Generate a temporary download link for a document](https://developers.telnyx.com/api-reference/documents/generate-a-temporary-download-link-for-a-document.md): Generates a temporary pre-signed URL that can be used to download the document directly from the storage backend without authentication. ### Bundles - [Retrieve Bundles](https://developers.telnyx.com/api-reference/bundles/retrieve-bundles.md): Get all allowed bundles. - [Get Bundle By Id](https://developers.telnyx.com/api-reference/bundles/get-bundle-by-id.md): Get a single bundle by ID. ### User Bundles - [Get User Bundles](https://developers.telnyx.com/api-reference/user-bundles/get-user-bundles.md): Get a paginated list of user bundles. - [Create User Bundles](https://developers.telnyx.com/api-reference/user-bundles/create-user-bundles.md): Creates multiple user bundles for the user. - [Get Unused User Bundles](https://developers.telnyx.com/api-reference/user-bundles/get-unused-user-bundles.md): Returns all user bundles that aren't in use. - [Get User Bundle by Id](https://developers.telnyx.com/api-reference/user-bundles/get-user-bundle-by-id.md): Retrieves a user bundle by its ID. - [Deactivate User Bundle](https://developers.telnyx.com/api-reference/user-bundles/deactivate-user-bundle.md): Deactivates a user bundle by its ID. - [Get User Bundle Resources](https://developers.telnyx.com/api-reference/user-bundles/get-user-bundle-resources.md): Retrieves the resources of a user bundle by its ID. ### Voicemail - [Get voicemail](https://developers.telnyx.com/api-reference/voicemail/get-voicemail.md): Returns the voicemail settings for a phone number - [Create voicemail](https://developers.telnyx.com/api-reference/voicemail/create-voicemail.md): Create voicemail settings for a phone number - [Update voicemail](https://developers.telnyx.com/api-reference/voicemail/update-voicemail.md): Update voicemail settings for a phone number ### Voice Channels - [List your voice channels for non-US zones](https://developers.telnyx.com/api-reference/voice-channels/list-your-voice-channels-for-non-us-zones.md): Returns the non-US voice channels for your account. voice channels allow you to use Channel Billing for calls to your Telnyx phone numbers. Please check the