--- name: telnyx-numbers-compliance-ruby description: >- Manage regulatory requirements, number bundles, supporting documents, and verified numbers for compliance. This skill provides Ruby SDK examples. metadata: author: telnyx product: numbers-compliance language: ruby generated_by: telnyx-openapi-pipeline --- # Telnyx Numbers Compliance - Ruby ## Installation ```bash gem install telnyx ``` ## Setup ```ruby require "telnyx" client = Telnyx::Client.new( api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted public_key: ENV["TELNYX_PUBLIC_KEY"], # Required for client.webhooks.unwrap (webhook verification) ) ``` All examples below assume `client` is already initialized as shown above. ## Error Handling All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code: ```ruby begin result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello") rescue Telnyx::Errors::APIConnectionError puts "Network error — check connectivity and retry" raise rescue Telnyx::Errors::RateLimitError # 429: rate limited — wait, then retry the request (bounded exponential backoff) sleep(1) # Check Retry-After header for actual delay # ...retry the call here (give up after a few attempts); otherwise re-raise: raise rescue Telnyx::Errors::APIStatusError => e puts "API error #{e.status}: #{e.message}" if e.status == 422 puts "Validation error — check required fields and formats" end raise # A failed request must never look like success to the caller end ``` Common error codes: `401` invalid API key, `403` insufficient permissions, `404` resource not found, `422` validation error (check field formats), `429` rate limited (retry with exponential backoff). ## Important Notes - **Phone numbers** must be in E.164 format (e.g., `+13125550001`). Include the `+` prefix and country code. No spaces, dashes, or parentheses. - **Pagination:** Use `.auto_paging_each` for automatic iteration: `page.auto_paging_each { |item| puts item.id }`. ## Retrieve Bundles Returns a paginated list of the billing bundles available to your account, with support for filtering. `GET /bundle_pricing/billing_bundles` ```ruby page = client.bundle_pricing.billing_bundles.list puts(page) ``` Returns: `cost_code` (string), `created_at` (date), `currency` (string), `id` (uuid), `is_public` (boolean), `mrc_price` (float), `name` (string), `slug` (string), `specs` (array[string]) ## Get Bundle By Id Returns the details of a single billing bundle by its ID, so you can inspect its contents before purchasing a user bundle. `GET /bundle_pricing/billing_bundles/{bundle_id}` ```ruby billing_bundle = client.bundle_pricing.billing_bundles.retrieve("8661948c-a386-4385-837f-af00f40f111a") puts(billing_bundle) ``` Returns: `active` (boolean), `bundle_limits` (array[object]), `cost_code` (string), `created_at` (date), `id` (uuid), `is_public` (boolean), `name` (string), `slug` (string) ## Get User Bundles Returns a paginated list of the bundles active on your account, with support for filtering. `GET /bundle_pricing/user_bundles` ```ruby page = client.bundle_pricing.user_bundles.list puts(page) ``` Returns: `active` (boolean), `billing_bundle` (object), `created_at` (date), `id` (uuid), `resources` (array[object]), `updated_at` (date), `user_id` (uuid) ## Create User Bundles Creates multiple user bundles for the user. `POST /bundle_pricing/user_bundles/bulk` Optional: `idempotency_key` (uuid), `items` (array[object]) ```ruby user_bundle = client.bundle_pricing.user_bundles.create puts(user_bundle) ``` Returns: `active` (boolean), `billing_bundle` (object), `created_at` (date), `id` (uuid), `resources` (array[object]), `updated_at` (date), `user_id` (uuid) ## Get Unused User Bundles Returns all user bundles that aren't in use. `GET /bundle_pricing/user_bundles/unused` ```ruby response = client.bundle_pricing.user_bundles.list_unused puts(response) ``` Returns: `billing_bundle` (object), `user_bundle_ids` (array[string]) ## Get User Bundle by Id Returns the details of a single user bundle on your account by its ID. `GET /bundle_pricing/user_bundles/{user_bundle_id}` ```ruby user_bundle = client.bundle_pricing.user_bundles.retrieve("ca1d2263-d1f1-43ac-ba53-248e7a4bb26a") puts(user_bundle) ``` Returns: `active` (boolean), `billing_bundle` (object), `created_at` (date), `id` (uuid), `resources` (array[object]), `updated_at` (date), `user_id` (uuid) ## Deactivate User Bundle Deactivates the specified user bundle on your account and returns the deactivated bundle. `DELETE /bundle_pricing/user_bundles/{user_bundle_id}` ```ruby response = client.bundle_pricing.user_bundles.deactivate("ca1d2263-d1f1-43ac-ba53-248e7a4bb26a") puts(response) ``` Returns: `active` (boolean), `billing_bundle` (object), `created_at` (date), `id` (uuid), `resources` (array[object]), `updated_at` (date), `user_id` (uuid) ## Get User Bundle Resources Retrieves the resources of a user bundle by its ID. `GET /bundle_pricing/user_bundles/{user_bundle_id}/resources` ```ruby response = client.bundle_pricing.user_bundles.list_resources("ca1d2263-d1f1-43ac-ba53-248e7a4bb26a") puts(response) ``` Returns: `created_at` (date), `id` (uuid), `resource` (string), `resource_type` (string), `updated_at` (date) ## List all document links List all documents links ordered by created_at descending. `GET /document_links` ```ruby page = client.document_links.list puts(page) ``` Returns: `created_at` (string), `document_id` (uuid), `id` (uuid), `linked_record_type` (string), `linked_resource_id` (string), `record_type` (string), `updated_at` (string) ## List all documents List all documents ordered by created_at descending. `GET /documents` ```ruby page = client.documents.list puts(page) ``` Returns: `av_scan_status` (enum: scanned, infected, pending_scan, not_scanned), `content_type` (string), `created_at` (string), `customer_reference` (string), `filename` (string), `id` (uuid), `record_type` (string), `sha256` (string), `size` (object), `status` (enum: pending, verified, denied), `updated_at` (string) ## Upload a document Upload a document. Uploaded files must be linked to a service within 30 minutes or they will be automatically deleted. `POST /documents` Optional: `customer_reference` (string), `file` (byte), `filename` (string), `url` (string) ```ruby response = client.documents.upload_json(document: {}) puts(response) ``` Returns: `av_scan_status` (enum: scanned, infected, pending_scan, not_scanned), `content_type` (string), `created_at` (string), `customer_reference` (string), `filename` (string), `id` (uuid), `record_type` (string), `sha256` (string), `size` (object), `status` (enum: pending, verified, denied), `updated_at` (string) ## Retrieve a document Returns the details of a single document on your account, including its metadata. `GET /documents/{id}` ```ruby document = client.documents.retrieve("6a09cdc3-8948-47f0-aa62-74ac943d6c58") puts(document) ``` Returns: `av_scan_status` (enum: scanned, infected, pending_scan, not_scanned), `content_type` (string), `created_at` (string), `customer_reference` (string), `filename` (string), `id` (uuid), `record_type` (string), `sha256` (string), `size` (object), `status` (enum: pending, verified, denied), `updated_at` (string) ## Update a document Updates the specified document's attributes and returns the updated document. `PATCH /documents/{id}` Optional: `av_scan_status` (enum: scanned, infected, pending_scan, not_scanned), `content_type` (string), `created_at` (string), `customer_reference` (string), `filename` (string), `id` (uuid), `record_type` (string), `sha256` (string), `size` (object), `status` (enum: pending, verified, denied), `updated_at` (string) ```ruby document = client.documents.update("6a09cdc3-8948-47f0-aa62-74ac943d6c58") puts(document) ``` Returns: `av_scan_status` (enum: scanned, infected, pending_scan, not_scanned), `content_type` (string), `created_at` (string), `customer_reference` (string), `filename` (string), `id` (uuid), `record_type` (string), `sha256` (string), `size` (object), `status` (enum: pending, verified, denied), `updated_at` (string) ## Delete a document 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 deleting. `DELETE /documents/{id}` ```ruby document = client.documents.delete("6a09cdc3-8948-47f0-aa62-74ac943d6c58") puts(document) ``` Returns: `av_scan_status` (enum: scanned, infected, pending_scan, not_scanned), `content_type` (string), `created_at` (string), `customer_reference` (string), `filename` (string), `id` (uuid), `record_type` (string), `sha256` (string), `size` (object), `status` (enum: pending, verified, denied), `updated_at` (string) ## Download a document Downloads the raw file content of the specified document as originally uploaded. `GET /documents/{id}/download` ```ruby response = client.documents.download("6a09cdc3-8948-47f0-aa62-74ac943d6c58") puts(response) ``` ## Generate a temporary download link for a document Generates a temporary pre-signed URL that can be used to download the document directly from the storage backend without authentication. `GET /documents/{id}/download_link` ```ruby response = client.documents.generate_download_link("550e8400-e29b-41d4-a716-446655440000") puts(response) ``` Returns: `url` (uri) ## Get action requirement details for a sub number order Returns the input fields an action requirement needs and the current requirement action for a sub number order. Action requirements are fulfilled by an external step rather than by uploading documents. Australia mobile ID verification is currently the only action requirement. `GET /external_requirements/{regulatory_requirement_id}/sub_number_orders/{sub_number_order_id}` ```ruby response = client.external_requirements.sub_number_orders.retrieve("regulatory_requirement_id", "sub_number_order_id") puts(response) ``` Returns: `fields_required` (array[object]), `regulatory_requirement_id` (uuid), `requirement_action` (object) ## Fulfill an action requirement for a sub number order Submits the end user's details to the external verification provider and returns the requirement action. Australia mobile ID verification is currently the only action requirement. It generates a unique Onfido verification link, returned in `requirement_action.value`, which you share with the end user. `POST /external_requirements/{regulatory_requirement_id}/sub_number_orders/{sub_number_order_id}` — Required: `requirement` ```ruby response = client.external_requirements.sub_number_orders.update("regulatory_requirement_id", "sub_number_order_id", requirement: {}) puts(response) ``` Returns: `regulatory_requirement_id` (uuid), `requirement_action` (object), `sub_order_id` (uuid) ## Update requirement group for a phone number order Associates an existing requirement group with a phone number in a number order. The response contains the updated number-order phone-number details. `POST /number_order_phone_numbers/{id}/requirement_group` — Required: `requirement_group_id` ```ruby response = client.number_order_phone_numbers.update_requirement_group( "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", requirement_group_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ) puts(response) ``` Returns: `bundle_id` (uuid), `country_code` (string), `deadline` (date-time), `id` (uuid), `is_block_number` (boolean), `locality` (string), `order_request_id` (uuid), `phone_number` (string), `phone_number_type` (string), `record_type` (string), `regulatory_requirements` (array[object]), `requirements_met` (boolean), `requirements_status` (string), `status` (string), `sub_number_order_id` (uuid) ## Retrieve regulatory requirements for a list of phone numbers Returns the regulatory requirements that apply to the supplied comma-separated phone numbers. The response includes the matching requirement records and pagination metadata. `GET /phone_numbers_regulatory_requirements` ```ruby phone_numbers_regulatory_requirement = client.phone_numbers_regulatory_requirements.retrieve puts(phone_numbers_regulatory_requirement) ``` Returns: `phone_number` (string), `phone_number_type` (string), `record_type` (string), `region_information` (array[object]), `regulatory_requirements` (array[object]) ## Retrieve regulatory requirements Returns regulatory requirements for number ordering, porting, or other supported actions. Results can be filtered by phone number, requirement group, country, number type, and action. `GET /regulatory_requirements` ```ruby regulatory_requirement = client.regulatory_requirements.retrieve puts(regulatory_requirement) ``` Returns: `action` (string), `country_code` (string), `phone_number_type` (string), `regulatory_requirements` (array[object]) ## List requirement groups Returns regulatory requirement groups for the account. Results can be filtered by country, number type, action, approval status, and customer reference. `GET /requirement_groups` ```ruby requirement_groups = client.requirement_groups.list puts(requirement_groups) ``` ## Create a new requirement group Creates a regulatory requirement group for a country, number type, and ordering or porting action. Optional customer-reference and requirement values are retained on the created group. `POST /requirement_groups` — Required: `country_code`, `phone_number_type`, `action` Optional: `customer_reference` (string), `regulatory_requirements` (array[object]) ```ruby requirement_group = client.requirement_groups.create(action: :ordering, country_code: "US", phone_number_type: :local) puts(requirement_group) ``` Returns: `action` (string), `country_code` (string), `created_at` (date-time), `customer_reference` (string), `id` (string), `phone_number_type` (string), `record_type` (string), `regulatory_requirements` (array[object]), `status` (enum: approved, unapproved, pending-approval, declined, expired), `updated_at` (date-time) ## Get a single requirement group by ID Returns the regulatory requirement group identified by `id`, including its requirement values and current approval status. `GET /requirement_groups/{id}` ```ruby requirement_group = client.requirement_groups.retrieve("550e8400-e29b-41d4-a716-446655440000") puts(requirement_group) ``` Returns: `action` (string), `country_code` (string), `created_at` (date-time), `customer_reference` (string), `id` (string), `phone_number_type` (string), `record_type` (string), `regulatory_requirements` (array[object]), `status` (enum: approved, unapproved, pending-approval, declined, expired), `updated_at` (date-time) ## Update requirement values in requirement group Updates the customer reference or regulatory requirement values on the specified requirement group. The response contains the updated group. `PATCH /requirement_groups/{id}` Optional: `customer_reference` (string), `regulatory_requirements` (array[object]) ```ruby requirement_group = client.requirement_groups.update("550e8400-e29b-41d4-a716-446655440000") puts(requirement_group) ``` Returns: `action` (string), `country_code` (string), `created_at` (date-time), `customer_reference` (string), `id` (string), `phone_number_type` (string), `record_type` (string), `regulatory_requirements` (array[object]), `status` (enum: approved, unapproved, pending-approval, declined, expired), `updated_at` (date-time) ## Delete a requirement group by ID Deletes the regulatory requirement group identified by `id`. The response contains the deleted requirement-group representation. `DELETE /requirement_groups/{id}` ```ruby requirement_group = client.requirement_groups.delete("550e8400-e29b-41d4-a716-446655440000") puts(requirement_group) ``` Returns: `action` (string), `country_code` (string), `created_at` (date-time), `customer_reference` (string), `id` (string), `phone_number_type` (string), `record_type` (string), `regulatory_requirements` (array[object]), `status` (enum: approved, unapproved, pending-approval, declined, expired), `updated_at` (date-time) ## Submit a Requirement Group for Approval Submits the specified regulatory requirement group for approval. The response contains the requirement group with its resulting approval status. `POST /requirement_groups/{id}/submit_for_approval` ```ruby requirement_group = client.requirement_groups.submit_for_approval("550e8400-e29b-41d4-a716-446655440000") puts(requirement_group) ``` Returns: `action` (string), `country_code` (string), `created_at` (date-time), `customer_reference` (string), `id` (string), `phone_number_type` (string), `record_type` (string), `regulatory_requirements` (array[object]), `status` (enum: approved, unapproved, pending-approval, declined, expired), `updated_at` (date-time) ## List all requirement types List all requirement types ordered by created_at descending `GET /requirement_types` ```ruby requirement_types = client.requirement_types.list puts(requirement_types) ``` Returns: `acceptance_criteria` (object), `created_at` (string), `description` (string), `example` (string), `id` (uuid), `name` (string), `record_type` (string), `type` (enum: document, address, textual), `updated_at` (string) ## Retrieve a requirement types Returns the details of a single requirement type by its identifier, describing a kind of documentation needed for regulatory purposes. `GET /requirement_types/{id}` ```ruby requirement_type = client.requirement_types.retrieve("a38c217a-8019-48f8-bff6-0fdd9939075b") puts(requirement_type) ``` Returns: `acceptance_criteria` (object), `created_at` (string), `description` (string), `example` (string), `id` (uuid), `name` (string), `record_type` (string), `type` (enum: document, address, textual), `updated_at` (string) ## List all requirements List all requirements with filtering, sorting, and pagination `GET /requirements` ```ruby page = client.requirements.list puts(page) ``` Returns: `action` (enum: both, branded_calling, ordering, porting), `country_code` (string), `created_at` (string), `effective_end_at` (date-time), `effective_start_at` (date-time), `id` (uuid), `locality` (string), `phone_number_type` (enum: local, mobile, multipurpose, national, shared_cost, toll_free), `record_type` (string), `requirement_types` (array[object]), `updated_at` (string), `version` (integer) ## Retrieve a document requirement Returns a single document requirement record by its identifier, describing the documentation needed for number-related actions. A specific requirement version can be requested. `GET /requirements/{id}` ```ruby requirement = client.requirements.retrieve("a9dad8d5-fdbd-49d7-aa23-39bb08a5ebaa") puts(requirement) ``` Returns: `action` (enum: both, branded_calling, ordering, porting), `country_code` (string), `created_at` (string), `effective_end_at` (date-time), `effective_start_at` (date-time), `id` (uuid), `locality` (string), `phone_number_type` (enum: local, mobile, multipurpose, national, shared_cost, toll_free), `record_type` (string), `requirement_types` (array[object]), `updated_at` (string), `version` (integer) ## Update requirement group for a sub number order Associates an existing requirement group with the specified sub number order. The response contains the updated sub number order requirement-group relationship. `POST /sub_number_orders/{id}/requirement_group` — Required: `requirement_group_id` ```ruby response = client.sub_number_orders.update_requirement_group( "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", requirement_group_id: "a4b201f9-8646-4e54-a7d2-b2e403eeaf8c" ) puts(response) ``` Returns: `country_code` (string), `created_at` (date-time), `customer_reference` (string), `id` (uuid), `is_block_sub_number_order` (boolean), `order_request_id` (uuid), `phone_number_type` (string), `phone_numbers` (array[object]), `phone_numbers_count` (integer), `record_type` (string), `regulatory_requirements` (array[object]), `requirements_met` (boolean), `status` (string), `updated_at` (date-time) ## List all user addresses Returns a paginated list of your user addresses, with support for filtering and sorting. `GET /user_addresses` ```ruby page = client.user_addresses.list puts(page) ``` Returns: `administrative_area` (string), `borough` (string), `business_name` (string), `country_code` (string), `created_at` (string), `customer_reference` (string), `extended_address` (string), `first_name` (string), `id` (uuid), `last_name` (string), `locality` (string), `neighborhood` (string), `phone_number` (string), `postal_code` (string), `record_type` (string), `street_address` (string), `updated_at` (string) ## Creates a user address Creates a new user address from the provided details and returns the created address. `POST /user_addresses` — Required: `first_name`, `last_name`, `business_name`, `street_address`, `locality`, `country_code` Optional: `administrative_area` (string), `borough` (string), `customer_reference` (string), `extended_address` (string), `neighborhood` (string), `phone_number` (string), `postal_code` (string), `skip_address_verification` (boolean) ```ruby user_address = client.user_addresses.create( business_name: "Toy-O'Kon", country_code: "US", first_name: "Alfred", last_name: "Foster", locality: "Austin", street_address: "600 Congress Avenue" ) puts(user_address) ``` Returns: `administrative_area` (string), `borough` (string), `business_name` (string), `country_code` (string), `created_at` (string), `customer_reference` (string), `extended_address` (string), `first_name` (string), `id` (uuid), `last_name` (string), `locality` (string), `neighborhood` (string), `phone_number` (string), `postal_code` (string), `record_type` (string), `street_address` (string), `updated_at` (string) ## Retrieve a user address Retrieves the details of an existing user address. `GET /user_addresses/{id}` ```ruby user_address = client.user_addresses.retrieve("550e8400-e29b-41d4-a716-446655440000") puts(user_address) ``` Returns: `administrative_area` (string), `borough` (string), `business_name` (string), `country_code` (string), `created_at` (string), `customer_reference` (string), `extended_address` (string), `first_name` (string), `id` (uuid), `last_name` (string), `locality` (string), `neighborhood` (string), `phone_number` (string), `postal_code` (string), `record_type` (string), `street_address` (string), `updated_at` (string) ## List all Verified Numbers Gets a paginated list of Verified Numbers. `GET /verified_numbers` ```ruby page = client.verified_numbers.list puts(page) ``` Returns: `phone_number` (string), `record_type` (enum: verified_number), `verified_at` (string) ## Request phone number verification Initiates phone number verification procedure. Supports DTMF extension dialing for voice calls to numbers behind IVR systems. `POST /verified_numbers` — Required: `phone_number`, `verification_method` Optional: `extension` (string) ```ruby verified_number = client.verified_numbers.create(phone_number: "+15551234567", verification_method: :sms) puts(verified_number) ``` Returns: `phone_number` (string), `verification_method` (string) ## Retrieve a verified number Retrieve the details of a verified number on your account. `GET /verified_numbers/{phone_number}` ```ruby verified_number_data_wrapper = client.verified_numbers.retrieve("+15551234567") puts(verified_number_data_wrapper) ``` Returns: `phone_number` (string), `record_type` (enum: verified_number), `verified_at` (string) ## Delete a verified number Remove a verified number from your account. `DELETE /verified_numbers/{phone_number}` ```ruby verified_number_data_wrapper = client.verified_numbers.delete("+15551234567") puts(verified_number_data_wrapper) ``` Returns: `phone_number` (string), `record_type` (enum: verified_number), `verified_at` (string) ## Submit verification code Submit the verification code received via the selected verification method to verify a phone number. `POST /verified_numbers/{phone_number}/actions/verify` — Required: `verification_code` ```ruby verified_number_data_wrapper = client.verified_numbers.actions.submit_verification_code("+15551234567", verification_code: "123456") puts(verified_number_data_wrapper) ``` Returns: `phone_number` (string), `record_type` (enum: verified_number), `verified_at` (string)