:html_theme.sidebar_secondary.remove: true

===============================
Welcome to DIDWW Documentation
===============================

Build, configure, and scale voice and messaging services with DIDWW using self-service tools, API, and integrations.

Get Started
===========

.. grid:: 1 2 2 3
    :gutter: 4
    :padding: 0

    .. grid-item-card:: **Phone Numbers**
        :link: phone-numbers/index
        :link-type: doc
        :text-align: left

        Search, buy, port in, and manage geographic, national, toll-free, and UIFN numbers.

    .. grid-item-card:: **Voice – Inbound Trunks**
        :link: voice/inbound-trunks/index
        :link-type: doc
        :text-align: left

        Configure inbound SIP and PSTN trunks to receive incoming calls to your DID numbers.

    .. grid-item-card:: **Voice – Outbound Trunks**
        :link: voice/outbound-trunks/index
        :link-type: doc
        :text-align: left

        Enable outbound calling, create SIP trunks, control routing, security, and dialing behavior.

    .. grid-item-card:: **SMS**
        :link: sms/index
        :link-type: doc
        :text-align: left

        Send and receive SMS, configure HTTP and Email SMS trunks, and manage Sender ID Verifications.

    .. grid-item-card:: **Billing & Pricing**
        :link: billing/index
        :link-type: doc
        :text-align: left

        Set up payment methods, manage payments, balances, pricing, and invoices.

    .. grid-item-card:: **Logs & Analytics**
        :link: logs-analytics/index
        :link-type: doc
        :text-align: left

        Analyze voice and SMS traffic using statistics, logs, reports, and exports.

Explore
=======

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item::

      .. card:: phone.systems™ - Cloud PBX
         :link: phone-systems/index
         :link-type: doc
         :img-top: _static/icons/ps.webp
         :class-card: sd-card-bridge

         Configure advanced call routing and automation using IVR menus, queues, time schedules, and caller-based logic.

   .. grid-item::

      .. card:: API Documentation
         :link: api3/2026-04-16/index
         :link-type: doc
         :img-top: _static/icons/didww-api-docs-w.webp
         :class-card: sd-card-bridge

         Integrate REST API to manage numbers, trunks, services, and call data.

   .. grid-item::

      .. card:: OTP Verification
         :link: otp-verification/index
         :link-type: doc
         :img-top: _static/icons/otp-verification.webp
         :class-card: sd-card-bridge

         Integrate phone number verification using SMS or voice codes.

Integrations
============

.. grid:: 1 3 3 4
   :gutter: 4
   :padding: 0

   .. grid-item-card::
      :link: ../integrations/elevenlabs/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/elevenlabs.svg" alt="ElevenLabs">
           </span>
           <span class="integration-name">ElevenLabs</span>
         </div>

   .. grid-item-card::
      :link: integrations/retell-ai/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

          <div class="integration-row">
            <span class="integration-icon">
              <img src="_static/icons/retellai.svg" alt="Retell AI">
            </span>
            <span class="integration-name">Retell AI</span>
          </div>

   .. grid-item-card::
      :link: integrations/vapi/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

          <div class="integration-row">
            <span class="integration-icon">
              <img src="../_static/icons/vapi.svg" alt="Vapi">
            </span>
            <span class="integration-name">Vapi</span>
          </div>

   .. grid-item-card::
      :link: ../integrations/ms-teams/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/microsoft-teams.png" alt="Microsoft Teams">
           </span>
           <span class="integration-name">Microsoft Teams</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/3cx/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/3CX.svg" alt="3cx">
           </span>
           <span class="integration-name">3CX</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/amazon/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/aws.svg" alt="Amazon Chime">
           </span>
           <span class="integration-name">Amazon Chime SDK</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/yeastar/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/yeastar.svg" alt="Yeastar">
           </span>
           <span class="integration-name">Yeastar P-Series PBX</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/asterisk/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/asterisk.png" alt="Asterisk">
           </span>
           <span class="integration-name">Asterisk</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/freeswitch/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/freeswitch.webp" alt="FreeSWITCH">
           </span>
           <span class="integration-name">FreeSWITCH</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/twilio/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/twilio.png" alt="Twilio">
           </span>
           <span class="integration-name">Twilio</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/avaya/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/avaya.svg" alt="Avaya">
           </span>
           <span class="integration-name">Avaya</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/ribbon/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/ribbon.svg" alt="Ribbon">
           </span>
           <span class="integration-name">Ribbon</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/telinta/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/telinta.png" alt="Telinta">
           </span>
           <span class="integration-name">Telinta</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/zapier/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/zapier.png" alt="Zapier">
           </span>
           <span class="integration-name">Zapier</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/pabbly/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/pabbly.svg" alt="Pabbly">
           </span>
           <span class="integration-name">Pabbly</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/genesys/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/genesys.svg" alt="Genesys">
           </span>
           <span class="integration-name">Genesys Cloud CX</span>
         </div>

   .. grid-item-card::
      :link: ../integrations/freepbx/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/freepbx.png" alt="FreePBX">
           </span>
           <span class="integration-name">FreePBX</span>
         </div>

   .. grid-item-card::
      :link: integrations/odoo/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

          <div class="integration-row">
            <span class="integration-icon">
              <img src="_static/icons/odoo.jpeg" alt="Odoo">
            </span>
            <span class="integration-name">Odoo</span>
          </div>

   .. grid-item-card::
      :link: ../integrations/didww-prometheus-exporter/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="_static/icons/prometheus-exporter.svg" alt="prometheus-exporter">
           </span>
           <span class="integration-name">Prometheus</span>
         </div>

.. toctree::
   :maxdepth: 2
   :caption: Services & Tools
   :hidden:

   Services & Tools <introduction>

.. toctree::
   :maxdepth: 2
   :caption: phone.systems™
   :hidden:

   phone.systems™ <phone-systems/index>

.. toctree::
   :maxdepth: 2
   :caption: Integrations
   :hidden:

   Integrations <integrations/index>

.. toctree::
   :maxdepth: 2
   :caption: MCP
   :hidden:

   MCP <mcp/index>

.. toctree::
   :maxdepth: 2
   :caption: Development
   :hidden:

   API Documentation <api3/2026-04-16/index>

.. toctree::
   :maxdepth: 2
   :caption: Call Events
   :hidden:

   Call Events <call-events/index>

.. toctree::
  :maxdepth: 2
  :hidden:
  :caption: OTP Verification

  OTP Verification <otp-verification/index>


:html_theme.sidebar_secondary.remove: true

===============================
Introduction
===============================

Build global communications with DIDWW phone numbers, voice, SMS, cloud PBX tools, API automation, analytics, and integrations.

DIDWW helps businesses, operators, service providers, and communication platforms create reliable voice and messaging services across multiple countries. Use DIDWW to manage phone numbers, route calls, send messages, automate provisioning, and connect communication workflows to your own systems.

.. grid:: 1 1 3 3
   :gutter: 4
   :padding: 3

   .. grid-item::

      **Global numbers**

      Buy, port, manage, and configure DID numbers for local, national, mobile, toll-free, shared-cost, and UIFN use cases.

   .. grid-item::

      **Voice and messaging**

      Route inbound and outbound voice traffic, configure SIP trunking, and use SMS services where supported.

   .. grid-item::

      **Automation and integrations**

      Use API, call events, and integrations to connect communications services with your systems, PBXs, CRMs, or AI platforms.

What you can achieve
====================

.. tab-set::

   .. tab-item:: Manage Phone Numbers

      Use DIDWW to buy numbers, transfer existing numbers, manage assigned numbers, configure capacity, and apply reusable configuration profiles.

      - :doc:`Phone Numbers <phone-numbers/index>` — Buy, port, manage, and configure DID numbers.
      - :doc:`Buy Numbers <phone-numbers/buy-numbers/index>` — Search available numbers and complete an order.
      - :doc:`My Numbers <phone-numbers/my-numbers/index>` — Review and manage assigned numbers.
      - :doc:`Number billing <phone-numbers/number-billing>` — Understand setup charges, recurring charges, billing cycles, and renewal behavior.
      - :doc:`Number Porting <phone-numbers/number-porting/index>` — Transfer existing numbers to DIDWW.
      - :doc:`Capacity <phone-numbers/capacity/index>` — Manage channel capacity for phone numbers.
      - :doc:`Configuration Profiles <phone-numbers/configuration-profiles/index>` — Apply reusable number configuration profiles.

   .. tab-item:: Set Up Voice

      Use DIDWW to deliver inbound calls to your infrastructure, configure outbound SIP trunking, and support number-based voice services.

      - :doc:`Voice <voice/index>` — Configure DIDWW voice services.
      - :doc:`Inbound Trunks <voice/inbound-trunks/index>` — Route inbound calls to SIP, PSTN, or trunk groups.
      - :doc:`Outbound Trunks <voice/outbound-trunks/index>` — Configure outbound SIP trunking and termination.
      - :doc:`Emergency Calling <voice/emergency-calling/index>` — Configure emergency calling for supported DID numbers.
      - :doc:`CNAM <voice/cnam/index>` — Configure CNAM services.

   .. tab-item:: Set Up Messaging

      Use DIDWW SMS services to configure messaging trunks for two-way P2P messaging, verify sender IDs for application-to-person messaging, and review SMS delivery activity.

      - :doc:`SMS <sms/index>` — Configure and manage DIDWW SMS services.
      - :doc:`SMS Trunks <sms/sms-trunks/index>` — Configure SMS trunks for sending and receiving two-way P2P messages.
      - :doc:`Sender ID Verifications <sms/sender-id-verifications/index>` — Register sender IDs for application-to-person messaging.
      - :doc:`SMS Logs <logs-analytics/sms-logs/index>` — Review SMS delivery records and message activity.

   .. tab-item:: Verify Phone Numbers

      Use DIDWW OTP Verification to confirm that a user controls a phone number by delivering a one-time code by SMS or phone call.

      - :doc:`OTP Verification <otp-verification/index>` — Overview, delivery methods, and how a verification works.
      - :doc:`Getting Started <otp-verification/getting-started>` — Create an OTP application and run your first verification.
      - :doc:`Authentication <otp-verification/authentication>` — Authenticate requests and choose an auth mode.
      - :doc:`API Reference <otp-verification/api-reference/index>` — Start, report, and status endpoints.

Operational areas
=================

.. grid:: 1 1 2 2
   :gutter: 4
   :padding: 0

   .. grid-item:: **Account and billing**

      - :doc:`Billing <billing/index>` — Manage payments, balances, invoices, and pricing.
      - :doc:`Payment Methods <billing/payment-methods/index>` — Set up and manage payment methods.
      - :doc:`Billing History <billing/billing/index>` — Review billing activity.
      - :doc:`Billing and Pricing <billing/billing-and-prices/index>` — Review pricing and invoice information.
      - :doc:`Account Settings <account-settings/account-setup>` — Manage users, security, notifications, and account access.
      - :doc:`Identities & Addresses <identities/getting-started>` — Manage end-user details for regulated services.
      - :doc:`Referral Program <referral-program/index>` — Join the program, share your referral link, review commissions, and withdraw approved earnings.

   .. grid-item:: **Monitoring and reference**

      - :doc:`Logs & Analytics <logs-analytics/index>` — Review voice and SMS traffic, reports, and usage data.
      - :doc:`Statistics <logs-analytics/statistics/index>` — Analyze service usage and traffic.
      - :doc:`Reports <logs-analytics/reports/index>` — Review generated reports.
      - :doc:`Call Logs <logs-analytics/call-logs/index>` — Inspect call records.
      - :doc:`SMS Logs <logs-analytics/sms-logs/index>` — Inspect SMS records.
      - :doc:`Network Infrastructure <presence/index>` — Review network, connectivity, and infrastructure information.
      - :doc:`Glossary <definitions>` — Review product, telecom, API, and service terminology.

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Phone Numbers

  Overview <phone-numbers/index.rst>
  Buy numbers <phone-numbers/buy-numbers/index.rst>
  My numbers <phone-numbers/my-numbers/index.rst>
  Number billing <phone-numbers/number-billing.rst>
  Number porting <phone-numbers/number-porting/index.rst>
  Capacity <phone-numbers/capacity/index.rst>
  Configuration profiles <phone-numbers/configuration-profiles/index.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Voice

  Overview <voice/index.rst>
  Inbound Trunks <voice/inbound-trunks/index.rst>
  Outbound Trunks <voice/outbound-trunks/index.rst>
  Emergency Calling <voice/emergency-calling/index.rst>
  CNAM <voice/cnam/index.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: SMS

  Overview <sms/index.rst>
  SMS Trunks <sms/sms-trunks/index.rst>
  Sender ID Verifications <sms/sender-id-verifications/index.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Logs & Analytics

  Overview <logs-analytics/index.rst>
  Statistics <logs-analytics/statistics/index.rst>
  Reports <logs-analytics/reports/index.rst>
  Call Logs <logs-analytics/call-logs/index.rst>
  SMS Logs <logs-analytics/sms-logs/index.rst>
  Exports <logs-analytics/exports/index.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Identities & Addresses

  Overview <identities/index.rst>
  Getting Started <identities/getting-started.rst>
  Identities <identities/identities.rst>
  Addresses <identities/addresses.rst>
  Verifications <identities/verifications.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Billing

  Overview <billing/index.rst>
  Getting Started <billing/getting-started.rst>
  Payment Methods <billing/payment-methods/index.rst>
  Billing History <billing/billing/index.rst>
  Billing and Pricing <billing/billing-and-prices/index.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Account Settings

   Overview <account-settings/index.rst>
   Register an Account with DIDWW <account-settings/creating-an-account.rst>
   Account Setup <account-settings/account-setup.rst>
   User Details <account-settings/user-details.rst>
   Account Details <account-settings/account-details.rst>
   Security <account-settings/two-factor-auth.rst>
   Users <account-settings/adding-new-roles.rst>
   Accounts <account-settings/multi-account.rst>
   Notifications <account-settings/notifications.rst>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Referral Program

   Overview <referral-program/index.rst>
   How the referral program works <referral-program/how-referral-program-works.rst>
   Join the referral program <referral-program/how-to-guides/join-referral-program.rst>
   Withdraw referral commissions <referral-program/how-to-guides/withdraw-referral-earnings.rst>
   Referral program reference <referral-program/referral-program-reference.rst>

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Infrastructure & Glossary

   Network Infrastructure <presence/index>
   Glossary <definitions.rst>
   Certifications and Memberships <certifications-and-memberships>


.. _user_panel_phone_numbers:

=============
Phone Numbers
=============

DID numbers are the foundation of your DIDWW setup. Use this section to buy numbers, transfer existing numbers to DIDWW, and manage numbers assigned to your account.

Start with **Buy Numbers** or **Number Porting** to add numbers to your account. After assignment, use **My Numbers** to manage trunks, services, capacity, and billing.

Set up and manage numbers
=========================

Buy, transfer, manage, and review billing for DID numbers.

.. grid:: 1 1 2 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Buy numbers**
      :link: buy-numbers/index
      :link-type: doc
      :text-align: left

      Search available DID numbers, review pricing and registration requirements, and complete checkout.

   .. grid-item-card:: **Number porting**
      :link: number-porting/index
      :link-type: doc
      :text-align: left

      Check portability, create porting requests, track porting numbers, and review port-out requests.

   .. grid-item-card:: **My numbers**
      :link: my-numbers/index
      :link-type: doc
      :text-align: left

      Manage DID numbers already assigned to your account, including trunks, services, capacity, billing cycles, and batch actions.

   .. grid-item-card:: **Number billing**
      :link: number-billing
      :link-type: doc
      :text-align: left

      Understand setup fees, monthly fees, billing periods, incoming rates, orders, payments, receipts, and invoices.

Configure capacity and configuration profiles
=============================================

Manage inbound call capacity and reusable voice, SMS, and capacity settings.

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Capacity**
      :link: capacity/index
      :link-type: doc
      :text-align: left

      Manage included, dedicated, shared, and metered inbound call capacity for DID numbers and Capacity groups.

   .. grid-item-card:: **Configuration profiles**
      :link: configuration-profiles/index
      :link-type: doc
      :text-align: left

      Reuse voice, SMS, and capacity settings across DID numbers, or apply them automatically with rules.

.. _services_coverage_pricing_access_pricelists:

===================
Download pricelists
===================

Download DIDWW pricelists from the public pricing pages or from the DIDWW User Panel. Public pricelists provide general service pricing, while User Panel pricelists show pricing for services enabled on your account.

Pricelists from the DIDWW website
===================================

Use the DIDWW website to get pricelists with general service pricing without signing in to the User Panel.

Step 1: Open a public pricing page
----------------------------------

Visit one of the pricing pages:

   - `Services, Coverage, and Pricelist <https://www.didww.com/coverage-and-prices/did-pricing>`_
   - `SIP Trunking Pricing <https://www.didww.com/coverage-and-prices/sip-trunking-pricing>`_

Step 2: Submit the pricelist request
------------------------------------

1. Fill in the form with the following information:

   - Full name
   - Company name
   - Email address

2. Optional: Select **Subscribe me to news and updates**.
3. Complete the reCAPTCHA.
4. Click **Get pricelist**.

A download link is sent to the email address entered in the form.

.. figure:: https://doc.didww.com/_images/general.png
   :figclass: align-center
   :alt: Public pricelist download form.

   **Fig. 1.** Requesting a public pricelist.

----

Pricelists from the User Panel
==============================

Use User Panel pricelists when you need all pricelists available to your account, including additional pricelists for enabled services.

Step 1: Open Buy Numbers
------------------------

1. Sign in to the `DIDWW User Panel <https://my.didww.com/#/users/sign_in>`_. If you do not have an account, `create a DIDWW account <https://my.didww.com/#/users/sign_up>`_.
2. Go to **Phone Numbers** > **Buy Numbers**.

Step 2: Download a pricelist
----------------------------

1. Click **Download Pricelist**.
2. Select the required pricelist from the dropdown.

.. note::

   - Large files may be sent to your account email address.
   - Only services enabled on your account have corresponding pricelists. For help, contact sales@didww.com.

.. figure:: https://doc.didww.com/_images/specific.png
   :figclass: align-center
   :alt: Download Pricelist dropdown in the DIDWW User Panel.

   **Fig. 2.** Downloading User Panel pricelists.


.. _user_panel_end_user_verification:

=====================
End-user verification
=====================

End-user verification is required in some countries before DID numbers can be activated. In Buy Numbers, the **Required** option in the registration filter identifies numbers that must complete End-user verification before activation.

Verification requirements depend on local telecommunications regulations and may vary by country, region, number type, and identity type. When End-user verification is required, DID numbers remain pending until the required information is reviewed and approved.

What is end-user verification?
==============================

End-user verification is the process of validating the identity and address information associated with DID number usage.

Telecommunications regulations in some countries require providers to collect and verify customer information before activating phone numbers. Depending on local requirements, verification may apply to individuals, businesses, or both.

Verification requirements may include:

- identity information
- address information
- proof-of-address documents
- business registration documents
- local presence requirements
- supporting documents, when required

How end-user verification affects number purchases
==================================================

When you select DID numbers to buy, DIDWW indicates whether registration is required for the number range. When registration is not required, end-user verification does not block activation after checkout.

If registration is required, the number cannot be activated until end-user details are submitted and approved. If you already have the required identity and address records, you can submit them during checkout using :ref:`Submit End User Details <submitting_for_verification>`. If the details are not available during checkout, the number remains pending until the required records are assigned and approved.

.. mermaid::

   flowchart LR

       A[Complete checkout] --> B{Registration required?}

       B -->|No| C[Number activation]

       B -->|Yes| D[Submit End-user Details]
       D --> E[Compliance review]
       E --> F[Number activation<br/>after approval]

       class C,E,G,I customer
       class B,F system
       class A,D idle
       class H,J operational

       classDef customer fill:#F7FBFF,stroke:#0072CE,stroke-width:2px,color:#102A43
       classDef system fill:#FFF1E8,stroke:#FF8A4C,stroke-width:2px,color:#102A43
       classDef idle fill:#F7FBFF,stroke:#0072CE,stroke-width:2px,color:#102A43
       classDef operational fill:#ECFDF5,stroke:#10B981,stroke-width:2px,color:#102A43

When registration is required
=============================

Verification requirements vary by country, number type, and local regulations.

Requirements may differ by:

- country, region, or city
- local, national, mobile, toll-free, or other number types
- personal or business identity type
- required proofs and supporting documents

Depending on local regulations, additional requirements may apply, including:

- local address requirements
- business-only eligibility
- national identity verification
- emergency service address requirements

How identities and addresses are used
=====================================

End-user verification uses identity and address records stored in :ref:`Identities & Addresses <user_panel_identities_addresses>` in the DIDWW User Panel.

An :ref:`identity <user_panel_identities>` represents the individual or business using the DID numbers. :ref:`Address records <user_panel_addresses>` store the physical address information required for regulatory verification. A :ref:`verification request <user_panel_verifications>` is created when identity and address details are assigned to a number that requires registration.

Depending on local regulations, verification may require identity, address, or business information before number activation.

Verification status and activation
==================================

Numbers that require end-user verification may remain in a pending state until the review process is completed.

If verification is rejected or additional information is required, DIDWW provides status updates in the User Panel. You can track submitted requests in :ref:`Verifications <user_panel_verifications>`. Activation timing depends on the country requirements and the completeness of the submitted information.

Related links
=============

- :doc:`how-to-buy` — Purchase DID numbers from DIDWW inventory.
- :doc:`filters-reference` — Review registration-related search filters.
- :ref:`Submit End User Details <submitting_for_verification>` — Assign identity and address records to numbers that require registration.
- :ref:`Verifications <user_panel_verifications>` — Track submitted verification requests and review their status.
- :ref:`Identities & Addresses <user_panel_identities_addresses>` — Manage identity and address records used for verification.
- :ref:`Identities <user_panel_identities>` — Create and manage personal or business identity records.
- :ref:`Addresses <user_panel_addresses>` — Create and manage physical address records used for verification.


.. _user_panel_buy_numbers_filters:

=================
Filters reference
=================

Buy Numbers filters narrow available DID inventory by location, number type, whether registration is required, supported features, billing option, area name, and prefix. Use this reference when you need to confirm what each filter means before purchasing numbers.

Country and number type filters
===============================

Each number type shows the number of available prefixes for the selected country. Number types with no available prefixes appear unavailable.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Filter
     - Description
   * - **Country**
     - Filters inventory by the country where you want to purchase phone numbers.
   * - **Local**
     - Shows geographic numbers tied to specific cities or regions.
   * - **National**
     - Shows non-geographic numbers that provide a countrywide presence and are not linked to a specific locality.
   * - **Mobile**
     - Shows numbers assigned to mobile networks.
   * - **Toll-free**
     - Shows numbers that let callers connect without charge.
   * - **Shared Cost**
     - Shows numbers where the call cost is shared between the caller and the recipient.
   * - **Global / UIFN**
     - Shows Universal International Freephone Numbers that allow callers from multiple countries to reach your business using a single number.

Geographical selection filters
==============================

.. _user_panel_buy_numbers_filters_advanced:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Filter
     - Description
   * - **State / Region**
     - Narrows the selection by state or administrative region within the selected country. This option is available only in countries with sub-national divisions, such as the United States, Canada, and the United Kingdom.
   * - **NPA/NXX**
     - Narrows the selection to a specific area code or number prefix. This filter is mainly used in countries with structured numbering plans, such as the United States and Canada.

Registration filters
====================

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Filter
     - Description
   * - **Required**
     - Shows registration-required numbers that need end-user information before activation.
   * - **Not required**
     - Shows numbers that do not require End-user verification before activation.

Supported feature filters
=========================

.. list-table::
   :header-rows: 1
   :widths: 23 70

   * - Filter
     - Description
   * - |inbound-calls| **Inbound calls**
     - Shows numbers that support SIP, PSTN, and phone.systems™ call forwarding.
   * - |local-cli| **Local CLI**
     - Shows numbers that can be used as caller ID with DIDWW local routes.
   * - |fax| **Inbound Fax**
     - Shows numbers that support T.38 or G.711u passthrough.
   * - |sms-in| **Inbound SMS**
     - Shows numbers that support SMPP, HTTP, and Email SMS delivery.
   * - |a2p| **Outbound A2P SMS**
     - Shows numbers that can be registered as Long-code Sender IDs for DIDWW A2P messaging through SMPP and HTTP.
   * - |sms-out| **Outbound P2P SMS**
     - Shows numbers that support SMPP and HTTP SMS delivery.
   * - |emergency| **Emergency calling**
     - Shows numbers that can be used to call local emergency service numbers.
   * - |cnam| **Outbound CNAM**
     - Shows numbers that support configurable caller name.

.. note::
   When multiple supported feature filters are selected, only numbers that support all selected features are shown.

Billing option filters
======================

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Filter
     - Description
   * - **Flat Rate**
     - Shows numbers with a flat-rate pricing model. Dedicated channels are selected in the **Channels Included** field during purchase and cannot be shared with other DIDs. A recurring charge applies.
   * - **Metered**
     - Shows numbers with the Pay-Per-Minute option. These numbers are assigned to a capacity group with 100 channels by default. The number of channels can be adjusted after purchase. Dedicated flat-rate channels are not included.

Text search filters
===================

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Filter
     - Description
   * - **Area name**
     - Finds numbers for a specific area or locality.
   * - **Prefix**
     - Finds DID numbers that match the entered number prefix.

Related links
=============

- :ref:`How to buy numbers <user_panel_buy_numbers_process>` — Use filters while purchasing DID numbers.
- :ref:`End-user verification <user_panel_end_user_verification>` — Understand what the registration filter means for activation.
- :ref:`Number Selection Tool <user_panel_buy_numbers_selection>` — Understand selected number search and reservation behavior.

.. |cnam| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-cnam@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |inbound-calls| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-inbound-calls@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |local-cli| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-local-termination@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |fax| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-fax@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |sms-in| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-p-2-p-sms-in@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |sms-out| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-p-2-p-sms-out@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |a2p| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-ap-2-sms@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |emergency| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-emergency@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _user_panel_purchase:
.. _user_panel_buy_numbers_process:

==================
How to buy numbers
==================

Purchase DID numbers from DIDWW inventory by searching available numbers, applying filters, reviewing pricing and service options, and completing checkout.

Before you begin
================

Sufficient prepaid balance is required to complete the purchase. See :ref:`getting started with billing <billing_quickstart>`.

.. important::
   If you haven’t added a credit card, you’ll be prompted to do so during checkout or you can choose an instant payment method to complete the purchase.

Step 1: Select a country
========================

1. Go to the **Phone Numbers > Buy Numbers** menu.
2. In the **Country** dropdown, choose the country where you want to purchase phone numbers.

.. figure:: https://doc.didww.com/_images/fig1.png
    :figclass: align-center
    :alt: Country selection on the Buy Numbers page.

    **Fig. 1.** Selecting a country.

Step 2: Select a number type
============================

Select a number type to display only numbers available in that category.

Available number types include Local, National, Mobile, Toll-free, Shared Cost, and Global / UIFN.

See :doc:`filters-reference` for detailed number type information.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Number type filter on the Buy Numbers page.

   **Fig. 2.** Selecting a number type.

Step 3: Apply filters
=====================

Use the available filters to narrow the search results by geography, whether registration is required, supported features, billing options, area name, or prefix.

For detailed filter descriptions, see :doc:`filters-reference`.

.. figure:: https://doc.didww.com/_images/buy_numbers_filters.png
   :figclass: align-center
   :alt: Buy Numbers page filters.

   **Fig. 3.** Applying additional filters.

Step 4: Add numbers to the shopping cart
========================================

1. Review the available number options and their pricing.
2. Select the number of **Channels Included**.
3. Set the **Quantity** of numbers to purchase.
4. Click the cart icon to add the selected numbers to your shopping cart.

.. figure:: https://doc.didww.com/_images/fig2.1.png
    :figclass: align-center
    :alt: Add numbers to the shopping cart.

    **Fig. 4.** Adding numbers to the shopping cart.

Step 5: Review the shopping cart
================================

Open the **Shopping Cart** to review your selected numbers. In the shopping cart, you can review the selected numbers and adjust the Channels Included or Quantity before checkout.

.. figure:: https://doc.didww.com/_images/fig4.png
    :figclass: align-center
    :alt: Review shopping cart.

    **Fig. 5.** Review shopping cart.

Step 6: Select billing period and proceed to checkout
=====================================================

In the **Shopping Cart**, select your preferred billing period and click **Proceed to Checkout**.

.. figure:: https://doc.didww.com/_images/fig4.1.png
    :figclass: align-center
    :alt: Billing period selection in the shopping cart.

    **Fig. 6.** Selecting a billing period.

Step 7: Review order summary and continue
=========================================

On the **Checkout** page, review the order details in the **Order Summary** panel and click **Continue**.

.. note::
   To make changes before finalizing your order, click the **Modify Order** button. This will return you to the shopping cart for adjustments.

.. figure:: https://doc.didww.com/_images/fig5.png
    :figclass: align-center
    :alt: Modify Order button.

    **Fig. 7.** Modify Order button.

Step 8: Acknowledge service restrictions
========================================

If any of your selected numbers have service restrictions, a **Service Restrictions** pop-up will appear. Review the terms, check the confirmation box, and click **Agree & Complete Order** to finalize your purchase.

.. figure:: https://doc.didww.com/_images/fig5.1.png
   :figclass: align-center
   :alt: Service Restrictions pop-up.

   **Fig. 8.** Service Restrictions pop-up.

Next steps
==========

- :doc:`../my-numbers/how-to-guides/assign-voice-trunk` — Configure inbound routing for purchased DID numbers.
- :doc:`../capacity/index` — Configure capacity for purchased DID numbers.
- :doc:`end-user-verification` — Complete End-user verification before activation, when required.


===========
Buy numbers
===========

Purchase DID numbers from DIDWW inventory for voice and messaging services. Use this section to search available numbers, understand registration requirements, and complete DID number purchases.

Key features
============

- Purchase phone numbers
- Explore coverage and availability
- View service restrictions
- View supported features
- View whether registration is required
- View pricing
- Select individual numbers
- Download pricelists for all DIDWW services

Get started
===========

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: **How to buy numbers**
      :link: how-to-buy
      :link-type: doc
      :text-align: left

      Find available numbers, add them to the cart, and complete checkout.

   .. grid-item-card:: **Download pricelists**
      :link: download-pricelists
      :link-type: doc
      :text-align: left

      Download price lists for DIDWW services.

   .. grid-item-card:: **Number selection tool**
      :link: number-selection-tool
      :link-type: doc
      :text-align: left

      Choose individual numbers, including gold and vanity numbers, where available.

Related resources
=================

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: **Filters reference**
      :link: filters-reference
      :link-type: doc
      :text-align: left

      Look up country, number type, feature, registration, and billing filters.

   .. grid-item-card:: **End-user verification**
      :link: end-user-verification
      :link-type: doc
      :text-align: left

      Understand when registration is required and how end-user verification affects number activation.

   .. grid-item-card:: **Identities & addresses**
      :link: ../../identities/index
      :link-type: doc
      :text-align: left

      Manage identity and address records used for End-user verification.

   .. grid-item-card:: **Billing**
      :link: ../../billing/index
      :link-type: doc
      :text-align: left

      Manage payment methods, invoices, orders, and service pricing.

   .. grid-item-card:: **Number billing**
      :link: ../number-billing
      :link-type: doc
      :text-align: left

      Understand setup charges, recurring charges, billing cycles, and capacity billing impact for DID numbers.

.. toctree::
   :maxdepth: 1
   :hidden:

   How to buy numbers <how-to-buy.rst>
   Download pricelists <download-pricelists.rst>
   Number selection tool <number-selection-tool.rst>
   End-user verification <end-user-verification.rst>
   Filters reference <filters-reference.rst>


.. _user_panel_buy_numbers_selection:

=====================
Number selection tool
=====================

Use the Number Selection Tool to search and reserve individual phone numbers before purchase. The tool supports both regular and Gold numbers for supported DID groups.

You can search by digits or letters. Letter searches use standard phone keypad mappings for vanity-style number combinations, while Gold numbers contain memorable digit patterns such as repeated or sequential numbers.

Before you begin
================

- Access to the Number Selection Tool is not enabled by default. Customers requiring this feature should contact their sales representative at `sales@didww.com <mailto:sales@didww.com>`_ or their account manager. Number Selection Tool access is subject to review and may be enabled on a case-by-case basis.
- Availability of Gold and vanity numbers varies by country and city.

Step 1: Select a country
========================

1. Go to the **Phone Numbers > Buy Numbers** menu.
2. In the **Country** dropdown, choose the country where you want to purchase phone numbers.

.. figure:: https://doc.didww.com/_images/country_select.png
   :figclass: align-center
   :alt: Select a country on the Buy Numbers page.

   **Fig. 9.** Selecting a country.

Step 2: Open the number selection tool
======================================

1. Use the available filters to find the DID group you want to purchase numbers from.
2. In the numbers table, locate the **Select numbers** column and click the **#** button to launch the Number Selection Tool.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Clicking the Numbers button to open the selection tool.

   **Fig. 10.** Opening the Number Selection Tool.

Step 3: Search for numbers
==========================

In the **Select and reserve numbers** window, you can search for **Regular** or **Gold Numbers** by selecting the appropriate tab and entering your search.

To find a specific number, use the **Number contains (123 or abc)** search field. Enter digits (e.g., "96" to find numbers that contain those digits) or letters (e.g., "yn" to locate vanity numbers based on keypad mappings).

.. grid:: 1 1 2 2

   .. grid-item::
      :class: text-center

      .. figure:: https://doc.didww.com/_images/fig2.1.png
         :width: 80%
         :figclass: align-center
         :alt: Filtering by specific digits.

         **Fig. 11.** Example of a numeric search.

   .. grid-item::
      :class: text-center

      .. figure:: https://doc.didww.com/_images/fig2.2.png
         :width: 80%
         :figclass: align-center
         :alt: Filtering by alphanumeric characters for vanity numbers.

         **Fig. 12.** Example of an alphanumeric (vanity) search.

Step 4: Reserve numbers
=======================

1. Check the boxes next to the numbers you want in the **Available** list on the left.
2. Click the right arrow **>** to move them to the **Reserved** list.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Managing reserved numbers and refreshing the reservation timer.

   **Fig. 13.** Selecting numbers and managing reservations.

Reservations expire after a set time due to live inventory. To retain your selected numbers, select them in the **Reserved** list and click **Refresh reservation**.

.. note::

   You can reserve up to 10 numbers at a time.

.. figure:: https://doc.didww.com/_images/refresh.png
   :figclass: align-center
   :alt: Refresh reservation action in the Number Selection Tool.

   **Fig. 14.** Refreshing the reservation timer.

Step 5: Review your cart and proceed to checkout
================================================

After selecting your numbers, click **Go to Cart**. The selected numbers appear in the shopping cart, where you can review them and complete checkout.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: Go to Cart button in the Number Selection Tool.

   **Fig. 15.** Proceeding to checkout.

Next steps
==========

- :doc:`how-to-buy` — Complete the DID number purchase process.
- :doc:`end-user-verification` — Learn when registration is required and how End-user verification affects activation.


================
Capacity billing
================

Capacity billing depends on whether capacity is included with the DID number service, purchased as flat-rate channels, or used as metered channels. Exact prices depend on the selected country, pool, account agreement, and current DIDWW pricing.

Capacity charges can come from the DID number service itself, from flat-rate channels purchased in a Capacity pool, or from metered usage. For current pricing references, see :doc:`../buy-numbers/download-pricelists`.

The examples on this page use sample values only. Use the prices shown in the User Panel or DIDWW pricelists for actual billing calculations.

Included channels and capacity mode
===================================

Included channels are part of the DID number service, and the selected capacity mode determines whether a DID number includes inbound voice channels in its service price.

The **2 included (DID+2)** capacity mode means the DID number price includes 2 inbound voice channels. The **0 included (DID+0)** capacity mode means no inbound voice channels are included by default, so the DID number must use other Capacity through dedicated, shared, or metered capacity configuration to receive inbound calls. The **metered** capacity mode means the DID number uses pay-per-minute Capacity instead of included flat-rate channels.

For capacity mode values, see :ref:`DID capacity modes <capacity_mode_values>`. For DID number price behavior during purchase, see :doc:`../number-billing`.

Flat-rate monthly charges
=========================

Flat-rate channels are billed at a fixed monthly rate per channel. The monthly cost is shown in the User Panel under **Channels cost** when purchasing flat-rate channels.

Flat-rate channels can be assigned as dedicated channels or shared channels after purchase.

.. admonition:: Example: flat-rate monthly charge

   If one flat-rate channel costs USD 15.00 per month and 4 channels are purchased from the same Capacity pool, the monthly flat-rate Capacity charge is:

   ``USD 15.00 x 4 = USD 60.00 per month``

To purchase flat-rate channels, see :doc:`how-to-guides/purchase-flat-rate-channels`.

Metered per-minute charges
==========================

Metered channels are billed per minute based on actual usage and the selected Capacity pool. The pay-per-minute cost appears in the User Panel under **Metered capacity cost**.

Metered channels do not have monthly fees.

.. admonition:: Example: metered usage charge

   If the metered Capacity cost is USD 0.01 per minute and inbound calls use 1,200 metered minutes during the billing period, the metered Capacity charge is:

   ``USD 0.01 x 1,200 = USD 12.00``

For metered channel behavior and default allocation details, see :doc:`pay-per-minute-channels`.

Setup fees
==========

A one-time setup fee is applied when flat-rate capacity channels are activated. The setup fee applies to each order, including later purchases of additional channels.

Pay-per-minute channels do not have setup fees.

Pro-rated billing
=================

When flat-rate channels are purchased in the middle of a billing cycle, the monthly charge is prorated for the remaining days of that cycle. The full monthly fee applies from the next billing cycle.

.. admonition:: Example: prorated flat-rate charge

   If one flat-rate channel costs USD 15.00 per month and is purchased with 10 days left in a 30-day billing cycle, the first monthly charge is prorated for the remaining 10 days:

   ``USD 15.00 / 30 x 10 = USD 5.00``

   From the next billing cycle, the full monthly charge applies.

Changing the next capacity mode takes effect in the next billing cycle unless the DID number is renewed immediately for the selected period. For details, see :ref:`Change Next Capacity Mode <change_next_capacity_mode>`.

Related resources
=================

- :doc:`How capacity works <how-capacity-works>` — Understand Capacity types and priority.
- :doc:`Number billing <../number-billing>` — Understand DID number setup charges, recurring charges, and billing cycles.
- :doc:`Download pricelists <../buy-numbers/download-pricelists>` — Download pricing references for DIDWW services.


.. _capacity_groups:

===============
Capacity groups
===============

Capacity groups let multiple DID numbers use shared flat-rate channels, metered channels, or both. Use Capacity groups when Capacity should be allocated to a set of DID numbers instead of reserved directly for one DID number.

What capacity groups are
========================

A Capacity group is created in a Capacity pool and assigned to DID numbers from **Phone Numbers > My Numbers**. DID numbers assigned to the same group can use the group's shared channels and metered channels when those resources are available according to Capacity priority.

Capacity groups are required for shared channels and metered channels. Dedicated channels are assigned directly to DID numbers and do not use Capacity groups.

Why capacity groups exist
=========================

Capacity groups make shared allocation possible. Without a group, Capacity can only be assigned directly to individual DID numbers as dedicated channels or provided through channels included with the DID number service.

Groups are useful when several DID numbers need access to extra inbound call Capacity, but not every DID number needs a separately reserved channel amount. They also make it possible to combine shared flat-rate channels with metered channels so a group can use fixed monthly Capacity first and usage-based Capacity as overflow.

.. mermaid::

   flowchart LR

      A["Incoming call"] --> B["DID number 1"]
      A --> C["DID number 2"]
      A --> D["DID number 3"]

      B --> E["Capacity group"]
      C --> E
      D --> E

      E --> F["Shared channels"]
      F -->|if shared channels are exhausted| G["Metered channels"]
      F --> H["Destination PSTN"]
      G --> H

      class A customerAction
      class B,C,D customerAction
      class E staffAction
      class F status
      class G status
      class H reviewComplete

      classDef customerAction stroke:#38bdf8,fill:#e0f2fe,stroke-width:2px,color:#1f2d3d
      classDef status stroke:#fb923c,fill:#fee2e2,stroke-width:2px,color:#1f2d3d
      classDef staffAction stroke:#facc15,fill:#fef3c7,stroke-width:2px,color:#1f2d3d
      classDef reviewComplete stroke:#2dd4bf,fill:#ccfbf1,stroke-width:2px,color:#1f2d3d

Shared channel allocation
=========================

Shared channels are flat-rate channels assigned to a Capacity group. The group can use shared channels when unassigned flat-rate channels are available in the selected pool.

When a DID number in the group reaches its included and dedicated channel limits, additional calls can use the group's shared channels if they are available.

Shared channels are consumed by inbound calls from DID numbers assigned to the group. A shared channel is not permanently reserved for one DID number inside the group; it is available to the group as a shared resource while it is not already in use.

Shared channels are limited by the number of unassigned flat-rate channels available in the selected Capacity pool. To assign or unassign shared channels, see :doc:`how-to-guides/manage-shared-channels`.

Metered channel allocation
==========================

Metered channels are pay-per-minute channels assigned to a Capacity group. They can be used alone or with shared channels in the same group.

Metered channels are used after higher-priority Capacity resources are unavailable. For priority behavior, see :ref:`Capacity priority <capacity_priority_values>`.

Metered channel allocation defines how many concurrent inbound calls can use pay-per-minute Capacity through the group. A Capacity group can have up to 1,000 metered channels. It does not reserve flat-rate channels or create a fixed monthly channel charge.

To assign or unassign metered channels, see :doc:`how-to-guides/manage-metered-channels`.

Group behavior
==============

Capacity groups belong to a selected Capacity pool. The pool determines the countries, pricing, and available channel resources that can be used by the group.

A group can contain shared channels, metered channels, or both. When both are configured, shared flat-rate channels are used before metered channels. This allows predictable traffic to use fixed monthly Capacity while metered Capacity remains available for overflow.

DID numbers must be assigned to the group before they can use the group's Capacity. Removing a DID number from a group stops that DID number from using the group's shared or metered channels.

Group limits
============

Capacity groups have channel allocation limits and DID number eligibility requirements. At least one shared or metered channel must be assigned when creating or editing a Capacity group, and only DID numbers that support additional Capacity can be assigned to a group.

Related resources
=================

- :doc:`Create a Capacity group <how-to-guides/create-capacity-group>` — Create a group for shared channels, metered channels, or both.
- :doc:`Edit a Capacity group <how-to-guides/edit-capacity-group>` — Rename a group or change assigned shared and metered channels.
- :doc:`Manage DID(s) in a Group <how-to-guides/manage-dids-in-group>` — Assign or remove DID numbers directly inside a Capacity group.
- :doc:`Delete a Capacity group <how-to-guides/delete-capacity-group>` — Delete a group that is no longer needed.
- :doc:`../my-numbers/how-to-guides/assign-dids-to-capacity-group` — Assign DID numbers to a Capacity group from My Numbers.
- :doc:`../my-numbers/how-to-guides/unassign-dids-from-capacity-group` — Remove DID numbers from a Capacity group from My Numbers.
- :doc:`Capacity reference <capacity-reference>` — Look up Capacity fields, values, and limits.


.. _capacity_reference:

==================
Capacity reference
==================

Capacity reference explains Capacity pools, channel types, DID capacity modes, values, and indicators.

.. _capacity_channel_types:

Channel types
=============

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Channel type
     - Description
   * - Channels included
     - Inbound voice channels included with the DID number service.
   * - Dedicated channels
     - Flat-rate channels assigned directly to one DID number. They are reserved for that DID number.
   * - Shared channels
     - Flat-rate channels assigned to a Capacity group and shared by DID numbers assigned to that group.
   * - Metered channels
     - Pay-per-minute channels assigned to a Capacity group and billed by usage.

.. _capacity_mode_values:

DID capacity modes
==================

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Mode
     - Description
   * - 2 included
     - DID+2 capacity mode. The DID number includes 2 inbound voice channels in the service price.
   * - 0 included
     - DID+0 capacity mode. The DID number includes no inbound voice channels by default and requires additional Capacity to receive inbound calls.
   * - metered
     - Pay-per-minute capacity mode. Numbers with this value use metered Capacity instead of included flat-rate channels.

.. _capacity_priority_values:

Capacity priority
=================

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Priority
     - Capacity type
     - Description
   * - 1
     - Channels included
     - Calls use channels included with the DID number first.
   * - 2
     - Dedicated channels
     - Calls use dedicated flat-rate channels after included channels are unavailable or exhausted.
   * - 3
     - Shared channels
     - Calls use shared flat-rate channels after included and dedicated channels are unavailable or exhausted.
   * - 4
     - Metered channels
     - Calls use pay-per-minute channels after included, dedicated, and shared channels are unavailable or exhausted.

.. _capacity_hybrid_combinations:

Hybrid capacity combinations
============================

.. tabs::

   .. tab:: 2 included

      .. list-table::
         :header-rows: 1
         :widths: 20 80

         * - Combination
           - Priority
         * - Metered only
           - Calls first use included channels. If they are in use, calls use metered channels.
         * - Shared only
           - Calls first use included channels. If they are in use, calls use shared channels.
         * - Shared and metered
           - Calls first use included channels, then shared channels, then metered channels.
         * - Dedicated only
           - Calls first use included channels. If they are in use, calls use dedicated channels.
         * - Dedicated and shared
           - Calls first use included channels, then dedicated channels, then shared channels.
         * - Dedicated and metered
           - Calls first use included channels, then dedicated channels, then metered channels.
         * - Dedicated, shared, and metered
           - Calls first use included channels, then dedicated channels, then shared channels, then metered channels.

   .. tab:: 0 included

      .. list-table::
         :header-rows: 1
         :widths: 20 80

         * - Combination
           - Priority
         * - Metered only
           - Calls use metered channels.
         * - Shared only
           - Calls use shared channels.
         * - Shared and metered
           - Calls first use shared channels, then metered channels.
         * - Dedicated only
           - Calls use dedicated channels.
         * - Dedicated and shared
           - Calls first use dedicated channels, then shared channels.
         * - Dedicated and metered
           - Calls first use dedicated channels, then metered channels.
         * - Dedicated, shared, and metered
           - Calls first use dedicated channels, then shared channels, then metered channels.

.. _capacity_pool_values:

Capacity pools
==============

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Pool
     - Description
   * - Standard
     - The default channel pool for a defined list of core countries.
   * - Extended
     - A channel pool for additional countries not available in the Standard pool.
   * - Custom
     - An account-specific pool enabled as part of a business agreement. Custom pools appear only when enabled for the account.

.. _capacity_pool_fields:

Capacity pool fields
====================

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Total Channel(s)
     - The total number of flat-rate channels purchased in the selected pool.
   * - Unassigned Channel(s)
     - Purchased flat-rate channels that are not assigned as dedicated channels or shared channels.
   * - Minimum limit
     - The minimum number of flat-rate channels that must remain in the selected pool when removing channels.
   * - Renew date
     - The next renewal date for flat-rate channels in the selected pool.
   * - Channel cost
     - The recurring cost per flat-rate channel in the selected pool.
   * - Metered capacity cost
     - The per-minute cost for metered capacity usage in the selected pool.
   * - Dedicated
     - The number of flat-rate channels assigned directly to DID numbers.
   * - Shared
     - The number of flat-rate channels assigned to Capacity groups as shared channels.
   * - Unassigned
     - The number of flat-rate channels available for assignment or removal.

.. _capacity_group_fields:

Capacity groups
===============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Group Name
     - Editable
     - The name used to identify the Capacity group in the User Panel.
   * - Assigned Channel(s)
     - Editable
     - The number of shared and metered channels assigned to the group.
   * - Assigned DID(s)
     - Editable
     - The number of DID numbers currently assigned to the group.

Related resources
=================

- :doc:`How capacity works <how-capacity-works>` — Understand Capacity behavior and priority.
- :doc:`Capacity groups <capacity-groups>` — Understand group behavior, fields, and limits.
- :doc:`Flat-rate channels <flat-rate-channels>` — Learn how dedicated and shared flat-rate channels work.
- :doc:`Pay-per-minute channels <pay-per-minute-channels>` — Learn how metered channels work.
- :doc:`My Numbers reference <../my-numbers/my-numbers-reference>` — Review DID number fields, statuses, and Capacity values shown in My Numbers.


.. _capacity_flat_rate_channels:

==================
Flat-rate channels
==================

Flat-rate channels provide inbound call Capacity for a fixed monthly charge per channel. They are purchased from a Capacity pool and can be assigned as dedicated channels for one DID number or as shared channels in a Capacity group.

Use flat-rate channels when inbound call volume is predictable enough to reserve a fixed amount of Capacity in advance.

How flat-rate channels work
===========================

Flat-rate channels increase the number of concurrent inbound calls that DID numbers can handle. After channels are purchased, they remain in the selected Capacity pool until they are assigned, removed, or renewed.

Flat-rate channels can be used in two ways:

- Dedicated channels are assigned directly to one DID number.
- Shared channels are assigned to a Capacity group and made available to DID numbers assigned to that group.

Only unassigned flat-rate channels can be removed from the account. If channels are assigned to DID numbers or Capacity groups, they must be unassigned before they can be removed.

Capacity pools
==============

Flat-rate channels are purchased from a Capacity pool. A Capacity pool defines where the channels can be used, how many channels are currently purchased, how many remain unassigned, and the recurring channel cost for that pool.

Dedicated and shared assignments draw from the same unassigned flat-rate channel amount in the selected pool. For example, assigning channels directly to DID numbers reduces the number of channels available for shared group allocation, and assigning shared channels to Capacity groups reduces the number available for dedicated assignment.

For Capacity pool values and field meanings, see :ref:`Capacity pools <capacity_pool_values>` and :ref:`Capacity pool fields <capacity_pool_fields>`. To purchase flat-rate channels from a pool, see :doc:`how-to-guides/purchase-flat-rate-channels`.

.. note::
   If the required country is not listed in an available pool, or if you are unsure which pool to select, contact sales@didww.com for assistance.

Dedicated flat-rate channels
============================

Dedicated flat-rate channels are assigned to one DID number. They are reserved for that DID number and cannot be used by other DID numbers.

Dedicated channels are used after channels included with the DID number, but before shared or metered channels. This makes them useful when one DID number needs predictable Capacity that should remain available regardless of activity on other DID numbers.

Dedicated channels reduce the unassigned flat-rate channel amount in the selected pool. When dedicated channels are unassigned, they return to the pool as unassigned flat-rate channels and can be assigned again or removed.

To manage dedicated channel assignment, see :doc:`how-to-guides/manage-dedicated-channels`.

Shared flat-rate channels
=========================

Shared flat-rate channels are assigned to a Capacity group. DID numbers assigned to the same Capacity group can use the same shared channels.

Shared channels are useful when several DID numbers need access to additional Capacity, but their call peaks do not usually happen at the same time. Instead of reserving separate dedicated channels for each DID number, the shared channel allocation can be consumed by any DID number in the group while channels are available.

Shared channels are used after included and dedicated channels, but before metered channels. For detailed Capacity group behavior, see :doc:`capacity-groups`.

To manage shared channel assignment, see :doc:`how-to-guides/manage-shared-channels`.

When to use flat-rate capacity
==============================

Use flat-rate Capacity when fixed monthly billing is preferred and the required channel amount is known in advance.

Dedicated channels fit DID numbers that need reserved Capacity. Shared channels fit groups of DID numbers where usage varies across the group and a shared pool of channels is more efficient than reserving separate Capacity for each number.

Flat-rate Capacity can also be combined with metered Capacity. In a hybrid setup, flat-rate channels handle expected traffic and metered channels provide overflow when higher-priority Capacity resources are already in use.

For priority behavior when flat-rate channels are combined with included or metered channels, see :ref:`Capacity priority <capacity_priority_values>` and :ref:`Hybrid capacity combinations <capacity_hybrid_combinations>`.

Related resources
=================

- :doc:`Purchase flat-rate channels <how-to-guides/purchase-flat-rate-channels>` — Purchase additional flat-rate channels from a channel pool.
- :doc:`Manage dedicated channels <how-to-guides/manage-dedicated-channels>` — Assign or unassign dedicated channels for DID numbers.
- :doc:`Manage shared channels <how-to-guides/manage-shared-channels>` — Assign or unassign shared channels in Capacity groups.


.. _capacity_how_capacity_works:

==================
How capacity works
==================

A DID number can use channels included with the DID number service, Capacity assigned directly to the DID number, or Capacity shared through a Capacity group. These resources allow DID numbers to handle more simultaneous inbound calls, support temporary traffic increases, and control how inbound call resources are allocated across one or more DID numbers.

Capacity is evaluated automatically when inbound calls arrive. DIDWW checks the available Capacity resources for the DID number and uses the highest-priority resource that is available.

For example, a DID number can use included channels first, then dedicated channels, then shared channels, and finally metered channels if higher-priority resources are already in use.

The following example shows how DIDWW evaluates available Capacity resources when an inbound call arrives.

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR
       classDef decision stroke:#fb923c,fill:#fef3c7,stroke-width:2px
       classDef action stroke:#22c55e,fill:#dcfce7,stroke-width:2px
       classDef outcome stroke:#ef4444,fill:#fee2e2,stroke-width:2px
       classDef input stroke:#38bdf8,fill:#e0f2fe,stroke-width:2px

       A([Incoming call]):::input
       B{"Included channels available?"}:::decision
       C["Use included channels"]:::action
       D{"Dedicated channels available?"}:::decision
       E["Use dedicated channels"]:::action
       F{"Shared channels available?"}:::decision
       G["Use shared channels"]:::action
       H{"Metered channels available?"}:::decision
       I["Use metered channels"]:::action
       J["Call rejected"]:::outcome

       A --> B
       B -->|YES| C
       B -->|NO| D
       D -->|YES| E
       D -->|NO| F
       F -->|YES| G
       F -->|NO| H
       H -->|YES| I
       H -->|NO| J

The flow starts with the Capacity that belongs most directly to the DID number and then moves through the remaining configured resources. If no Capacity resource is available, the inbound call cannot be delivered using Capacity resources.

This priority model allows different Capacity resources to work together while keeping call delivery predictable.

For Capacity type definitions and priority order, see :ref:`Channel types <capacity_channel_types>` and :ref:`Capacity priority <capacity_priority_values>`.

Capacity types
==============

Capacity can be provided through included channels, dedicated channels, shared channels, metered channels, or a combination of these resources.

Some resources belong to the DID number service, some are assigned directly to one DID number, and others are made available through a Capacity group. Capacity resources can also use different billing models depending on how they are configured.

For Capacity type definitions, see :ref:`Channel types <capacity_channel_types>`.

DID included channels
=====================

Some DID numbers include inbound voice channels as part of the DID number service. These channels are the first Capacity resource used for inbound calls.

When included channels are already in use, other configured Capacity resources can provide additional concurrent call handling.

For capacity mode values, see :ref:`DID capacity modes <capacity_mode_values>`.

Dedicated channels
==================

Dedicated channels are flat-rate channels assigned directly to one DID number. They are reserved for that DID number and are used after included channels.

For a detailed explanation of dedicated flat-rate behavior, see :doc:`flat-rate-channels`.

To assign or unassign dedicated channels, see :doc:`how-to-guides/manage-dedicated-channels`.

Shared channels
===============

Shared channels are flat-rate channels assigned to a Capacity group. DID numbers in the group can use the shared channels when higher-priority Capacity resources are unavailable.

For a detailed explanation of shared flat-rate behavior, see :doc:`flat-rate-channels` and :doc:`capacity-groups`.

To assign or unassign shared channels, see :doc:`how-to-guides/manage-shared-channels`.

Metered channels
================

Metered channels are pay-per-minute channels assigned to a Capacity group. They provide usage-based Capacity and are used after higher-priority resources are unavailable.

For a detailed explanation of metered Capacity behavior, see :doc:`pay-per-minute-channels` and :doc:`capacity-groups`.

To assign or unassign metered channels, see :doc:`how-to-guides/manage-metered-channels`.

Capacity priority
=================

When multiple Capacity resources are available, inbound calls use available resources according to a predefined priority order.

This ensures that Capacity resources are consumed consistently and that higher-priority resources are used before lower-priority resources.

For example, a DID number may have included channels, dedicated channels assigned directly to the DID number, and shared channels available through a Capacity group. Inbound calls use the available resources according to Capacity priority until no Capacity remains available.

For priority values and resource order, see :ref:`Capacity priority <capacity_priority_values>`.

Capacity groups
===============

A Capacity group allows multiple DID numbers to use shared channels, metered channels, or both. Groups are used when Capacity should be allocated to a set of DID numbers instead of directly to one DID number.

For Capacity group behavior, fields, and limits, see :doc:`capacity-groups`. To create or manage a group, see :doc:`how-to-guides/create-capacity-group` and :doc:`how-to-guides/manage-dids-in-group`.

Hybrid capacity
===============

Hybrid Capacity combines multiple Capacity resource types within the same Capacity configuration.

This allows inbound calls to move between available Capacity resources as call volume increases.

For example, a DID number may use included channels during normal traffic levels, dedicated or shared Capacity during higher traffic periods, and metered Capacity when all other available resources have been consumed.

The exact behavior depends on the Capacity resources assigned to the DID number and any associated Capacity groups.

For hybrid capacity priority by capacity mode and channel combination, see :ref:`Hybrid capacity combinations <capacity_hybrid_combinations>`.

When capacity is exceeded
=========================

Inbound calls use available channels according to Capacity priority. If no configured channel is available, the inbound call cannot be delivered using Capacity resources.

Use :doc:`view-capacity-usage` to review concurrent call usage, capacity exceeded events, and reports.

Related resources
=================

- :doc:`capacity-reference` — Review Capacity types, modes, priorities, pools, fields, and limits.
- :doc:`flat-rate-channels` — Learn how flat-rate Capacity resources work.
- :doc:`pay-per-minute-channels` — Learn how usage-based Capacity resources work.
- :doc:`capacity-groups` — Understand Capacity group behavior and allocation.
- :doc:`capacity-billing` — Understand how Capacity affects billing.


=======================
Create a capacity group
=======================

Create a Capacity group to assign shared channels, metered channels, or both to multiple DID numbers.

Before you begin
================

- Choose the channel pool that matches the DID numbers you plan to assign. For pool and group behavior, see :ref:`Capacity groups <capacity_groups>`.
- At least one active is required if you plan to assign the group to numbers, if you do not own any, see  :ref:`How to buy numbers <user_panel_buy_numbers_process>`.
- For shared channels, at least one unassigned flat-rate channel must be available in the selected pool. See :ref:`Purchase flat-rate channels <capacity_purchase_flat_rate_channels>`.
- For metered channels, your account must have a positive prepaid balance. To add funds, go to :ref:`Payment Methods <billing_payment_methods>`.

Create and configure the group
==============================

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the capacity pool, such as **Standard** or **Extended**.
3. Click **Create Capacity Group**.
4. In the pop-up window, enter a **Group name**.
5. Enter the number of **Assigned shared Channels**, **Assigned metered Channels**, or both.
6. Click **Create**.

.. figure:: https://doc.didww.com/_images/hybrid-create-capacity-group.png
   :alt: Create Capacity Group pop-up with shared and metered channels
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Configure Capacity group channels

.. important::
   At least one shared or metered channel must be assigned when creating a Capacity group.

.. note::
   Flat-rate channels can be assigned only when they are available as unassigned channels. A Capacity group can include shared channels, metered channels, or both.

Related resources
=================

- :doc:`Capacity groups <../capacity-groups>` — Understand group behavior, fields, and limits.
- :doc:`Manage DID(s) in a Group <manage-dids-in-group>` — Assign or remove DID numbers directly inside a Capacity group.
- :doc:`Edit a Capacity group <edit-capacity-group>` — Change group channel allocation.


=======================
Delete a capacity group
=======================

Delete a Capacity group when it is no longer needed and DID numbers should no longer use its shared or metered channels.

Before you begin
================

- Unassign all DID numbers from the Capacity group before deleting it. See :doc:`Unassign DID numbers from a Capacity group <../../my-numbers/how-to-guides/unassign-dids-from-capacity-group>`.
- Review capacity usage before removing the group. See :ref:`View capacity usage <capacity_view_usage>`.
- Review whether the group has assigned shared channels or metered channels. For group fields, limits, and behavior, see :ref:`Capacity groups <capacity_groups>`.
- If you need to reduce channel allocation before deletion, see :doc:`Manage shared channels <manage-shared-channels>` or :doc:`Manage metered channels <manage-metered-channels>`.

Step 1: Locate the capacity group
=================================

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Find the Capacity group you want to delete.
3. Click **Actions > delete**.

.. figure:: https://doc.didww.com/_images/locate_capacity_group.png
   :alt: Edit group option in the Actions menu
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open the Capacity group actions menu

Step 2: Delete the group
========================

In the confirmation pop-up click **Delete** to confirm the deletion.

.. figure:: https://doc.didww.com/_images/delete_capacity_group.png
   :alt: Delete Capacity Group confirmation dialog
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Delete Capacity Group confirmation dialog

Related resources
=================

- :doc:`Unassign DID numbers from a Capacity group <../../my-numbers/how-to-guides/unassign-dids-from-capacity-group>` — Remove DID numbers from the group before deletion.
- :doc:`Manage shared channels <manage-shared-channels>` — Reduce shared channel allocation before deleting a group.
- :doc:`Capacity groups <../capacity-groups>` — Review group fields, limits, and actions.


=====================
Edit a capacity group
=====================

Edit a Capacity group to rename it or change the number of shared and metered channels assigned to it.

Before you begin
================

- Review current usage before reducing assigned channels. See :ref:`View capacity usage <capacity_view_usage>`.
- For shared channels, the assigned amount cannot exceed the unassigned flat-rate channels available in the selected pool. See :ref:`Purchase flat-rate channels <capacity_purchase_flat_rate_channels>`.
- For metered channels, your account must have a positive prepaid balance. To add funds, go to :ref:`Payment Methods <billing_payment_methods>`.
- A Capacity group must have at least one shared or metered channel. For group behavior and limits, see :ref:`Capacity groups <capacity_groups>`.

Step 1: Edit the group
======================

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the capacity pool where the group is configured.
3. Find the Capacity group you want to update.
4. Click the **Actions** menu (three dots).
5. Select **Edit group**.

.. figure:: https://doc.didww.com/_images/step2.png
   :alt: Edit group option in the Actions menu
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Edit group

Step 2: Perform changes
=======================

1. In the **Edit Capacity Group** pop-up window, update **Group name**, **Assigned shared Channels**, or **Assigned metered Channels**.
2. Click **Submit**.

.. figure:: https://doc.didww.com/_images/edit-capacity-group2.png
   :alt: Edit Capacity Group pop-up
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Edit Capacity Group

Related resources
=================

- :doc:`Capacity groups <../capacity-groups>` — Understand group behavior and limits.
- :doc:`Manage shared channels <manage-shared-channels>` — Assign or unassign shared channels.
- :doc:`Manage metered channels <manage-metered-channels>` — Assign or unassign metered channels.


==============
How-to guides
==============

Use these guides to purchase, assign, unassign, remove, and manage additional inbound call Capacity for DID numbers.

Channels
========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Purchase flat-rate channels**
      :link: purchase-flat-rate-channels
      :link-type: doc
      :text-align: left

      Purchase additional flat-rate channels from a Standard, Extended, or Custom pool.

   .. grid-item-card:: **Manage dedicated channels**
      :link: manage-dedicated-channels
      :link-type: doc
      :text-align: left

      Assign or unassign dedicated channels for one or more DID numbers.

   .. grid-item-card:: **Manage shared channels**
      :link: manage-shared-channels
      :link-type: doc
      :text-align: left

      Assign or unassign shared channels in Capacity groups.

   .. grid-item-card:: **Manage metered channels**
      :link: manage-metered-channels
      :link-type: doc
      :text-align: left

      Assign or unassign pay-per-minute channels in Capacity groups.

   .. grid-item-card:: **Remove flat-rate channels**
      :link: remove-flat-rate-channels
      :link-type: doc
      :text-align: left

      Remove unassigned flat-rate channels from a channel pool.

Capacity groups
===============

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Create a capacity group**
      :link: create-capacity-group
      :link-type: doc
      :text-align: left

      Create a group for shared channels, metered channels, or both.

   .. grid-item-card:: **Edit a capacity group**
      :link: edit-capacity-group
      :link-type: doc
      :text-align: left

      Update group name, shared channels, or metered channels.

   .. grid-item-card:: **Manage DID(s) in a group**
      :link: manage-dids-in-group
      :link-type: doc
      :text-align: left

      Assign or remove DID numbers directly inside a Capacity group.

   .. grid-item-card:: **Delete a capacity group**
      :link: delete-capacity-group
      :link-type: doc
      :text-align: left

      Delete a Capacity group that is no longer needed.

.. toctree::
   :maxdepth: 1
   :hidden:

   Purchase flat-rate channels <purchase-flat-rate-channels.rst>
   Manage dedicated channels <manage-dedicated-channels.rst>
   Manage shared channels <manage-shared-channels.rst>
   Manage metered channels <manage-metered-channels.rst>
   Remove flat-rate channels <remove-flat-rate-channels.rst>
   Create a capacity group <create-capacity-group.rst>
   Edit a capacity group <edit-capacity-group.rst>
   Manage DID(s) in a group <manage-dids-in-group.rst>
   Delete a capacity group <delete-capacity-group.rst>


.. _capacity_purchase_flat_rate_channels:

===========================
Purchase flat-rate channels
===========================

Purchase flat-rate channels when you need additional inbound call capacity billed at a fixed monthly rate. Purchased channels become available for dedicated or shared assignment.

Before you begin
================

- You need at least one active :ref:`DID number <user_panel_buy_numbers_process>`.
- Your account needs a positive prepaid balance equal to or greater than the cost of the additional channels. To add funds, go to :ref:`Payment Methods <billing_payment_methods>`.
- Verify that the DID numbers are covered by the Standard, Extended, or Custom pool you plan to use.

.. note::
   Additional channels cannot be added to numbers that already include fixed capacity, such as toll-free numbers with 300 default channels.

Step 1: Open Capacity and select a channel pool
-----------------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the channel pool, such as **Standard** or **Extended**, based on the country of your DID numbers.
3. Click **Add New Channels**.

.. note::
   The monthly cost of flat-rate channels is shown in the pricing block under **Channels cost**. To view volume-based pricing details, hover over the tooltip next to **Channels cost**.

.. figure:: https://doc.didww.com/_images/step1-prod-capacity-empty.png
   :alt: Open the Capacity page and select a pool to purchase flat-rate channels
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open the Capacity page and select a pool

Step 2: Select the channel quantity
-----------------------------------

1. In the pop-up window, review the channel setup fee, monthly fee, and billing interval.
2. Enter the channel **quantity**.
3. Review the cost summary.

.. important::
   Pricing is volume-based. If you add channels in the middle of a billing cycle, the monthly fee is prorated for the remaining days of that cycle. A one-time setup fee is applied when capacity channels are activated.

.. figure:: https://doc.didww.com/_images/step2-prod-pop-up.png
   :alt: Select flat-rate channel quantity
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Select the channel quantity

Step 3: Complete the order
--------------------------

1. Click **Complete Order**.
2. The system charges your prepaid balance immediately.

.. note::
   If your prepaid balance is insufficient, the order cannot be placed and a notification appears.

When the order is successful, you are redirected to the order completed page with a confirmation screen. The ordered channels are immediately available.

.. figure:: https://doc.didww.com/_images/step3-order-complete-match-prices.png
   :alt: Flat-rate channel order completed confirmation page
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Flat-rate channel order completed confirmation page

Related resources
=================

- :doc:`Flat-rate channels <../flat-rate-channels>` — Understand flat-rate channel behavior, pools, and billing.
- :doc:`Manage dedicated channels <manage-dedicated-channels>` — Assign purchased channels to one DID number.
- :doc:`Manage shared channels <manage-shared-channels>` — Assign purchased channels to a Capacity group.


.. _capacity_assign_flat_rate_channels:

=========================
Manage dedicated channels
=========================

Assign dedicated flat-rate channels when one DID number needs reserved additional inbound call capacity. Unassign dedicated channels when the DID number no longer needs those channels.

Before you begin
================

- At least one active :ref:`DID number <user_panel_buy_numbers_process>` is required.
- At least one unassigned flat-rate channel is required to assign dedicated channels. See :ref:`Purchase flat-rate channels <capacity_purchase_flat_rate_channels>`.
- Only DID numbers that support additional Capacity can use dedicated channels.

Assign dedicated channels
=========================

Use this flow to assign dedicated flat-rate channels to one or more DID numbers.

Step 1: Select DID numbers
--------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number or DID numbers you want to assign dedicated channels to.
3. At the bottom of the page, click **Batch Actions**.
4. Select **Assign Dedicated Channels**.

.. figure:: https://doc.didww.com/_images/1dedicated_assign_select_batch.png
   :alt: Select DID numbers to assign dedicated flat-rate channels
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Select DID numbers and open Batch Actions

Step 2: Assign dedicated channels
---------------------------------

1. In the pop-up window, select the channel pool, such as **Standard** or **Extended**.
2. Enter the number of channels in **Assigned Dedicated Channels**.
3. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/2dedicated_assign_step2.png
   :alt: Assign dedicated flat-rate channels to a DID number
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Assign dedicated channels

----

Unassign dedicated channels
===========================

Use this flow to remove dedicated flat-rate channels from one or more DID numbers.

Step 1: Select DID numbers
--------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number or DID numbers you want to unassign dedicated channels from.
3. At the bottom of the page, click **Batch Actions**.
4. Select **Assign Dedicated Channels**.

.. figure:: https://doc.didww.com/_images/1dedicated_assign_select_batch.png
   :alt: Select DID numbers to assign dedicated flat-rate channels
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Select DID numbers and open Batch Actions

Step 2: Set dedicated channels to 0
-----------------------------------

1. In the pop-up window, select the channel pool, such as **Standard** or **Extended**.
2. Enter 0 in **Assigned Dedicated Channels**.
3. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/3-capacity-unassign-dedicated-channels.png
   :alt: Unassign dedicated channels by setting Assigned Dedicated Channels to 0
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Unassign dedicated channels

Related resources
=================

- :doc:`Flat-rate channels <../flat-rate-channels>` — Understand dedicated and shared flat-rate channels.
- :doc:`How capacity works <../how-capacity-works>` — Understand channel priority.
- :doc:`Remove flat-rate channels <remove-flat-rate-channels>` — Remove channels after they are unassigned.


.. _flat-rate-unassign-shared-channels:

======================
Manage shared channels
======================

Assign shared flat-rate channels to a Capacity group when multiple DID numbers should share additional inbound call capacity. Unassign shared channels when the group no longer needs them.

Before you begin
================

- At least one active :ref:`DID number <user_panel_buy_numbers_process>` is required.
- At least one unassigned flat-rate channel is required to assign shared channels. See :ref:`Purchase flat-rate channels <capacity_purchase_flat_rate_channels>`.
- Only DID numbers that support additional Capacity can be assigned to a Capacity group.

Assign shared channels
======================

Use this flow to create a Capacity group with shared flat-rate channels and assign DID numbers to that group.

Step 1: Open Capacity and create a group
----------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the capacity pool, such as **Standard** or **Extended**, where you have at least one unassigned channel.
3. Click **Create Capacity Group**.

.. figure:: https://doc.didww.com/_images/1assign_shared_channels2.png
   :alt: Create a Capacity group for shared channels
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Create a Capacity group

Step 2: Assign shared channels to the group
-------------------------------------------

1. In the pop-up window, enter a **Group name**.
2. Enter the number of channels in **Assigned shared Channels**.
3. Click **Create**.

.. figure:: https://doc.didww.com/_images/2capacity_group_popup.png
   :alt: Assign shared channels to a Capacity group
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Assign shared channels

Step 3: Select DID numbers
--------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID numbers you want to assign to the Capacity group.
3. At the bottom of the page, click **Batch Actions**.
4. Select **Update Capacity Group**.

.. figure:: https://doc.didww.com/_images/3shared_select.png
   :alt: Select DID numbers to assign to a Capacity group
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Select DID numbers and open Batch Actions

Step 4: Assign the capacity group
---------------------------------

1. In the **Update Capacity Group** window, select a **Capacity Group**.
2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/4shared_update_capacity_group.png
   :alt: Update Capacity Group window for shared channels
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Update Capacity Group

----

Unassign shared channels
========================

Use this flow to reduce the number of shared flat-rate channels assigned to an existing Capacity group.

Step 1: Review shared channel allocation
----------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the capacity pool where the shared channels are allocated.
3. In the **Channel allocation** block, review the number of channels assigned as shared.

.. figure:: https://doc.didww.com/_images/channel-allocation.png
   :alt: Channel allocation block showing shared channels
   :figclass: align-center
   :width: 100%

   **Fig. 5.** Review channel allocation

Step 2: Open the group editor
-----------------------------

1. Find the Capacity group where the **Assigned Channels** column shows shared channels.
2. Edit the capacity group by clicking **Actions > Edit group**.

.. figure:: https://doc.didww.com/_images/step2.png
   :alt: Edit group option in the Actions menu
   :figclass: align-center
   :width: 100%

   **Fig. 6.** Open Edit group

.. important::
   Before reducing shared channels, make sure the reduction will not cause call failures or traffic loss. A Capacity group must have at least one shared or metered channel.

   To cancel all shared channels while keeping the group active, first increase the number of metered channels to at least 1, then reduce assigned shared channels to 0. To remove all channels from a group, first unassign all DID numbers from the group, then delete the group.

Step 3: Reduce shared channels
------------------------------

1. In the **Edit Capacity Group** pop-up window, locate **Assigned shared Channels**.
2. Reduce the number of shared channels to the required value, or 0 to completely remove them from a capacity group.
3. Click **Submit**.

.. figure:: https://doc.didww.com/_images/edit-capacity-group2.png
   :alt: Reduce assigned shared channels in Edit Capacity Group
   :figclass: align-center
   :width: 100%

   **Fig. 7.** Unassign shared channels

Related resources
=================

- :doc:`Capacity groups <../capacity-groups>` — Understand group behavior, fields, and limits.
- :doc:`Manage DID(s) in a Group <manage-dids-in-group>` — Assign DID numbers to an existing group from the Capacity page.
- :doc:`Remove flat-rate channels <remove-flat-rate-channels>` — Remove unassigned flat-rate channels.


=======================
Manage metered channels
=======================

Assign metered channels when a Capacity group needs pay-per-minute inbound call capacity. Unassign a DID number from the Capacity group when it should no longer use metered channels.

Before you begin
================

- At least one active :ref:`DID number <user_panel_buy_numbers_process>` is required.
- A positive prepaid balance is required to use metered channels. To add funds, go to :ref:`Payment Methods <billing_payment_methods>`.
- Only DID numbers that support additional Capacity can be assigned to a Capacity group.

Assign metered channels
=======================

Use this flow to create a Capacity group with metered channels and assign DID numbers to that group.

Step 1: Open Capacity and select a channel pool
-----------------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the channel pool, such as **Standard** or **Extended**, based on the country of your DID numbers.

.. note::
   The pay-per-minute cost is shown in the pricing block under **Metered capacity cost**.

.. figure:: https://doc.didww.com/_images/step1pay-per-minute-assign.png
   :alt: Capacity page before assigning metered channels
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Capacity and select a pool

Step 2: Create a capacity group
-------------------------------

Click **Create Capacity Group**.

.. figure:: https://doc.didww.com/_images/create_metered_group.png
   :alt: Create Capacity Group for metered channels
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Create a Capacity group

Step 3: Assign metered channels to the group
--------------------------------------------

1. In the pop-up window, enter a **Group name**.
2. Under **Assigned metered Channels**, enter the number of channels, up to 1,000.
3. Click **Create**.

.. figure:: https://doc.didww.com/_images/step2assign-metered-channels.png
   :alt: Assign metered channels to a Capacity group
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Assign metered channels

Step 4: Select DID numbers
--------------------------

After creating a Capacity Group and assigning metered (pay-per-minute) channels to it, you need to **Update Capacity Group** and assign your DID numbers to that group.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID numbers you want to assign to the Capacity group.
3. At the bottom of the page, click **Batch Actions**.
4. Select **Update Capacity Group**.

.. figure:: https://doc.didww.com/_images/3shared_select.png
   :alt: Select DID numbers and open Batch Actions
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Select DID numbers and open Batch Actions

.. important::
   - Shared flat-rate channels always take priority over metered channels. Metered capacity is used only when no shared channels are assigned to the group, or when all included, dedicated, and shared channels are already in use.
   - DID numbers purchased with the Pay-per-minute Capacity option are automatically added to a Capacity group in the Standard pool, with 100 metered channels assigned by default.

Step 5: Update the capacity group
---------------------------------

1. In the **Update Capacity Group** window, select a **Capacity Group**.
2. Choose the **Group Name**.
3. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/step4update_capacity.png
   :alt: Update Capacity Group window showing metered channels
   :figclass: align-center
   :width: 100%

   **Fig. 5.** Update Capacity Group

----

Unassign metered channels
=========================

If you no longer want a DID number to use additional pay-per-minute capacity, unassign it from its Capacity group.

Step 1: Filter DID numbers by capacity group
--------------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the **Active** or **All Numbers** tab.
3. To quickly locate numbers with dedicated channels, open **Filters** and enable the **Capacity group** filter.
4. When the filter is added, choose the capacity pool (**Standard** or **Extended**) and select the name of the Capacity Group (e.g., Pay per minute).

.. figure:: https://doc.didww.com/_images/step1filter-numbers.png
   :alt: Filter DID numbers by Capacity group
   :figclass: align-center
   :width: 100%

   **Fig. 6.** Filter DID numbers by Capacity group

Step 2: Review metered channel allocation
-----------------------------------------

To confirm you are unassigning the correct numbers, check the **Capacity** column for details about the assigned metered capacity.

1. Locate the DID number in the table.
2. Hover over the **Capacity** column to review capacity details.

.. figure:: https://doc.didww.com/_images/step2-capacity-metered.png
   :alt: Capacity allocation showing metered channels
   :figclass: align-center
   :width: 100%

   **Fig. 7.** Review metered channel allocation

Step 3: Open the Update Capacity Group action
---------------------------------------------

1. Select the DID numbers.
2. At the bottom of the page, click **Batch Actions**.
3. Select **Update Capacity Group**.

.. figure:: https://doc.didww.com/_images/step3select_numbers.png
   :alt: Select DID numbers and open Update Capacity Group
   :figclass: align-center
   :width: 100%

   **Fig. 8.** Open Update Capacity Group

Step 4: Unassign the capacity group
-----------------------------------

1. In the **Update Capacity Group** window, open the **Capacity group** dropdown.
2. Select **Unassign Capacity Group**.
3. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/unassign_capacity_group.png
   :alt: Unassign a DID number from its Capacity group
   :figclass: align-center
   :width: 100%

   **Fig. 9.** Unassign Capacity Group

Related resources
=================

- :doc:`Pay-per-minute channels <../pay-per-minute-channels>` — Understand metered capacity behavior and billing.
- :doc:`Capacity groups <../capacity-groups>` — Understand group fields and limits.
- :doc:`Capacity billing <../capacity-billing>` — Understand metered per-minute charges.


=========================
Remove flat-rate channels
=========================

Remove flat-rate channels when purchased channels are no longer needed. Only unassigned flat-rate channels can be removed.

Before you begin
================

Unassign the flat-rate channels in the capacity pool where you plan to remove them. For details, see :ref:`Manage shared channels <flat-rate-unassign-shared-channels>` or :ref:`Manage dedicated channels <capacity_assign_flat_rate_channels>`.

.. important::
   The **Remove Channels** button is visible only when at least one unassigned channel is available in the selected pool.

Step 1: Open Capacity
=====================

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the pool, such as **Standard** or **Extended**, where you purchased the channels.
3. In the **Channel allocation** block, verify that unassigned channels are available to remove.

.. figure:: https://doc.didww.com/_images/remove-channels-button.png
   :alt: Remove Channels button on the Capacity page
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Remove Channels button

Step 2: Remove channels
=======================

1. Click **Remove Channels**.
2. In the pop-up window, enter the number of unassigned channels to remove.
3. Click **Remove**.

.. figure:: https://doc.didww.com/_images/remove-channels-amount.png
   :alt: Confirm removal of unassigned flat-rate channels
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Remove unassigned channels

Related resources
=================

- :doc:`Flat-rate channels <../flat-rate-channels>` — Understand flat-rate channel behavior and billing.
- :doc:`Manage dedicated channels <manage-dedicated-channels>` — Unassign dedicated channels before removing them.
- :doc:`Manage shared channels <manage-shared-channels>` — Unassign shared channels before removing them.


.. _capacity_manage_dids_in_group:

=========================
Manage DID(s) in a group
=========================

Use the **Manage DID(s) in Group** page to assign DID numbers to a Capacity group or remove them from the group without leaving the Capacity workspace.

Before you begin
================

A Capacity group is required before you manage DID numbers in it. See :doc:`Create a Capacity group <create-capacity-group>`.

Assign DID numbers to the group
===============================

Use this flow to move DID numbers from the supported list into the selected Capacity group.

Step 1: Open the manage DID page
--------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the capacity pool where the group is configured.
3. Find the Capacity group you want to manage and click **Actions > Manage assigned DID(s)**.

.. figure:: https://doc.didww.com/_images/manage_assigned_dids_action.png
   :alt: Manage assigned DID(s) action in the Capacity group menu
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Manage assigned DID(s)

Step 2: Assign to group
-----------------------

1. In the top table, review the DID numbers supported by the selected capacity pool.
2. Use the filters to narrow the list if needed.
3. Select the DID numbers you want to add to the group.
4. Click **Assign to Group**.

.. figure:: https://doc.didww.com/_images/assign_to_group.png
   :alt: Assign to Group button in the Manage DID(s) in Group page
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Assign to Group

----

Remove DID numbers from the group
=================================

Use this flow to remove DID numbers from the selected Capacity group.

Step 1: Open the manage DID page
--------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. Select the capacity pool where the group is configured.
3. Find the Capacity group you want to manage and click **Actions > Manage assigned DID(s)**.

.. figure:: https://doc.didww.com/_images/manage_assigned_dids_action.png
   :alt: Manage assigned DID(s) action in the Capacity group menu
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Open Manage assigned DID(s)

Step 2: Remove from group
-------------------------

1. In the bottom table, review the DID numbers supported by the selected capacity pool.
2. Use the filters to narrow the list if needed.
3. Select the DID numbers you want to remove from the group.
4. Click **Remove from Group**.
5. In the pop-up confirmation window click **Remove**.

.. figure:: https://doc.didww.com/_images/remove_from_group.png
   :alt: Remove from Group button and confirmation flow
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Remove from Group

Related resources
=================

- :doc:`Assign DID numbers to a Capacity group <../../my-numbers/how-to-guides/assign-dids-to-capacity-group>` — Assign DID numbers from the My Numbers page.
- :doc:`Unassign DID numbers from a Capacity group <../../my-numbers/how-to-guides/unassign-dids-from-capacity-group>` — Remove DID numbers from a group from My Numbers.
- :doc:`Capacity groups <../capacity-groups>` — Review Capacity group behavior, fields, and limits.
- :doc:`How capacity works <../how-capacity-works>` — Review capacity modes and channel priority.


.. _flexible_capacity:

========
Capacity
========

Capacity determines how many inbound calls a DID number can receive at the same time. Without sufficient Capacity, calls that exceed the limit are rejected — meaning real callers hear a busy signal or get disconnected before reaching your system.

DIDWW gives you three channel types to match your traffic patterns and control costs:

- **Flat-rate** — Fixed monthly channels for predictable call volumes, assigned to a single DID or shared across multiple DIDs through a Capacity group.
- **Pay-per-minute** — Metered channels for variable or unpredictable traffic, billed per minute with no setup or monthly fees.
- **Hybrid** — Flat-rate channels for baseline traffic with metered channels as automatic overflow, so you pay a fixed rate for expected volume and only pay extra when traffic spikes.

.. note::

   Capacity applies to inbound calls only.

Key features
============

- See which capacity options are available for a DID number.
- Buy, assign, and remove flat-rate channels.
- Assign extra channels directly to a DID number.
- Share channels between multiple DID numbers through a Capacity group.
- Add or remove DID numbers from a Capacity group.
- Review call usage, failed calls, and capacity exceeded events.
- Learn how Capacity is billed and how the different channel types work together.

Get started
===========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **How capacity works**
      :link: how-capacity-works
      :link-type: doc
      :text-align: left

      Understand Capacity types, priority, Capacity groups, and hybrid capacity call flow.

   .. grid-item-card:: **Flat-rate channels**
      :link: flat-rate-channels
      :link-type: doc
      :text-align: left

      Learn how dedicated and shared flat-rate channels provide fixed monthly capacity.

   .. grid-item-card:: **Pay-per-minute channels**
      :link: pay-per-minute-channels
      :link-type: doc
      :text-align: left

      Learn how metered channels provide usage-based capacity through Capacity groups.

   .. grid-item-card:: **How-to guides**
      :link: how-to-guides/index
      :link-type: doc
      :text-align: left

      Purchase, assign, unassign, remove, and manage Capacity channels and Capacity groups.

   .. grid-item-card:: **Capacity groups**
      :link: capacity-groups
      :link-type: doc
      :text-align: left

      Understand shared and metered channel allocation, group behavior, fields, and limits.

   .. grid-item-card:: **View capacity usage**
      :link: view-capacity-usage
      :link-type: doc
      :text-align: left

      Review concurrent call usage, exceeded-capacity events, statistics, and reports.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Capacity reference**
      :link: capacity-reference
      :link-type: doc
      :text-align: left

      Look up Capacity fields, values, channel types, pool types, and modes.

   .. grid-item-card:: **Capacity billing**
      :link: capacity-billing
      :link-type: doc
      :text-align: left

      Understand included channels, flat-rate charges, setup fees, prorated billing, and metered charges.

   .. grid-item-card:: **My numbers**
      :link: ../my-numbers/index
      :link-type: doc
      :text-align: left

      Manage DID-level capacity settings, group assignment, trunks, and related services.

   .. grid-item-card:: **Number billing**
      :link: ../number-billing
      :link-type: doc
      :text-align: left

      Review DID number setup charges, recurring charges, billing cycles, and renewal behavior.

   .. grid-item-card:: **Logs & analytics**
      :link: ../../logs-analytics/index
      :link-type: doc
      :text-align: left

      Review statistics, reports, and call logs related to Capacity usage and failures.

   .. grid-item-card:: **Inbound trunks**
      :link: ../../voice/inbound-trunks/index
      :link-type: doc
      :text-align: left

      Configure inbound call routing before reviewing Capacity behavior.

.. toctree::
   :maxdepth: 1
   :hidden:

   How capacity works <how-capacity-works.rst>
   Flat-rate channels <flat-rate-channels.rst>
   Pay-per-minute channels <pay-per-minute-channels.rst>
   Capacity groups <capacity-groups.rst>
   How-to guides <how-to-guides/index.rst>
   Capacity billing <capacity-billing.rst>
   Capacity reference <capacity-reference.rst>
   View capacity usage <view-capacity-usage.rst>


.. _capacity_add_metered_channels:

=======================
Pay-per-minute channels
=======================

Pay-per-minute channels, also called metered channels, provide usage-based inbound call Capacity. Metered channels are assigned through Capacity groups and are billed only when inbound calls use metered Capacity.

Use pay-per-minute channels when traffic is variable, when fixed monthly Capacity is not required, or when metered Capacity should provide overflow after higher-priority resources are already in use. You can assign up to 1,000 metered channels per group.

How pay-per-minute channels work
================================

Pay-per-minute or metered channels define the maximum number of simultaneous inbound calls that can use pay-per-minute Capacity in a Capacity group. They do not reserve flat-rate channels from a pool and do not have setup or monthly fees.

When a DID number is assigned to a Capacity group with metered channels, inbound calls can use those channels after included channels, dedicated channels, and shared channels are already in use or unavailable.

Because metered channels are evaluated after higher-priority Capacity resources, they are commonly used as overflow Capacity. They can also be used without shared channels when a DID number should rely on usage-based Capacity instead of a fixed monthly channel allocation.

For priority behavior, see :ref:`Capacity priority <capacity_priority_values>` and :ref:`Hybrid capacity combinations <capacity_hybrid_combinations>`.

Capacity pools
==============

Metered channel pricing and availability depend on the selected Capacity pool. The pool determines the coverage and per-minute metered Capacity cost used when calls are delivered through metered channels.

For Capacity pool values and field meanings, see :ref:`Capacity pools <capacity_pool_values>` and :ref:`Capacity pool fields <capacity_pool_fields>`.

.. note::
    If the required country is not listed in an available pool, or if you are unsure which pool to select, contact sales@didww.com for assistance.

Capacity groups
===============

Metered channels are assigned to Capacity groups. DID numbers use metered channels by being assigned to the group that contains those channels.

A Capacity group can include metered channels only, or it can combine shared flat-rate channels with metered channels for a hybrid Capacity setup. In a hybrid group, shared channels are used before metered channels, and metered channels provide overflow after the higher-priority Capacity resources are unavailable.

For group behavior, fields, and limits, see :doc:`capacity-groups`. To assign or unassign metered channels, see :doc:`how-to-guides/manage-metered-channels`.

Default metered channels behavior after DID purchase
====================================================

DID numbers purchased with the Pay-per-minute Capacity option are automatically added to a Capacity group with metered channels assigned by default. This allows inbound calls to use metered Capacity without requiring a separate flat-rate channel purchase.

The default group and channel amount can be changed later by editing the Capacity group or by moving DID numbers to a different Capacity group.

The default metered channel amount after DID purchase is 100 channels. For capacity mode values and pool values, see :ref:`DID capacity modes <capacity_mode_values>` and :ref:`Capacity pools <capacity_pool_values>`.

When to use pay-per-minute capacity
===================================

Use pay-per-minute Capacity when inbound call volume is variable, when fixed monthly Capacity is not needed, or when metered channels should act as backup Capacity for unexpected spikes.

Metered channels are also useful as overflow Capacity in a hybrid setup because they are used after higher-priority channel types are unavailable.

Pay-per-minute Capacity can be useful for newly purchased DID numbers that need immediate inbound call handling, DID numbers with occasional call spikes, or groups of DID numbers where fixed flat-rate allocation would be inefficient.

Related resources
=================

- :doc:`Manage metered channels <how-to-guides/manage-metered-channels>` — Assign or unassign metered channels in Capacity groups.
- :doc:`How capacity works <how-capacity-works>` — Understand Capacity priority and hybrid capacity call flow.
- :doc:`View capacity usage <view-capacity-usage>` — Review usage and troubleshoot capacity issues.


.. _capacity_view_usage:

===================
View capacity usage
===================

Use Capacity usage statistics to review concurrent inbound call demand for Capacity groups and compare configured channels with actual usage. Usage review helps determine whether the current shared and metered channel allocation is sufficient, whether channels should be moved or reduced, and whether recent call failures may be related to Capacity.

For Capacity priority and field meanings, see :ref:`Capacity priority <capacity_priority_values>` and :doc:`capacity-reference`.

View concurrent call usage
==========================

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. In the **Capacity Groups** table, find the group you want to review and click the chart icon in **Assigned Channel(s)** to open the usage view.

.. figure:: https://doc.didww.com/_images/open-capacity-group-usage.png
   :alt: Capacity page showing the chart icon in the Capacity Groups table
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Capacity group usage from the **Capacity Groups** table.

3. Use the **Timeframe** filters to focus on the period you want to review.
4. Use concurrent call usage to understand how often a Capacity group approaches its configured allocation and which channel types are being consumed. In the **Concurrent calls** chart, **Shared** and **Metered** are shown separately so you can see whether the group is relying on flat-rate shared Capacity, pay-per-minute overflow Capacity, or both.

- If shared channel usage regularly approaches the assigned shared channel amount, the group may need more shared channels or a different allocation strategy.
- If metered channels are used frequently, compare the current metered usage with the existing flat-rate allocation to decide whether additional shared channels would be more cost-effective.
- If usage remains far below the configured allocation for long periods, the group may have more channels assigned than it needs.
- If usage spikes are short and infrequent, metered overflow may already be sufficient without increasing shared channels.

.. figure:: https://doc.didww.com/_images/capacity-groups-statistics-overview.png
   :alt: Capacity groups tab in Statistics showing total failed calls, concurrent calls, and capacity exceeded
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Review Capacity group usage in **Statistics > Capacity groups**.

----

Review capacity exceeded events
===============================

1. In the DIDWW User Panel, go to **Phone Numbers > Capacity**.
2. In the **Capacity Groups** table, find the group you want to review and click the chart icon in **Assigned Channel(s)** to open the usage view.

.. figure:: https://doc.didww.com/_images/open-capacity-group-usage.png
   :alt: Capacity page showing the chart icon in the Capacity Groups table
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Capacity group usage from the **Capacity Groups** table.

3. Use the **Timeframe** filters to focus on the period you want to review.
4. Review **Total failed calls** and **Capacity exceeded** together with concurrent call usage:

- **Total failed calls** shows how many inbound calls failed during the selected timeframe.
- **Capacity exceeded** shows how often the configured Capacity was not sufficient for incoming traffic during that timeframe.

If **Capacity exceeded** increases during the same period where concurrent calls reach the group's configured shared or metered allocation, the group may need more Capacity or a different channel mix. If failed calls increase without matching Capacity pressure, review inbound routing, DID number assignment, and other call-delivery settings before changing channel allocation.

.. figure:: https://doc.didww.com/_images/capacity-groups-statistics-filters.png
   :alt: Capacity groups statistics view showing timeframe and capacity group filters
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Use filters to focus on the relevant Capacity group and timeframe.

----

Use statistics and reports
==========================

Use the Capacity page and DIDWW analytics views together to compare configured Capacity with actual inbound traffic:

- Use the chart icon on the **Capacity** page to open the usage view for a specific Capacity group quickly.
- Use :doc:`../../logs-analytics/statistics/index` to review group-level usage trends, failed calls, and Capacity exceeded events over time.
- Use :doc:`../../logs-analytics/reports/index` to group inbound voice traffic by DID number, trunk, trunk group, or DID country and compare usage with related charges.

Usage data is especially useful before changing assigned dedicated channels, shared channels, or metered channels. For related tasks, see :doc:`how-to-guides/manage-dedicated-channels`, :doc:`how-to-guides/manage-shared-channels`, and :doc:`how-to-guides/manage-metered-channels`.

----

Troubleshoot capacity issues
============================

Use the following checks when inbound calls fail, when capacity usage is higher than expected, or when charges do not match the expected Capacity mix:

.. dropdown:: Charges do not match expected capacity mix

   **Common causes**

   - Metered channels are being used more often than expected.
   - Shared channels are insufficient, causing overflow to metered.
   - The Capacity group contains DIDs with different capacity modes.

   **How to fix**

   - Use :doc:`../../logs-analytics/reports/index` to group inbound traffic by DID number or trunk and compare usage with charges.
   - Use :doc:`../../logs-analytics/statistics/index` to check how often metered channels are consumed versus shared channels.
   - If metered usage is consistently high, consider adding shared channels with :doc:`how-to-guides/manage-shared-channels`.
   - For shared and metered behavior, see :doc:`capacity-groups` and :doc:`capacity-reference`.

.. dropdown:: DID is in a Capacity group but not using it

   **Common causes**

   - The DID number has its own capacity limit that overrides the group.
   - The DID number capacity mode does not include enough channels for the expected traffic.
   - The DID number is assigned to the wrong Capacity group.

   **How to fix**

   - Review the DID capacity limit with :doc:`../my-numbers/how-to-guides/set-capacity-limits`.
   - Review group membership with :doc:`how-to-guides/manage-dids-in-group`.
   - For capacity mode and priority behavior, see :ref:`DID capacity modes <capacity_mode_values>` and :ref:`Capacity priority <capacity_priority_values>`.

.. dropdown:: Short traffic spikes causing intermittent failures

   **Common causes**

   - The Capacity group does not have metered channels enabled.
   - Metered channels are assigned below the level needed to absorb short spikes.
   - The spikes are too short for shared channels to be the practical fix.

   **How to fix**

   - Enable or increase metered channels with :doc:`how-to-guides/manage-metered-channels`.
   - Review how metered channels work in :doc:`pay-per-minute-channels` and :doc:`capacity-reference`.
   - Review usage trends in :doc:`../../logs-analytics/statistics/index` if you want to confirm that the spikes are short and intermittent.

.. dropdown:: Capacity allocation appears higher than needed

   **Common causes**

   - Traffic volume has decreased since channels were last configured.
   - Channels were added during a peak period and not reviewed afterward.
   - Multiple Capacity groups share traffic that was previously handled by one group.

   **How to fix**

   - Use the chart icon on the **Capacity** page to review concurrent call usage over a representative timeframe.
   - If usage remains consistently low, reduce shared channels with :doc:`how-to-guides/manage-shared-channels`.
   - If metered channels are rarely used, consider removing them with :doc:`how-to-guides/manage-metered-channels`.
   - For Capacity group fields and limits, see :doc:`capacity-groups` and :doc:`capacity-reference`.

.. dropdown:: Capacity statistics not showing data

   **Common causes**

   - The Capacity group was recently created and has not yet received traffic.
   - The selected timeframe does not contain any call activity.
   - The Capacity group has no DIDs assigned to it.

   **How to fix**

   - Adjust the **Timeframe** filter to a period with known traffic.
   - Confirm the group has DIDs assigned with :doc:`how-to-guides/manage-dids-in-group`.
   - If the group is new, wait for inbound calls to occur and then return to the usage view.
   - For the usage metrics shown here, see :doc:`../../logs-analytics/statistics/index` and :doc:`capacity-reference`.

Related resources
=================

- :doc:`How capacity works <how-capacity-works>` — Understand Capacity priority, hybrid behavior, and what happens when Capacity is exceeded.
- :doc:`Capacity groups <capacity-groups>` — Understand shared and metered group behavior.
- :doc:`Capacity reference <capacity-reference>` — Look up Capacity fields, values, and indicators.
- :doc:`../../logs-analytics/statistics/index` — Review Capacity group metrics and other call concurrency statistics.
- :doc:`../../logs-analytics/reports/index` — Analyze inbound voice traffic and related charges.


.. _configuration_profiles_how_profiles_and_rules_work:

=========================================
How configuration profiles and rules work
=========================================

Configuration profiles and rules work together to automate DID number setup after purchase. A profile stores the settings to apply to a number — such as voice routing, SMS routing, and Capacity — while a rule determines when and whether that profile is applied automatically.

Understanding how these two components relate to each other is the foundation for building a consistent, repeatable provisioning workflow.

For the field-level details, see :doc:`profiles-reference` and :doc:`rules-reference`.
For the procedures that use these settings, see :doc:`how-to-guides/index`.

Configuration profiles overview
===============================

A configuration profile is a reusable set of DID number settings. A profile can include voice routing, SMS routing, Capacity settings, and a description.

Profiles are useful when multiple DID numbers need the same setup. Instead of configuring each DID number separately, you can apply one profile to selected numbers or use rules to apply a profile automatically after purchase.

For profile fields, actions, and constraints, see :doc:`profiles-reference`.
For creating, applying, editing, or deleting profiles, see :doc:`how-to-guides/index`.

Rules overview
==============

Rules apply configuration profiles to newly purchased DID numbers based on conditions such as country, number type, region, or city.

.. important:: Rules apply only to newly purchased DID numbers. They do not update DID numbers that already exist in your account.

For rule fields, filters, actions, and priority values, see :doc:`rules-reference`.
For creating or managing rules, see :doc:`how-to-guides/index`.

Rule matching order
========================

Rules are evaluated when a new DID number is added to your account. DIDWW checks the rule conditions and applies the configuration profile that best matches the number.

Rule conditions can be broad or specific. A broad rule can apply to all selected countries. A more specific rule can be narrowed by number type, region, or city.

.. mermaid::

   flowchart LR
       %% Start of the process
       start((Purchase New DID<br>Start Rule Matching)):::customer --> city(("DID Matches a<br>City?")):::staff

       %% Unified Apply / Do Not Apply outputs
       city --> yes
       region --> yes
       number --> yes
       country --> yes
       yes --> apply((Apply Profile)):::completed
       no --> dontapply((Do not Apply<br>Profile)):::canceled

       %% Sequential rule matching path with shared Yes and common No Match chain
       city --> nomatch1[No Match Found]:::status
       nomatch1 --> region(("DID matches a<br>Region?")):::staff
       region --> nomatch2[No Match Found]:::status
       nomatch2 --> number(("DID matches a<br>Number Type?")):::staff
       number --> nomatch3[No Match Found]:::status
       nomatch3 --> country(("DID matches a<br>Country?")):::staff
       country --> nomatch4[No Match Found]:::status
       nomatch4 --> allcountries(("Is there a<br>rule set for<br>All Countries?")):::staff
       allcountries --> yes[Yes]:::completed
       allcountries --> no[No]:::status

       %% Color and style definitions (matching the provided image)
       classDef status fill:#f9e6dc,stroke:#ff5c1a,stroke-width:2px,color:#1f2d3d;
       classDef staff fill:#fff4cf,stroke:#ffb000,stroke-width:2px,color:#1f2d3d;
       classDef customer fill:#d7ecfb,stroke:#008ce3,stroke-width:2px,color:#1f2d3d;
       classDef completed fill:#d0f0ec,stroke:#00a99d,stroke-width:2px,color:#1f2d3d;
       classDef canceled fill:#f6d6df,stroke:#e83f6f,stroke-width:2px,color:#1f2d3d;

When multiple rules can match the same DID number, DIDWW checks rules from the most specific match to the broadest match. City-level rules take priority over regional rules, regional rules take priority over number-type rules, and number-type rules take priority over country-level rules.

For priority details, see :ref:`rules_priority`.

Profile and rule relationship
=============================

A rule does not contain routing or Capacity settings directly. Instead, the rule points to a configuration profile. When a newly purchased DID number matches the rule conditions, DIDWW applies the selected profile to that number.

For example, you could create a rule that matches any new Local number purchased in the United States and applies a profile that assigns a specific voice trunk, SMS trunk, Capacity group, and description — without any manual steps after the purchase.

For the profile fields that the rule can apply, see :doc:`profiles-reference`.
For the rule fields and matching order, see :doc:`rules-reference`.

Profile application methods
===========================

Configuration profiles can be applied in two ways:

- **Manually**, from **My Numbers**, using the **Apply Configuration Profile** batch action. Use this for existing numbers that were purchased before a rule was in place, or for numbers that need a one-off configuration. For the procedure, see :doc:`how-to-guides/apply-configuration-profile-manually`.
- **Automatically**, from **Configuration Profiles > Rules**, when a newly purchased number matches a rule's conditions. Use this to ensure every new number receives a standard setup immediately after purchase. For rule creation, see :doc:`how-to-guides/create-rules-for-profiles`.

Registration and service requirements
=====================================

Configuration profiles can help standardize setup after a DID number is purchased or ported in, but they do not replace country, number type, or service requirements. If a DID number requires end-user verification, identity details, or address details, those requirements still apply.

For registration-related number management, see :doc:`../my-numbers/index` and :doc:`../buy-numbers/end-user-verification`.


.. _apply_configuration_profile:

====================================
Apply configuration profile manually
====================================

Apply a configuration profile manually to existing DID numbers in a single action.
This allows you to quickly configure voice, SMS, and capacity settings without creating rules.

Before you begin
================

- At least one active :ref:`DID number <user_panel_buy_numbers_process>` is required to apply configuration profile.
- At least one :ref:`configuration profile <configuration_profiles_profiles_create>` is required.

Step 1: Select DID(s) and open batch actions
============================================

1. In the **Phone Numbers > My Numbers** section, select one or more DIDs you want to configure.
2. At the bottom of the page, open the **Batch Actions** menu.
3. Choose **Apply Configuration Profile** from the list.

.. figure:: https://doc.didww.com/_images/apply-profile1.png
     :alt: Select DID(s) and open Batch Actions to apply a configuration profile.
     :figclass: align-center
     :width: 100%

     **Fig. 3.** Selecting DID(s) and opening Batch Actions to apply a configuration profile

Step 2: Apply configuration profile
===================================

1. In the **Apply Configuration Profile** pop-up, review the selected DID number(s).
2. From the **Configuration Profile** dropdown, select the profile you want to apply.
3. Click **Confirm** to apply the settings to all selected numbers.

.. figure:: https://doc.didww.com/_images/apply-profile2.png
   :alt: Apply a configuration profile to selected DIDs.
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Applying a configuration profile to selected DID numbers

Related resources
=================

- :doc:`../profiles-reference`: Review Configuration Profile fields and actions.
- :doc:`../../my-numbers/batch-actions-reference`: Review My Numbers batch actions.
- :doc:`create-configuration-profile`: Create a configuration profile.
- :doc:`manage-configuration-profiles`: Edit or delete configuration profiles.


.. _configuration_profiles_profiles_create:

============================
Create configuration profile
============================

Create a configuration profile to apply reusable DID number settings in one action.

Before you begin
================

- A voice trunk is required before it can be selected in the **Trunk** field. See :doc:`../../../voice/inbound-trunks/index`.
- An SMS trunk is required before it can be selected in the **SMS Trunk** field. See :doc:`../../../sms/sms-trunks/index`.
- A Capacity group is required before it can be selected in the **Capacity Group** field. See :doc:`../../capacity/how-to-guides/create-capacity-group`.

Step 1: Open the create profile form
====================================

1. In the DIDWW User Panel, go to **Phone Numbers > Configuration Profiles**.
2. Open the **Profiles** tab.
3. Click **Create Profile**.

   .. figure:: https://doc.didww.com/_images/fig1-2.png
      :alt: Create Configuration Profile form.
      :figclass: align-center
      :width: 100%

      **Fig. 1.** Create Configuration Profile form.

Step 2: Configure the profile
=============================

4. Enter a profile name.
5. Select the settings the profile should apply.

.. note:: At least one configuration must be selected to apply the profile to a number.

6. Click **Create**.

   .. figure:: https://doc.didww.com/_images/fig2.png
      :alt: Configured Configuration Profile fields.
      :figclass: align-center
      :width: 100%

      **Fig. 2.** Configured Configuration Profile fields.

Related resources
=================

- :doc:`../profiles-reference`: Review Configuration Profile fields and actions.
- :doc:`../how-configuration-profiles-and-rules-work`: Understand how profiles and rules work.
- :doc:`manage-configuration-profiles`: Edit or delete configuration profiles.
- :doc:`create-rules-for-profiles`: Create rules that apply profiles automatically.


.. _create_a_rule:
.. _configuration_profiles_examples:

=========================
Create rules for profiles
=========================

Create rules to apply configuration profiles automatically to newly purchased DID numbers.

Before you begin
================

- At least one configuration profile is required. See :doc:`create-configuration-profile`.
- Rules apply only to newly purchased DID numbers. They do not update DID numbers that already exist in your account.
- Rule results depend on rule evaluation behavior. More specific rules, such as city rules, take priority over broader rules, such as country rules. See :ref:`rules_priority`.

Step 1: Create a Rule
=====================

1. In the DIDWW User Panel, go to **Phone Numbers > Configuration Profiles**.
2. Open the **Rules** tab.
3. Click **Create Rule**.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Rules page with Create Rule button.

   **Fig. 1.** Rules page.

Step 2: Define the conditions the rule applies to
=================================================

For the rule fields, filters, and priority details used here, see :doc:`../rules-reference`.

4. Enter the rule name.
5. Select the configuration profile to apply.
6. Select the rule conditions.
7. Click **Create**.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Create Rule form with configured fields.

   **Fig. 2.** Create Rule form.

.. _configuration_profiles_configuration_examples:

Configuration examples
======================

Use these examples to see how configuration profiles and rules work together for common DID number setups.

Before you begin
----------------

- Create a configuration profile first. See :doc:`create-configuration-profile`.
- Review the profile and rule fields in :doc:`../profiles-reference` and :doc:`../rules-reference`.
- Rules apply only to newly purchased DID numbers. They do not update DID numbers that already exist in your account.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Global rule

      .. _configuration_profiles_examples_global:

      A global rule applies one configuration profile to all newly purchased DID numbers.

      Use this setup when new DID numbers should use the same voice trunk, SMS trunk, Capacity group, and description by default. If a new DID number supports inbound SMS, the selected SMS trunk is assigned for inbound messages.

      The configuration profile can also include a Capacity group when newly purchased numbers need additional inbound call Capacity after included channels are in use.

      .. rubric:: Profile setup example

      .. list-table::
         :header-rows: 1
         :widths: 30 70

         * - Field
           - Example value
         * - Name
           - Global Default Profile
         * - Capacity Group
           - Pay Per Minute
         * - Trunk
           - Default Voice Trunk
         * - SMS Trunk
           - SMS to Email
         * - Description
           - Global DID configuration

      .. figure:: https://doc.didww.com/_images/fig1-2.png
         :figclass: align-center
         :alt: Global Default Profile.
         :width: 85%

         **Fig. 3.** Global Default Profile.

      .. rubric:: Rule setup example

      .. list-table::
         :header-rows: 1
         :widths: 30 70

         * - Field
           - Example value
         * - Name
           - Global Rule
         * - Profile
           - Global Default Profile
         * - Countries
           - Empty
         * - Number Types
           - Empty
         * - Regions
           - Empty
         * - Cities
           - Empty

      .. figure:: https://doc.didww.com/_images/example1-2.png
         :figclass: align-center
         :alt: Global rule applied to all countries.
         :width: 85%

         **Fig. 4.** Global rule applied to all countries.

   .. tab-item:: Country and number type rules

      .. _configuration_profiles_examples_numbertype:

      Country and number type rules apply different configuration profiles to newly purchased DID numbers in the same country based on DID number type.

      Use this setup when Local, Mobile, National, or Toll-Free DID numbers should use different routing or Capacity settings.

      .. rubric:: Profile setup examples

      .. tab-set::
         :class: my-tabs

         .. tab-item:: Local number type profile

            Use a Local number type profile when Local DID numbers should route to a PBX or another inbound voice trunk.

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA Local Type Profile
               * - Capacity Group
                 - Pay Per Minute
               * - Trunk
                 - My PBX
               * - SMS Trunk
                 - SMS to Email
               * - Description
                 - USA Local Settings

            .. figure:: https://doc.didww.com/_images/example2-1.png
               :figclass: align-center
               :alt: USA Local Type Profile.
               :width: 85%

               **Fig. 5.** USA Local Type Profile.

         .. tab-item:: Toll-Free number type profile

            Use a Toll-Free number type profile when Toll-Free DID numbers should route to a different inbound voice trunk.

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA Toll-Free Profile
               * - Capacity Group
                 - Empty
               * - Trunk
                 - phone.systems
               * - SMS Trunk
                 - SMS to Email
               * - Description
                 - USA Toll-Free Settings

            Toll-Free numbers already include 300 channels by default, so the example does not assign a Capacity group.

            .. figure:: https://doc.didww.com/_images/example2-1-2.png
               :figclass: align-center
               :alt: USA Toll-Free Profile.
               :width: 85%

               **Fig. 6.** USA Toll-Free Profile.

      .. rubric:: Rule setup examples

      .. tab-set::
         :class: my-tabs

         .. tab-item:: Local rule

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA Local Rule
               * - Profile
                 - USA Local Type Profile
               * - Countries
                 - United States
               * - Number Types
                 - Local

            .. figure:: https://doc.didww.com/_images/example2-2-1.png
               :figclass: align-center
               :alt: USA Local Rule.
               :width: 85%

               **Fig. 7.** USA Local Rule.

         .. tab-item:: Toll-Free rule

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA Toll-Free Rule
               * - Profile
                 - USA Toll-Free Profile
               * - Countries
                 - United States
               * - Number Types
                 - Toll-Free

            .. figure:: https://doc.didww.com/_images/example2-2-2.png
               :figclass: align-center
               :alt: USA Toll-Free Rule.
               :width: 85%

               **Fig. 8.** USA Toll-Free Rule.

   .. tab-item:: Regional rules

      .. _configuration_profiles_examples_region:

      Regional rules apply different configuration profiles to newly purchased DID numbers in specific regions.

      Use this setup when DID numbers in different regions should route through different regional trunks. Regional rules are available for supported countries, such as the United States, Canada, and the United Kingdom.

      .. rubric:: Profile setup examples

      .. tab-set::
         :class: my-tabs

         .. tab-item:: New York region profile

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA New York Profile
               * - Capacity Group
                 - Pay Per Minute
               * - Trunk
                 - USA East Coast SIP Trunk
               * - SMS Trunk
                 - SMS to Email
               * - Description
                 - East Coast Regional Settings

            .. figure:: https://doc.didww.com/_images/example3-1-2.png
               :figclass: align-center
               :alt: USA New York Region Profile.
               :width: 85%

               **Fig. 9.** USA New York Region Profile.

         .. tab-item:: California region profile

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA California Profile
               * - Capacity Group
                 - Pay Per Minute
               * - Trunk
                 - USA West Coast SIP Trunk
               * - SMS Trunk
                 - SMS to Email
               * - Description
                 - West Coast Regional Settings

            .. figure:: https://doc.didww.com/_images/example3-1.png
               :figclass: align-center
               :alt: USA California Region Profile.
               :width: 85%

               **Fig. 10.** USA California Region Profile.

      .. rubric:: Rule setup examples

      .. tab-set::
         :class: my-tabs

         .. tab-item:: New York regional rule

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA New York Region Rule
               * - Profile
                 - USA New York Profile
               * - Countries
                 - United States
               * - Number Types
                 - Local
               * - Regions
                 - New York

            .. figure:: https://doc.didww.com/_images/example3-2.png
               :figclass: align-center
               :alt: USA New York Region Rule.
               :width: 85%

               **Fig. 11.** USA New York Region Rule.

         .. tab-item:: California regional rule

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - USA California Region Rule
               * - Profile
                 - USA California Profile
               * - Countries
                 - United States
               * - Number Types
                 - Local
               * - Regions
                 - California

            .. figure:: https://doc.didww.com/_images/example3-2-2.png
               :figclass: align-center
               :alt: USA California Region Rule.
               :width: 85%

               **Fig. 12.** USA California Region Rule.

   .. tab-item:: City rules

      .. _configuration_profiles_examples_city:

      City rules apply different configuration profiles to newly purchased DID numbers in specific cities.

      Use this setup when DID numbers in individual cities should use their own inbound voice trunks, SMS trunks, descriptions, or Capacity settings.

      .. rubric:: Profile setup examples

      .. tab-set::
         :class: my-tabs

         .. tab-item:: Stockholm city profile

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - Sweden Stockholm City Profile
               * - Capacity Group
                 - Pay Per Minute
               * - Trunk
                 - Sweden Stockholm City SIP Trunk
               * - SMS Trunk
                 - SMS to Email
               * - Description
                 - Stockholm City DID Configuration

            .. figure:: https://doc.didww.com/_images/example4-1-1.png
               :figclass: align-center
               :alt: Sweden Stockholm City Profile.
               :width: 85%

               **Fig. 13.** Sweden Stockholm City Profile.

         .. tab-item:: Warsaw city profile

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - Poland Warsaw City Profile
               * - Capacity Group
                 - Pay Per Minute
               * - Trunk
                 - Poland Warsaw City SIP Trunk
               * - SMS Trunk
                 - SMS to Email
               * - Description
                 - Warsaw City DID Configuration

            .. figure:: https://doc.didww.com/_images/example4-1-2.png
               :figclass: align-center
               :alt: Poland Warsaw City Profile.
               :width: 85%

               **Fig. 14.** Poland Warsaw City Profile.

      .. rubric:: Rule setup examples

      .. tab-set::
         :class: my-tabs

         .. tab-item:: Stockholm city rule

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - Sweden Stockholm City Only Rule
               * - Profile
                 - Sweden Stockholm City Profile
               * - Countries
                 - Sweden
               * - Number Types
                 - Local
               * - Cities
                 - Stockholm

            .. figure:: https://doc.didww.com/_images/example4-2-1.png
               :figclass: align-center
               :alt: Sweden Stockholm City Rule.
               :width: 85%

               **Fig. 15.** Sweden Stockholm City Rule.

         .. tab-item:: Warsaw city rule

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Example value
               * - Name
                 - Poland Warsaw City Only Rule
               * - Profile
                 - Poland Warsaw City Profile
               * - Countries
                 - Poland
               * - Number Types
                 - Local
               * - Cities
                 - Warsaw

            .. figure:: https://doc.didww.com/_images/example4-2-2.png
               :figclass: align-center
               :alt: Poland Warsaw City Rule.
               :width: 85%

               **Fig. 16.** Poland Warsaw City Rule.

Related resources
=================

- :doc:`../rules-reference`: Review rule fields, conditions, and evaluation behavior.
- :doc:`../profiles-reference`: Review Configuration Profile fields and actions.
- :doc:`../how-configuration-profiles-and-rules-work`: Understand how profiles and rules work.
- :doc:`create-configuration-profile`: Create a configuration profile.
- :doc:`manage-rules`: Edit or delete rules.


====================================
Configuration profiles how-to guides
====================================

Use these guides to create, apply, and manage Configuration Profiles and rules.

Profiles
========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Create configuration profile**
      :link: create-configuration-profile
      :link-type: doc
      :text-align: left

      Create a reusable profile for voice, SMS, Capacity, and description settings.

   .. grid-item-card:: **Apply configuration profile manually**
      :link: apply-configuration-profile-manually
      :link-type: doc
      :text-align: left

      Apply a profile to existing DID numbers from My Numbers.

   .. grid-item-card:: **Manage configuration profiles**
      :link: manage-configuration-profiles
      :link-type: doc
      :text-align: left

      Edit or delete configuration profiles from the Profiles tab.

Rules
=====

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Create rules for profiles**
      :link: create-rules-for-profiles
      :link-type: doc
      :text-align: left

      Create rules that apply profiles automatically to newly purchased DID numbers.

   .. grid-item-card:: **Manage rules**
      :link: manage-rules
      :link-type: doc
      :text-align: left

      Edit or delete rules from the Rules tab.

.. toctree::
   :maxdepth: 1
   :hidden:

   Create configuration profile <create-configuration-profile.rst>
   Apply configuration profile manually <apply-configuration-profile-manually.rst>
   Manage configuration profiles <manage-configuration-profiles.rst>
   Create rules for profiles <create-rules-for-profiles.rst>
   Manage rules <manage-rules.rst>


.. _manage_configuration_profiles:

=============================
Manage configuration profiles
=============================

Use the **Profiles** tab to edit or delete configuration profiles.

Before you begin
================

- At least one configuration profile is required. See :doc:`create-configuration-profile`.
- Deleting a configuration profile also deletes any rules assigned to it. For rule behavior, see :doc:`../rules-reference`.

Edit a configuration profile
============================

.. _configuration_profiles_profiles_edit:

Use this flow when the reusable DID number settings need to change.

Step 1: Open the profile actions menu
-------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Configuration Profiles**.
2. Open the **Profiles** tab.
3. Find the profile you want to update and click the **Actions > Edit**.

.. figure:: https://doc.didww.com/_images/configuration-profiles-actions-edit.png
   :alt: Edit Configuration Profile actions button.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Edit Configuration Profile actions button.

Step 2: Update the profile
--------------------------

1. In the **Edit Profile** window, update the profile settings.
2. Click **Submit**.

.. figure:: https://doc.didww.com/_images/configuration-profiles-edit.png
   :alt: Edit Configuration Profile form.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Edit Configuration Profile form.

Delete a configuration profile
==============================

.. _configuration_profiles_profiles_delete:

Use this flow when a configuration profile is no longer needed.

Step 1: Open the profile actions menu
-------------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Configuration Profiles**.
2. Open the **Profiles** tab.
3. Find the profile you want to delete and click the **Actions > Delete**.

.. figure:: https://doc.didww.com/_images/configuration-profiles-actions-delete.png
   :alt: Delete Configuration Profile actions button.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Delete Configuration Profile actions button.

Step 2: Confirm deletion
------------------------

1. In the confirmation pop-up, review the profile you are deleting.
2. Click **Delete**.

.. figure:: https://doc.didww.com/_images/configuration-profiles-delete.png
   :alt: Delete Configuration Profile pop-up.
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Delete Configuration Profile pop-up.

Related resources
=================

- :doc:`../profiles-reference`: Review Configuration Profile fields and actions.
- :doc:`../how-configuration-profiles-and-rules-work`: Understand how profiles and rules work.
- :doc:`manage-rules`: Review how assigned rules are edited or deleted.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button


.. _manage_configuration_profile_rules:

============
Manage rules
============

Use the **Rules** tab to edit or delete rules that apply configuration profiles to newly purchased DID numbers.

Before you begin
================

- At least one rule is required. See :doc:`create-rules-for-profiles`.
- Review rule evaluation behavior before changing overlapping rules. See :ref:`rules_priority`.

Edit a rule
===========

.. _edit_a_rule:

Use this flow when the matching conditions or assigned configuration profile need to change.

Step 1: Open the rule actions menu
-----------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Configuration Profiles**.
2. Open the **Rules** tab.
3. Find the rule you want to update and click the **Actions > Edit**.

.. figure:: https://doc.didww.com/_images/rule-actions-edit.png
   :alt: Edit rule actions button.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Edit rule actions button.

Step 2: Update the rule
-----------------------

1. In the **Edit Rule** window, update the rule settings.
2. Click **Submit**.

.. figure:: https://doc.didww.com/_images/rule-edit.png
   :figclass: align-center
   :alt: Edit Rule form.
   :width: 100%

   **Fig. 2.** Edit Rule form.

----

Delete a rule
=============

.. _delete_a_rule:

Use this flow when a rule should no longer apply a configuration profile to newly purchased DID numbers.

Step 1: Open the rule actions menu
----------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Configuration Profiles**.
2. Open the **Rules** tab.
3. Find the rule you want to delete and click the **Actions > Delete**.

.. figure:: https://doc.didww.com/_images/rule-actions-delete.png
   :alt: Delete rule actions button.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Delete rule actions button.

Step 2: Confirm deletion
------------------------

1. In the confirmation pop-up, review the rule you are deleting.
2. Click **Delete**.

.. figure:: https://doc.didww.com/_images/rule-delete.png
   :figclass: align-center
   :alt: Delete Rule confirmation pop-up.
   :width: 100%

   **Fig. 4.** Delete Rule confirmation pop-up.

Related resources
=================

- :doc:`../rules-reference`: Review rule fields, conditions, and evaluation behavior.
- :doc:`create-rules-for-profiles`: Create rules for profiles.
- :doc:`manage-configuration-profiles`: Review how configuration profiles are edited or deleted.


.. _configuration_profiles:
.. _user_panel_cp:

======================
Configuration profiles
======================

Configuration Profiles apply reusable DID number settings in one action. Use this section to understand how profiles and rules work, create reusable configurations, and apply voice, SMS, capacity, and description settings consistently.

Key features
============

- Reuse the same voice, SMS, Capacity, and description settings across multiple DID numbers.
- Apply a saved configuration to existing DID numbers in one step.
- Automatically apply the right configuration to newly purchased DID numbers.
- Choose where a rule applies by country, number type, region, or city.
- Keep DID number setup consistent without re-entering the same details.
- Control which configuration is applied to new numbers as they are purchased.

Get started
===========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **How configuration profiles and rules work**
      :link: how-configuration-profiles-and-rules-work
      :link-type: doc
      :text-align: left

      Understand profiles, rules, rule priority, and how configuration is applied to DID numbers.

   .. grid-item-card:: **How-to guides**
      :link: how-to-guides/index
      :link-type: doc
      :text-align: left

      Create, apply, edit, and delete configuration profiles and rules.

   .. grid-item-card:: **Create rules for profiles**
      :link: how-to-guides/create-rules-for-profiles
      :link-type: doc
      :text-align: left

      Create rules and review examples for country, number type, region, and city rule setups.

References
==========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Configuration profiles reference**
      :link: profiles-reference
      :link-type: doc
      :text-align: left

      Look up profile fields, actions, UI elements, and constraints.

   .. grid-item-card:: **Rules reference**
      :link: rules-reference
      :link-type: doc
      :text-align: left

      Look up rule fields, conditions, actions, and evaluation behavior.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **My Numbers**
      :link: ../my-numbers/index
      :link-type: doc
      :text-align: left

      Manage DID numbers, batch actions, trunks, capacity, services, and descriptions.

   .. grid-item-card:: **Capacity**
      :link: ../capacity/index
      :link-type: doc
      :text-align: left

      Manage Capacity groups, dedicated channels, metered channels, and Capacity limits.

   .. grid-item-card:: **Inbound trunks**
      :link: ../../voice/inbound-trunks/index
      :link-type: doc
      :text-align: left

      Create and manage inbound voice trunks used by configuration profiles.

   .. grid-item-card:: **SMS trunks**
      :link: ../../sms/sms-trunks/index
      :link-type: doc
      :text-align: left

      Create and manage SMS trunks used by configuration profiles.

.. toctree::
   :maxdepth: 1
   :hidden:

   How configuration profiles and rules work <how-configuration-profiles-and-rules-work.rst>
   How-to guides <how-to-guides/index.rst>
   Configuration profiles reference <profiles-reference.rst>
   Rules reference <rules-reference.rst>


.. _configuration_profiles_profiles_reference:
.. _configuration_profiles_reference:

================================
Configuration profiles reference
================================

Configuration Profiles reference explains the fields, filters, actions, and constraints shown on the **Profiles** tab.

Main fields
===========

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Name
     - Editable
     - A friendly name used to identify the configuration profile.
   * - Voice Trunk
     - Editable
     - The inbound voice trunk assigned by the configuration profile when the profile is applied to a DID number.
   * - SMS Trunk
     - Editable
     - The inbound SMS trunk assigned by the configuration profile when the profile is applied to a DID number.
   * - Capacity Group
     - Editable
     - The Capacity group assigned by the configuration profile when the profile is applied to a DID number.
   * - Capacity Limit
     - Editable
     - The per-DID concurrent inbound call limit assigned by the configuration profile when the profile is applied.
   * - Description
     - Editable
     - A note used to identify the DID number on the **My Numbers** page.

----

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Filter
     - Filter condition
     - Description
   * - Name
     - Contains text input
     - Filters profiles by profile name.
   * - Filters
     - Additional filter selector
     - Opens the filter picker for additional available filters on the page.

Filter conditions
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Filter condition
     - Description
   * - Contains text input
     - Matches profile names that contain the entered text.
   * - Additional filter selector
     - Opens the list of extra filters that can be added to the current filter row.

Related resources
=================

- :doc:`how-configuration-profiles-and-rules-work` - Understand how profiles and rules work together.
- :doc:`how-to-guides/create-configuration-profile` - Create a configuration profile.
- :doc:`how-to-guides/apply-configuration-profile-manually` - Apply a profile to existing DID numbers.
- :doc:`how-to-guides/manage-configuration-profiles` - Edit or delete configuration profiles.
- :doc:`rules-reference` - Review rule fields, filters, and behavior.
- :doc:`../my-numbers/batch-actions-reference` - Review **Apply Configuration Profile** in My Numbers batch actions.


.. _configuration_profiles_rules_reference:

===============
Rules reference
===============

Rules reference explains the fields, filters, actions, and priority values shown on the **Rules** tab.

Main fields
===========

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Name
     - Editable
     - A friendly name used to identify the rule.
   * - Profile
     - Editable
     - The configuration profile applied when the rule conditions match a newly purchased DID number.
   * - Countries
     - Editable
     - The country or countries where the rule applies.
   * - Number Types
     - Editable
     - The DID number types where the rule applies, such as Local, Mobile, National, Shared Cost, Toll-free, or Global / UIFN.
   * - Regions
     - Editable
     - The region where the rule applies.
   * - Cities
     - Editable
     - The city where the rule applies.

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Filter
     - Filter condition
     - Description
   * - Name
     - Contains text input
     - Filters rules by rule name.
   * - Country
     - Searchable single-select filter
     - Filters rules by the country assigned in the rule.
   * - Region
     - Single-select filter
     - Filters rules by region.
   * - City
     - Search text input
     - Filters rules by city.
   * - Profile
     - Searchable single-select filter
     - Filters rules by assigned configuration profile.
   * - Number type
     - Multi-select checkbox filter
     - Filters rules by one or more selected DID number types.
   * - Filters
     - Additional filter selector
     - Opens the filter picker for additional available filters on the page.

Filter conditions
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Filter condition
     - Description
   * - Contains text input
     - Matches rule names that contain the entered text.
   * - Searchable single-select filter
     - Allows one value to be selected from a searchable list.
   * - Single-select filter
     - Allows one value to be selected from a list.
   * - Search text input
     - Matches city values using entered search text.
   * - Multi-select checkbox filter
     - Allows multiple DID number types to be selected at the same time.
   * - Additional filter selector
     - Opens the list of extra filters that can be added to the current filter row.

.. _rules_priority:

Rule priority
=============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Priority
     - Rule scope
     - Description
   * - 1
     - City
     - DIDWW checks city-level rules first and applies the matching profile when a city rule matches.

       .. note:: Applying the rule to ``Cities`` is only available when a **single** ``Region`` is selected.
   * - 2
     - Region
     - DIDWW checks region-level rules after city rules when no city rule matches.

       .. note:: Applying the rule to ``Regions`` is only available when a **single** ``Number Type`` and a **single** ``Country`` is selected.
   * - 3
     - Number type
     - DIDWW checks number-type rules after city and region rules when no more specific rule matches.
   * - 4
     - Country
     - DIDWW checks country-level rules after city, region, and number-type rules when no more specific rule matches.
   * - 5
     - All countries
     - DIDWW checks rules that are not limited by country after all more specific rule scopes.

Related resources
=================

- :doc:`how-configuration-profiles-and-rules-work` - Understand how rules apply profiles.
- :doc:`how-to-guides/create-rules-for-profiles` - Create rules and review rule setup examples.
- :doc:`how-to-guides/manage-rules` - Edit or delete rules.
- :doc:`profiles-reference` - Review configuration profile fields, filters, and actions.


.. _my_numbers_batch_actions_reference:

=======================
Batch actions reference
=======================

Batch actions in My Numbers apply supported changes to selected DID numbers. Use this reference to understand available batch actions, when to use them, and documented constraints before applying updates to multiple numbers.

Selecting numbers for batch actions
===================================

To use **Batch Actions**, select one or more DID numbers from the My Numbers table. You can select numbers manually or use the checkbox next to the **DID Number** column to open bulk selection options.

.. figure:: https://doc.didww.com/_images/batch_action_selection_behavior.png
   :alt: Batch Actions menu with selected DID numbers.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Batch Actions menu with selected DID numbers.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Selection option
     - Description
   * - Select All
     - Selects all DID numbers matching the current filter criteria, including DID numbers on other pages.
   * - Select Visible
     - Selects only the DID numbers currently displayed on the page.

Available batch actions
=======================

.. list-table::
   :header-rows: 1
   :widths: 20 35 45
   :width: 100%

   * - Batch action
     - Description
     - Notes and constraints
   * - Renew DIDs
     - Renews selected DID numbers.
     - DID numbers can be renewed at any time. Expired numbers remain in the **Service Aging Pool (SAP)** for 34 days. Manually canceled DID numbers must be restored before they can be renewed. See :doc:`how-to-guides/renew-number`.
   * - Restore Terminated DIDs
     - Restores selected terminated DID numbers.
     - Only manually canceled DID numbers can be restored. If the number has active service time, it can be restored immediately at no additional cost. DID numbers remain in **Service Aging Pool (SAP)** for 34 days after the expiration date. See :doc:`how-to-guides/restore-number`.
   * - Set Number of Billing Cycles
     - Sets how many billing cycles remain before automatic renewal stops for selected DID numbers.
     - Newly purchased DID numbers are set to **Unlimited** billing cycles by default. The maximum value is 999. Leave the field empty to set an unlimited number of billing cycles.
   * - Update Trunks
     - Assigns or unassigns inbound voice trunks for selected DID numbers.
     - Use **Unassign Voice Trunk** to remove the current voice trunk from selected numbers. See :doc:`how-to-guides/assign-voice-trunk`.
   * - Update SMS Trunks
     - Assigns or unassigns an SMS trunk for selected DID numbers.
     - Use **Unassign SMS Trunk** to remove the current SMS trunk from selected numbers. See :doc:`how-to-guides/assign-sms-trunk`.
   * - Update Capacity Group
     - Assigns selected DID numbers to a capacity group or unassigns them from a capacity group.
     - Only DID numbers that support additional capacity can be assigned to a capacity group. To remove group assignment, select **Unassign Capacity Group** in the **Update Capacity Group** window.
   * - Assign Dedicated Channels
     - Assigns flat-rate dedicated channels to selected DID numbers.
     - Select the capacity pool and enter the number of dedicated channels to assign. To unassign dedicated channels, set **Assigned Dedicated Channels** to **0**.
   * - Remove DIDs
     - Cancels selected DID numbers.
     - A confirmation dialog lists the selected DID numbers and allows an optional cancellation reason. See :doc:`how-to-guides/remove-number`.
   * - Update Capacity Limit
     - Sets a maximum number of concurrent inbound calls for selected DID numbers.
     - Updating this value limits concurrent calls for the DID number and does not increase overall account capacity. Clear the field to remove an existing limit. See :doc:`how-to-guides/set-capacity-limits`.
   * - Change Next Capacity Mode
     - Changes the capacity mode that selected DID numbers use in the next billing cycle.
     - Available options are **Clear** (remove the scheduled mode change), **2 included** (DID+2), and **0 included** (DID+0). The update takes effect in the next billing cycle unless the DID number is renewed immediately after the change. See :doc:`how-to-guides/change-next-capacity-mode`.
   * - Update Description
     - Updates the description for selected DID numbers.
     - Use this action when the same description should be applied to multiple selected numbers.
   * - Configure CNAM OUT
     - Submits a CNAM OUT configuration request for selected DID numbers that support CNAM OUT.
     - CNAM OUT can contain up to 15 characters. An identity is required. Submitted requests usually complete review within 48–72 hours. See :doc:`how-to-guides/configure-cnam-out`.
   * - Remove CNAM OUT
     - Submits a CNAM OUT removal request for selected DID numbers with active CNAM OUT.
     - The request remains in **Cancellation Pending** status until verified. CNAM cannot be modified or reapplied while the removal task is pending. Submitted requests usually complete review within 48–72 hours. See :doc:`how-to-guides/configure-cnam-out`.
   * - Apply Configuration Profile
     - Applies a configuration profile to selected DID numbers.
     - At least one configuration profile is required. A profile can apply voice, SMS, capacity, and description settings in one action. See :doc:`../configuration-profiles/index`.
   * - Assign End user Details
     - Assigns identity and address details to selected DID numbers that require registration.
     - Use for DID numbers in **Awaiting Registration** status. Assigned end-user details are submitted for verification review. See :doc:`how-to-guides/assign-end-user-details`.
   * - Unassign End user Details
     - Removes assigned End user Details from selected DID numbers.
     - Use this action when End user Details should no longer be assigned to the selected DID numbers.

Related resources
=================

- :doc:`manage-phone-numbers` — Understand how DID number settings, services, capacity, and lifecycle behavior work together.
- :doc:`my-numbers-reference` — Review fields, values, statuses, service states, and UI indicators.
- :doc:`how-to-guides/index` — Follow step-by-step guides for common single-number and batch tasks.
- :doc:`how-to-guides/change-next-capacity-mode` — Change DID numbers between supported DID+0 and DID+2 capacity modes.
- :doc:`how-to-guides/set-capacity-limits` — Limit concurrent inbound calls for DID numbers.
- :doc:`../capacity/index` — Manage Capacity groups, dedicated channels, shared channels, metered channels, and capacity limits.
- :doc:`../configuration-profiles/index` — Create and apply configuration profiles.
- :doc:`../../identities/index` — Manage identities, addresses, and End user verification.


.. _did_number_setup_and_activation:

====================
Setup and activation
====================

Purchased and ported-in DID numbers remain assigned to your account until they expire, are removed, or are ported out. After assignment, DID numbers often require additional configuration before they can receive inbound calls, receive inbound SMS messages, or activate additional services.

The My Numbers section combines DID number management into one workspace. It shows DID number status, time left, assigned trunks, identities, supported services, capacity, and available actions for single-number and batch updates.

A DID number may already belong to your account but still require configuration before inbound traffic can be delivered. Common reasons include missing inbound trunk assignments, insufficient inbound capacity, required end-user verification, pending service approval, or renewal settings that allow the DID number to expire.

The following flow shows the typical initial configuration process required before a DID number can receive inbound calls or inbound SMS messages.

.. mermaid::

   flowchart LR

       A[DID purchased<br/>or ported in]

       B{Registration<br/>required?}

       C[Assign end-user details]

       D[Ready for configuration]

       E[Assign voice trunk]

       F{Sufficient<br/>capacity?}

       G[Assign capacity]

       H[Inbound calling<br/>ready]

       I[Assign SMS trunk]

       J[Inbound SMS<br/>ready]

       A --> B

       B -->|Yes| C
       B -->|No| D

       C --> D

       D --> E
       E --> F

       F -->|No| G
       F -->|Yes| H

       G --> H

       D --> I
       I --> J

   classDef customer fill:#C9DEEF,color:#222,stroke:#0B84E3,stroke-width:2px
   classDef system fill:#F3E8C5,color:#222,stroke:#F0A000,stroke-width:2px
   classDef idle fill:#E5E7EB,color:#444,stroke:#9CA3AF,stroke-width:2px
   classDef operational fill:#DDF3E4,color:#1F5130,stroke:#33A05A,stroke-width:2px

   class C,E,G,I customer
   class B,F system
   class A,D idle
   class H,J operational

After a DID number is configured and active, My Numbers is also used to manage renewal behavior, billing cycles, capacity changes, service configuration, end-user verification updates, and lifecycle actions such as removal or restoration.

DID number setup can also be automated with :doc:`../configuration-profiles/index`, which applies reusable voice trunk, SMS trunk, and capacity group settings to DID numbers.

For status, trunk, and verification values, see :doc:`my-numbers-reference`.

For task-based instructions, see :doc:`how-to-guides/index`. For actions that can be applied to multiple selected DID numbers, see :doc:`batch-actions-reference`.


.. _my_numbers_filters_reference:

=================
Filters reference
=================

Filters in My Numbers help you find DID numbers by status, routing, geography, supported features, assigned resources, verification data, lifecycle state, and billing information.

Use filters to narrow the displayed DID numbers before reviewing details, exporting results, or applying batch actions.

----

Quick filters
=============

Quick filters appear at the top of the My Numbers page and show counts for DID number groups that may require attention. Filters disappear automatically when no DID numbers match the filter condition.

.. figure:: https://doc.didww.com/_images/MyNumbersQuickFilters.png
   :alt: My Numbers quick filters with status counts.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** My Numbers quick filters with status counts.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Filter
     - Description
   * - All
     - Shows all DID numbers in your account.
   * - Active
     - Shows DID numbers that have active service time.
   * - Not Configured
     - Shows DID numbers without required inbound routing or inbound capacity configuration.
   * - Expiring Soon
     - Shows DID numbers that will not renew automatically because no billing cycles remain.
   * - Awaiting Registration
     - Shows DID numbers waiting for end-user verification approval.
   * - Blocked
     - Shows DID numbers that are blocked and cannot receive inbound calls.
   * - Terminated
     - Shows DID numbers that no longer have active service time or were canceled.
   * - Porting in progress
     - Shows DID numbers currently in the porting process.

----

All filters
===========

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Filter
     - Filter condition
     - Description
   * - :ref:`DID number <my_numbers_did_number_filter_modes>`
     - Contains text input, Single-select filter, :ref:`Bulk Input <my_numbers_bulk_input_did_number_filter>`
     - Filters by DID number.
   * - Description
     - Contains text input
     - Filters by DID number description.
   * - Country
     - Single-select filter
     - Filters by country associated with DID numbers assigned to your account.
   * - Region
     - Single-select filter
     - Filters by region or state associated with DID numbers assigned to your account.
   * - :ref:`Number type <my_numbers_number_type_filter_values>`
     - Multi-select checkbox filter
     - Filters by DID number type.
   * - :ref:`Features <my_numbers_features_filter_values>`
     - Single-select filter
     - Filters by supported DID number feature.
   * - Voice trunk
     - Single-select filter
     - Filters by assigned inbound voice trunk or trunk group.
   * - SMS trunk
     - Single-select filter
     - Filters by assigned inbound SMS trunk or SMS trunk group.
   * - :ref:`Capacity pool <my_numbers_capacity_pool_filter_values>`
     - Single-select filter
     - Filters by assigned capacity pool.
   * - Capacity group
     - Grouped single-select filter
     - Filters by assigned capacity group.
   * - Order ref
     - Equals text input.
     - Filters by order reference.
   * - Verification ref
     - Equals text input.
     - Filters by verification reference.
   * - Regulatory area
     - Single-select filter
     - Filters by regulatory area associated with DID numbers assigned to your account.
   * - Identity
     - Single-select filter
     - Filters by assigned identity.
   * - Address
     - Single-select filter
     - Filters by assigned address.
   * - :ref:`Billing cycles left <my_numbers_billing_cycles_left_filter_conditions>`
     - Condition selector with numeric input, depending on the selected condition.
     - Filters by remaining billing cycles.

.. _my_numbers_filter_methods:

Filter conditions
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Filter condition
     - Description
   * - Contains text input
     - Matches values that contain the entered text or digits.
   * - Equals text input
     - Matches only exact entered values.
   * - Single-select filter
     - Allows one value to be selected from a list.
   * - Grouped single-select filter
     - Allows one value to be selected from grouped list sections.
   * - Multi-select checkbox filter
     - Allows multiple values to be selected at the same time.
   * - Condition selector with numeric input
     - Filters numeric values using conditions such as **Equals**, **Less than**, or **Greater than**.

.. _my_numbers_did_number_filter_modes:

DID number filter modes
-----------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Method
     - Description
   * - Contains
     - Matches DID numbers that contain the entered digits.
   * - Select
     - Selects DID numbers directly from DID numbers assigned to your account.
   * - :ref:`Bulk Input <my_numbers_bulk_input_did_number_filter>`
     - Filters up to 250 DID numbers entered in one field as comma-separated values.

.. _my_numbers_number_type_filter_values:

Number type filter values
-------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Local
     - Geographic DID numbers associated with a city or local area.
   * - Mobile
     - DID numbers associated with mobile numbering.
   * - National
     - DID numbers associated with national numbering.
   * - Shared cost
     - DID numbers where call costs may be shared according to local numbering rules.
   * - Toll-free
     - DID numbers callers can reach without standard caller-paid charges where supported.
   * - Global / UIFN
     - Global or Universal International Freephone Number DID numbers.

.. _my_numbers_features_filter_values:

Features filter values
----------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Any
     - Does not restrict results by supported feature.
   * - Inbound calls
     - Shows DID numbers that support inbound call delivery.
   * - Local CLI
     - Shows DID numbers that support local caller ID usage with DIDWW local routes.
   * - Inbound fax
     - Shows DID numbers that support inbound fax.
   * - Inbound SMS
     - Shows DID numbers that support inbound SMS delivery.
   * - Outbound P2P SMS
     - Shows DID numbers that support outbound person-to-person SMS.
   * - Outbound A2P SMS
     - Shows DID numbers that support outbound A2P SMS usage.
   * - Emergency calling
     - Shows DID numbers that support Emergency Calling.
   * - Outbound CNAM
     - Shows DID numbers that support CNAM OUT.

.. _my_numbers_capacity_pool_filter_values:

Capacity pool filter values
---------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Any
     - Does not restrict results by capacity pool.
   * - Standard
     - Shows DID numbers assigned to the Standard capacity pool.
   * - Extended
     - Shows DID numbers assigned to the Extended capacity pool.

.. _my_numbers_billing_cycles_left_filter_conditions:

Billing cycles left conditions
------------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Condition
     - Description
   * - Equals
     - Matches DID numbers with the exact entered billing cycle value.
   * - Less than
     - Matches DID numbers with fewer billing cycles remaining than the entered value.
   * - Greater than
     - Matches DID numbers with more billing cycles remaining than the entered value.
   * - Unlimited
     - Matches DID numbers configured with unlimited automatic renewal.

----

Related resources
=================

- :doc:`manage-phone-numbers` — Understand DID number management workflows.
- :doc:`how-to-guides/filter-numbers` — Filter DID numbers, including multiple-number searches with Bulk Input.
- :doc:`my-numbers-reference` — Look up field, status, feature, billing, and service values used by filters.
- :doc:`batch-actions-reference` — Review actions that can be applied after filtering and selecting DID numbers.


======================================
Assign DID numbers to a capacity group
======================================

Assign DID numbers to a Capacity group so they can use the group's shared channels, metered channels, or both.

Before you begin
================

- Create the Capacity group before assigning DID numbers to it. See :doc:`Create a Capacity group <../../capacity/how-to-guides/create-capacity-group>`.
- Choose a Capacity group in the pool that matches the DID numbers you plan to assign. For pool and group behavior, see :ref:`Capacity groups <capacity_groups>`.
- Only DID numbers that support additional Capacity can be assigned to a Capacity group. For capacity modes and channel priority, see :doc:`How capacity works <../../capacity/how-capacity-works>`.

Use this flow to assign one or more DID numbers to an existing Capacity group.

Step 1: Select DID numbers
==========================

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID numbers you want to assign to the Capacity group.
3. At the bottom of the page, click **Batch Actions**.
4. Select **Update Capacity Group**.

.. figure:: https://doc.didww.com/_images/3shared_select.png
   :alt: Select DID numbers and open Batch Actions
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Select DID numbers and open Batch Actions

Step 2: Assign the capacity group
=================================

1. In the **Update Capacity Group** window, select a **Capacity Group**.
2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/4update_capacity_group.png
   :alt: Update Capacity Group window
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Update Capacity Group

Related resources
=================

- :doc:`Capacity groups <../../capacity/capacity-groups>` — Understand Capacity group behavior.
- :doc:`Manage shared channels <../../capacity/how-to-guides/manage-shared-channels>` — Assign DID numbers to groups with shared channels.
- :doc:`Manage metered channels <../../capacity/how-to-guides/manage-metered-channels>` — Assign DID numbers to groups with metered channels.


=======================
Assign end-user details
=======================

Assign end-user details to DID numbers that require registration. End-user details connect the number to an identity and address, then start the verification process required for activation.

Before you begin
================

- A DID number in **Awaiting Registration** status is required.
- An identity and address that meet the number requirements are required. See :ref:`Identities & Addresses <user_panel_identities_addresses>`.

Assign end-user details to a single DID number
==============================================

Use this flow when you need to submit identity and address information for one DID number.

Step 1: Open the Awaiting Registration quick filter
---------------------------------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Open the **Awaiting Registration** quick filter.

Step 2: Assign the identity
---------------------------

1. Find the DID number and click **None** in the **Identity** column next to the verification icon.

   .. figure:: https://doc.didww.com/_images/assign_single_did_action.png
      :figclass: align-center
      :alt: Assigning end-user details for a single DID number.
      :width: 100%

      **Fig. 1.** Assigning end-user details for a single DID number.

2. In the **Assign End User Details** pop-up window, select the **Identity** and click **Confirm**.

   .. figure:: https://doc.didww.com/_images/assign_single_did_popup.png
      :figclass: align-center
      :alt: Selecting an identity for a single DID number.
      :width: 100%

      **Fig. 2.** Selecting an identity.

Step 3: Assign the address
--------------------------

1. On the page that opens, click **Assign**.

   .. figure:: https://doc.didww.com/_images/assign_button_page.png
      :figclass: align-center
      :alt: Assign button for end-user details.
      :width: 100%

      **Fig. 3.** Assign button.

2. In the **Assign Address** pop-up window, select the **Address** and click **Confirm**.

   .. figure:: https://doc.didww.com/_images/assign_address_popup.png
      :figclass: align-center
      :alt: Selecting an address for end-user details.
      :width: 100%

      **Fig. 4.** Selecting an address.

----

Assign end-user details to multiple DID numbers
===============================================

Use this flow when several DID numbers can use the same identity and address records.

Step 1: Open the Awaiting Registration quick filter
---------------------------------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Open the **Awaiting Registration** quick filter.

Step 2: Select numbers
----------------------

1. Select the DID numbers you want to update.

   .. figure:: https://doc.didww.com/_images/assign_batch_checkmarks.png
      :figclass: align-center
      :alt: Selecting multiple DID numbers.
      :width: 100%

      **Fig. 5.** Selecting multiple DID numbers.

Step 3: Select the identity
---------------------------

1. At the bottom of the page, click **Batch Actions**.
2. Select **Assign End User Details**.

   .. figure:: https://doc.didww.com/_images/assign_batch_did_action.png
      :figclass: align-center
      :alt: Assign End User Details batch action.
      :width: 100%

      **Fig. 6.** Assign End User Details batch action.

3. In the **Assign End User Details** pop-up window, select the **Identity** and click **Confirm**.

   .. figure:: https://doc.didww.com/_images/assign_batch_identity_popup.png
      :figclass: align-center
      :alt: Selecting an identity for multiple DID numbers.
      :width: 100%

      **Fig. 7.** Selecting an identity.

Step 4: Assign the address
--------------------------

1. On the page that opens, review the selected DID numbers and click **Assign**.

   .. figure:: https://doc.didww.com/_images/assign_batch_button_page.png
      :figclass: align-center
      :alt: Assign button for multiple DID numbers.
      :width: 100%

      **Fig. 8.** Assign button.

2. In the **Assign Address** pop-up window, select the **Address** and click **Confirm**.

   .. figure:: https://doc.didww.com/_images/assign_batch_address_popup.png
      :figclass: align-center
      :alt: Selecting an address for multiple DID numbers.
      :width: 100%

      **Fig. 9.** Selecting an address.

Next steps
==========

- :ref:`Verifications <user_panel_verifications>` — Track the verification request status.
- :doc:`../../buy-numbers/end-user-verification` — Understand End-user verification and activation.
- :doc:`../batch-actions-reference` — Review the **Assign End User Details** batch action.


.. _user_panel_assign_sms_trunk:
.. _assigning-sms-trunk:

===================
Assign an SMS trunk
===================

Assign an inbound SMS trunk to one or more SMS-enabled DID numbers. The assigned trunk can be an SMS to Email trunk, HTTP IN trunk, SMPP ESME trunk, SMPP SMSC trunk, or SMS trunk group, and its configuration determines where incoming messages are delivered.

You can assign an SMS trunk directly from the **Trunk** column for a single DID number or use **Batch Actions** to update multiple DID numbers.

Before you begin
================

- An SMS-capable DID number is required. See :ref:`How to buy numbers <user_panel_purchase>`.
- An inbound SMS trunk is required. See :ref:`SMS Trunks <userpanel_sms>`.

.. _user_panel_assign_sms_trunk_single:
.. _assigning-sms-trunk_single_number:

Assign the trunk for a single DID number
========================================

To assign an inbound SMS trunk to a single DID number, follow these steps.

Step 1: Open My Numbers page
----------------------------

In the DIDWW User Panel, go to **Phone Numbers > My Numbers**, or `open the page directly <https://my.didww.com/#/user_dids>`_.

.. figure:: https://doc.didww.com/_images/both_fig1.png
   :figclass: align-center
   :alt: My Numbers page.
   :width: 100%

   **Fig. 1.** My Numbers page.

Step 2: Assign the trunk
------------------------

Locate the DID number you want to configure. You can use filters such as **Feature: Inbound SMS** to narrow the list.

1. In the **Trunk** column, click **SMS: none**.
2. Select the SMS trunk from the dropdown menu.
3. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/single_gif1.gif
   :figclass: align-center
   :alt: Assigning an SMS trunk to a single DID number.
   :width: 100%

   **Fig. 2.** Assigning an SMS trunk to a single DID number.

.. note::

   To unassign an SMS trunk, select **Unassign SMS Trunk** instead of choosing a trunk.

----

.. _user_panel_assign_sms_trunk_batch:
.. _assigning-sms-trunk_batch_actions:

Assign the trunk for multiple DID numbers
=========================================

To assign an inbound SMS trunk to multiple DID numbers, follow these steps.

Step 1: Open My Numbers page
----------------------------

In the DIDWW User Panel, go to **Phone Numbers > My Numbers**, or `open the page directly <https://my.didww.com/#/user_dids>`_.

.. figure:: https://doc.didww.com/_images/both_fig1.png
   :figclass: align-center
   :alt: My Numbers page.
   :width: 100%

   **Fig. 3.** My Numbers page.

Step 2: Select the numbers
--------------------------

Select the DID numbers you want to update. You can use filters such as **Feature: SMS In** to narrow the list.

You can select numbers in two ways:

1. Check the boxes next to individual DID numbers.
2. Click the checkbox next to the **Country/City** column to open bulk options.

   - **Select All** selects all DID numbers that match the current filter criteria, even if they span multiple pages.
   - **Select Visible** selects only the DID numbers currently shown on the page.

.. figure:: https://doc.didww.com/_images/bulk_fig2.png
   :figclass: align-center
   :alt: Selecting multiple DID numbers.
   :width: 100%

   **Fig. 4.** Selecting multiple DID numbers.

Step 3: Assign the trunk
------------------------

1. At the bottom of the page, click **Batch Actions**.
2. Select **Update SMS Trunks**.
3. Choose the SMS trunk you want to assign.
4. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/bulk_gif1.gif
   :figclass: align-center
   :alt: Assigning an SMS trunk to multiple DID numbers.
   :width: 100%

   **Fig. 5.** Assigning an SMS trunk to multiple DID numbers.

.. note::

   To unassign an SMS trunk from selected DID numbers, select **Unassign SMS Trunk** instead of choosing a trunk.

Related resources
=================

- :doc:`../../../sms/sms-trunks/index` — Create and manage SMS trunks.
- :doc:`../batch-actions-reference` — Review My Numbers batch actions and selection behavior.


.. _user_panel_assign_trunk:

====================
Assign a voice trunk
====================

Assign an inbound voice trunk to one or more DID numbers. The assigned trunk can be a SIP trunk, PSTN trunk, phone.systems™ trunk, or trunk group, and its configuration determines where incoming calls are delivered.

You can assign a voice trunk directly from the **Trunk** column for a single DID number or use **Batch Actions** to update multiple DID numbers.

Before you begin
================

- A DID number is required. See :ref:`How to buy numbers <user_panel_purchase>`.
- An inbound voice trunk is required. See :ref:`Inbound Trunks <user_panel_voice_in>`.

.. _user_panel_assign_trunk_single:

Assign the trunk for a single DID number
========================================

To assign a voice trunk to a single DID number, follow these steps.

Step 1: Open My Numbers page
----------------------------

In the DIDWW User Panel, go to **Phone Numbers > My Numbers**, or `open the page directly <https://my.didww.com/#/user_dids>`_.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: My Numbers page.
   :width: 100%

   **Fig. 1.** My Numbers page.

Step 2: Open the Not Configured quick filter
--------------------------------------------

This step is optional. Select the **Not Configured** quick filter to find DID numbers without a configured inbound voice trunk.

DID numbers without a configured inbound trunk are marked as **Voice: none** in the **Trunk** column.

.. note::

   The **Not Configured** quick filter lists DID numbers that do not have an assigned inbound voice trunk or inbound channels. DIDs in this state, either unassigned or assigned with zero capacity, are unable to receive incoming calls.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Not Configured quick filter.
   :width: 100%

   **Fig. 2.** Not Configured quick filter.

Step 3: Assign the trunk
------------------------

1. Locate the DID number you want to configure.
2. In the **Trunk** column, click the trunk name or **Voice: none**.
3. Select the trunk from the dropdown menu.
4. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Assigning a voice trunk to a single DID number.
   :width: 100%

   **Fig. 3.** Assigning a voice trunk to a single DID number.

.. note::

   To unassign a voice trunk, select **Unassign Voice Trunk** instead of choosing a trunk.

----

.. _user_panel_assign_trunk_batch:

Assign the trunk for multiple DID numbers
=========================================

To assign a voice trunk to multiple DID numbers, follow these steps.

Step 1: Open My Numbers page
----------------------------

In the DIDWW User Panel, go to **Phone Numbers > My Numbers**, or `open the page directly <https://my.didww.com/#/user_dids>`_.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: My Numbers page.
   :width: 100%

   **Fig. 4.** My Numbers page.

Step 2: Open the Not Configured quick filter
--------------------------------------------

This step is optional. Select the **Not Configured** quick filter to find DID numbers without a configured inbound voice trunk.

DID numbers without a configured inbound trunk are marked as **Voice: none** in the **Trunk** column.

.. note::

   The **Not Configured** quick filter lists DID numbers that do not have an assigned inbound voice trunk or inbound channels. DIDs in this state, either unassigned or assigned with zero capacity, are unable to receive incoming calls.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Not Configured quick filter.
   :width: 100%

   **Fig. 5.** Not Configured quick filter.

Step 3: Select the numbers
--------------------------

Select the DID numbers you want to update.

You can select numbers in two ways:

1. Check the boxes next to individual DID numbers.
2. Click the checkbox next to the **Country/City** column to open bulk options.

   - **Select All** selects all DID numbers that match the current filter criteria, even if they span multiple pages.
   - **Select Visible** selects only the DID numbers currently shown on the page.

.. figure:: https://doc.didww.com/_images/gif2.gif
   :figclass: align-center
   :alt: Selecting multiple DID numbers.
   :width: 100%

   **Fig. 6.** Selecting multiple DID numbers.

Step 4: Assign the trunk
------------------------

1. At the bottom of the page, click **Batch Actions**.
2. Select **Update Trunks**.
3. Choose the trunk you want to assign.
4. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/gif3.gif
   :figclass: align-center
   :alt: Assigning a voice trunk to multiple DID numbers.
   :width: 100%

   **Fig. 7.** Assigning a voice trunk to multiple DID numbers.

.. note::

   To unassign a voice trunk from selected DID numbers, select **Unassign Voice Trunk** instead of choosing a trunk.

Related resources
=================

- :doc:`../../../voice/inbound-trunks/creating-a-new-sip-trunk` — Create a SIP trunk for inbound call routing.
- :doc:`../../../voice/inbound-trunks/creating-a-new-pstn-trunk` — Create a PSTN trunk for inbound call routing.
- :doc:`../batch-actions-reference` — Review My Numbers batch actions and selection behavior.


.. _change_next_capacity_mode:

=========================
Change next capacity mode
=========================

For local, national, and mobile numbers, you can choose between two virtual number capacity modes. A capacity mode defines how many inbound voice channels are included in the service price for each DID:

    - **DID+2** — Includes 2 dedicated inbound voice channels in the price of the service. Supplemental channels can be added if required at an additional cost.
    - **DID+0** — No dedicated inbound channels are included. To receive calls, the DID must use additional capacity from flat-rate channels, pay-per-minute channels, or a hybrid of both.

You can change the capacity mode for your number after purchase using **Change Next Capacity Mode**. The update takes effect in the **next billing cycle**, or you can apply it immediately by renewing the DID for your selected period after changing the mode.

.. important::
   To apply the change immediately, renew the DID number for your selected period. For details, see :ref:`Renewing DID Numbers <renew-did-s>`.

----

Before you begin
================

    - At least one active :ref:`DID number <user_panel_buy_numbers_process>` is required.
    - The DID must support `DID+0 and DID+2 capacity modes <https://www.didww.com/services/capacity#:~:text=DID%2B0%20and%20DID%2B2%20virtual%20number%20modes>`_.

.. note:: Numbers that do not support additional capacity modes, such as toll-free numbers with 300 default channels, cannot switch modes.

----

How to change the next capacity mode
=====================================

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Single DID*

      .. raw:: html

         <h3 id="step-1-open-did-management">
           Step 1: Open DID management
           <a class="headerlink" href="#step-1-open-did-management" title="Link to this heading"></a>
         </h3>

      1. In the **User Panel**, go to **My Numbers**.
      2. Find the DID you want to edit.
      3. Click the **three dots** next to the DID and select **Manage DID**.

      .. figure:: https://doc.didww.com/_images/1manageDID.png
         :alt: Manage DID menu
         :figclass: align-center

         **Fig. 1.** Accessing DID management

      .. raw:: html

           <h3 id="step-2-edit-capacity-settings">
             Step 2: Edit capacity settings
             <a class="headerlink" href="#step-2-edit-capacity-settings" title="Link to this heading"></a>
           </h3>

      On the **View Details** page, click **Edit** in the **Configuration** section.

      .. figure:: https://doc.didww.com/_images/2viewDetails.png
         :alt: Edit DID configuration
         :figclass: align-center

         **Fig. 2.** Editing DID configuration

      .. raw:: html

           <h3 id="step-3-update-channels-included">
             Step 3: Update channels included
             <a class="headerlink" href="#step-3-update-channels-included" title="Link to this heading"></a>
           </h3>

      1. In the **Edit Configuration** window, go to **Channels included**.
      2. Choose the number of channels from the dropdown list.
      3. Click **Submit** to save your changes.

      .. important::

         Channels included options:
            - **Clear** — Revert all capacity changes if they have not been applied yet.
            - **2 included** — 2 dedicated channels will be assigned to each DID in the next billing cycle.
            - **0 included** — All dedicated channels will be removed from the DID(s) in the next billing cycle.
              The number(s) must then be assigned to a capacity group to remain operational.

      .. figure:: https://doc.didww.com/_images/3change_included_channels.png
         :alt: Change included channels
         :figclass: align-center

         **Fig. 3.** Selecting the number of included channels

      .. note::

         - If the **Channels included** field does not display a dropdown menu, the DID does not support changing between capacity modes.
         - The selected mode will take effect during the next billing cycle.
         - In case you want the change to take effect immediately, you can renew the DID number for the selected period and update the channels included right away.
           For more details, see the renewal guide: :ref:`renew-did-s`.

   .. tab-item:: *Multiple DIDs*

       .. raw:: html

          <h3 id="step-1-select-dids">
            Step 1: Select DIDs
            <a class="headerlink" href="#step-1-select-dids" title="Link to this heading"></a>
          </h3>

       1. In the **DIDWW User Panel**, go to **My Numbers**.
       2. Select the DIDs you want to update by checking the boxes next to them.

       .. figure:: https://doc.didww.com/_images/1selectnumberscheckboxes.png
          :figclass: align-center
          :alt: Select multiple DIDs

          **Fig. 1.** Selecting multiple DIDs

       .. raw:: html

          <h3 id="step-2-open-batch-actions">
            Step 2: Open batch actions
            <a class="headerlink" href="#step-2-open-batch-actions" title="Link to this heading"></a>
          </h3>

       At the bottom of the page, click **Batch Actions** and choose **Change Next Capacity Mode**.

       .. figure:: https://doc.didww.com/_images/2batchactions.png
          :figclass: align-center
          :alt: Batch change capacity mode

          **Fig. 2.** Using Batch Actions to change the capacity mode

       .. raw:: html

          <h3 id="step-3-change-next-capacity-mode">
            Step 3: Change next capacity mode
            <a class="headerlink" href="#step-3-change-next-capacity-mode" title="Link to this heading"></a>
          </h3>

       1. In the pop-up window, select the new **Next Capacity Mode** for each DID.
       2. Click **Confirm** to save your changes.

       .. important::

          Next Capacity Mode options:
             - **Clear** — Revert all capacity changes if they have not been applied yet.
             - **2 included** — 2 dedicated channels will be assigned to each DID in the next billing cycle.
             - **0 included** — All dedicated channels will be removed from the DID(s) in the next billing cycle.
               The number(s) must then be assigned to a capacity group to remain operational.

       .. figure:: https://doc.didww.com/_images/3nextcapacitymode.png
          :figclass: align-center
          :alt: Change next capacity mode window

          **Fig. 3.** Selecting the next capacity mode

       .. note::

          - The selected mode will take effect during the next billing cycle.
          - In case you want the change to take effect immediately, you can renew the DID number for the selected period and update the channels included right away.
            For more details, see the renewal guide: :ref:`renew-did-s`.


================
Manage CNAM OUT
================

Manage CNAM OUT for DID numbers that support the CNAM OUT feature. CNAM OUT assigns a caller name to the DID number, which may be displayed to the receiving party when the destination operator performs a CNAM lookup.

.. _user_panel_cnam_out:

Enable CNAM OUT
===============

CNAM OUT can be enabled from the **Phone Numbers > My Numbers** page for DID numbers that support the CNAM OUT feature.

.. note::

   - This CNAM activation process is only available for DIDWW US DID numbers.
   - When a CNAM OUT configuration request is submitted, the global CNAM database is updated with the specified CNAM OUT value.
   - The display of CNAM OUT depends on the destination operator. If the destination operator performs a CNAM lookup and retrieves the value from the CNAM database, it will be displayed for the destination number.

Step 1: Select CNAM OUT-supported numbers
-----------------------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Filter the DID numbers that support the CNAM OUT feature.
3. Select the DID numbers for which CNAM OUT should be configured.

.. figure:: https://doc.didww.com/_images/fig1_select_DIDs.png
   :figclass: align-center
   :alt: Selecting CNAM OUT supported DID numbers.

   **Fig. 1.** Selecting CNAM OUT supported DID numbers.

Step 2: Open the Configure CNAM OUT action
------------------------------------------

1. Open **Batch Actions** and select **Configure CNAM OUT**.

.. figure:: https://doc.didww.com/_images/fig2_batch_actions.png
   :figclass: align-center
   :alt: Configure CNAM OUT batch action.

   **Fig. 2.** Configure CNAM OUT batch action.

Step 3: Submit the CNAM OUT request
-----------------------------------

1. Provide the following information:

   - **CNAM OUT** — Enter the desired CNAM, up to 15 characters.
   - **Identity** — Select an existing identity or create a new one.

2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/fig3_enter_CNAM.png
   :figclass: align-center
   :alt: Configure CNAM OUT details.

   **Fig. 3.** Configure CNAM OUT details.

.. note::

   - After the CNAM OUT request is submitted, it will be verified within 48-72 hours.
   - An email with the subject **DIDWW: CNAM Request Submitted** is sent when the request is submitted. After CNAM OUT is activated, another email with the subject **DIDWW: CNAM Activated** is sent.

Step 4: Review the CNAM OUT status
----------------------------------

1. Review the CNAM value and task status in the **Manage DID** section.

.. figure:: https://doc.didww.com/_images/fig4_actions_manage.png
   :figclass: align-center
   :alt: Actions menu for managing a DID number.

   **Fig. 4.** Manage DID action.

2. Open the DID number details page to view the CNAM OUT status and the CNAM assigned to the selected DID number.

.. figure:: https://doc.didww.com/_images/fig5_manage_page.png
   :figclass: align-center
   :alt: CNAM OUT value and status on the DID number details page.

   **Fig. 5.** CNAM OUT value and status.

.. note::

   CNAM cannot be modified or removed while the task is pending or if the DID number does not support CNAM OUT.

----

.. _user_panel_cnam_out_remove:

Remove CNAM OUT
===============

CNAM OUT can be removed for selected DID numbers that have an active CNAM service, indicated by the green CNAM service icon |cnam_icon| in the **Services** column.

Step 1: Select numbers with active CNAM OUT
-------------------------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Select the DID numbers where CNAM OUT is active and should be removed.

Step 2: Open the Remove CNAM OUT action
---------------------------------------

1. Open **Batch Actions** and select **Remove CNAM OUT**.

.. figure:: https://doc.didww.com/_images/1batch_remove_cnam.png
   :figclass: align-center
   :alt: Remove CNAM OUT batch action.

   **Fig. 6.** Remove CNAM OUT batch action.

Step 3: Confirm the removal
---------------------------

1. Review the list of DID numbers for which CNAM OUT will be removed.
2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/2remove_cnam.png
   :figclass: align-center
   :alt: Confirming CNAM OUT removal.

   **Fig. 7.** Confirming CNAM OUT removal.

Step 4: Review the removal status
---------------------------------

1. Open the DID number details page to check the status of the CNAM OUT removal task.

   The status shows **Cancellation Pending** until the request is verified.

.. note::

   - After the **Remove CNAM OUT** request is submitted, it will be verified within 48-72 hours.
   - When a CNAM removal request is submitted, an email with the subject **DIDWW: CNAM Cancelation Request** is sent. After the CNAM removal is completed, another email with the subject **CNAM Canceled** is sent.
   - CNAM cannot be modified or reapplied while the removal task is pending.

Related resources
=================

- :ref:`Caller Name Delivery (CNAM) <user_panel_cnam>` — Understand CNAM IN and CNAM OUT.
- :ref:`Reference fields <my_numbers_reference_fields>` — Review CNAM OUT service states.
- :doc:`../batch-actions-reference` — Review the **Configure CNAM OUT** and **Remove CNAM OUT** batch actions.

.. |cnam_icon| image:: /img/new_user_panel/cnam/cnam_icon.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: CNAM service icon


.. _my_numbers_filter_numbers:

==============
Filter numbers
==============

Filter numbers in My Numbers when you need to find specific DID numbers before reviewing details, exporting results, or applying batch actions. This guide shows how to filter multiple DID numbers at the same time with **Bulk Input**.

Before you begin
================

At least one DID number must be assigned to your account to use filters.

.. _my_numbers_bulk_input_did_number_filter:

Filter DID numbers with bulk input
==================================

Use this flow when you need to filter several known DID numbers at the same time. Up to 250 comma-separated DID numbers can be entered in one Bulk Input search.

Step 1: Open My Numbers page
----------------------------

In the DIDWW User Panel, go to **Phone Numbers > My Numbers**, or `open the page directly <https://my.didww.com/#/user_dids>`_.

Step 2: Filter the DID numbers
------------------------------

1. Click the **DID number** filter.
2. Select **Bulk Input**.
3. Enter the DID numbers separated by commas.
4. Click **Submit**.

.. figure:: https://doc.didww.com/_images/fig5.png
   :alt: Bulk Input DID number filter example.
   :figclass: align-center

   **Fig. 1.** Bulk Input DID number filter example.

Accepted input formats
======================

Bulk Input accepts DID numbers with commas, plus signs, spaces, and parentheses. Other special characters are not accepted.

Supported input formats include:

- ``+370 (37) 123456``
- ``+52 (55) 12345678``
- ``525512345678``
- ``12746237423``
- ``12324234234``

Next steps
==========

- :doc:`../filters-reference` — Review all My Numbers filters and filter conditions.
- :doc:`../batch-actions-reference` — Review actions that can be applied after filtering and selecting DID numbers.


==============
How-to guides
==============

Use these guides to update DID numbers in the My Numbers section. They cover routing, registration-related details, CNAM OUT, renewal, removal, and restoration tasks.

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Assign a voice trunk**
      :link: assign-voice-trunk
      :link-type: doc
      :text-align: left

      Assign a voice trunk to one or more DID numbers.

   .. grid-item-card:: **Assign an SMS trunk**
      :link: assign-sms-trunk
      :link-type: doc
      :text-align: left

      Assign an inbound SMS trunk to one or more SMS-enabled DID numbers.

   .. grid-item-card:: **Assign end-user details**
      :link: assign-end-user-details
      :link-type: doc
      :text-align: left

      Assign identity and address records to numbers that require registration.

   .. grid-item-card:: **Filter numbers**
      :link: filter-numbers
      :link-type: doc
      :text-align: left

      Filter DID numbers, including multiple-number searches with Bulk Input.

   .. grid-item-card:: **Manage CNAM OUT**
      :link: configure-cnam-out
      :link-type: doc
      :text-align: left

      Enable or remove CNAM OUT for supported DID numbers.

   .. grid-item-card:: **Renew a number**
      :link: renew-number
      :link-type: doc
      :text-align: left

      Renew a DID number or renew multiple numbers with a batch action.

   .. grid-item-card:: **Remove a number**
      :link: remove-number
      :link-type: doc
      :text-align: left

      Cancel one DID number or remove multiple DID numbers at once.

   .. grid-item-card:: **Restore a number**
      :link: restore-number
      :link-type: doc
      :text-align: left

      Restore eligible manually canceled DID numbers.

   .. grid-item-card:: **Change next capacity mode**
      :link: change-next-capacity-mode
      :link-type: doc
      :text-align: left

      Change DID numbers between supported DID+0 and DID+2 capacity modes.

   .. grid-item-card:: **Set capacity limits**
      :link: set-capacity-limits
      :link-type: doc
      :text-align: left

      Limit the maximum number of concurrent inbound calls for DID numbers.

   .. grid-item-card:: **Assign DID numbers to a capacity group**
      :link: assign-dids-to-capacity-group
      :link-type: doc
      :text-align: left

      Assign one or more DID numbers to an existing Capacity group.

   .. grid-item-card:: **Unassign DID numbers from a capacity group**
      :link: unassign-dids-from-capacity-group
      :link-type: doc
      :text-align: left

      Remove one or more DID numbers from their current capacity group.

.. toctree::
   :maxdepth: 1
   :hidden:

   Assign a voice trunk <assign-voice-trunk.rst>
   Assign an SMS trunk <assign-sms-trunk.rst>
   Assign end-user details <assign-end-user-details.rst>
   Filter numbers <filter-numbers.rst>
   Manage CNAM OUT <configure-cnam-out.rst>
   Renew a number <renew-number.rst>
   Remove a number <remove-number.rst>
   Restore a number <restore-number.rst>
   Change next capacity mode <change-next-capacity-mode.rst>
   Set capacity limits <set-capacity-limits.rst>
   Assign DID numbers to a capacity group <assign-dids-to-capacity-group.rst>
   Unassign DID numbers from a capacity group <unassign-dids-from-capacity-group.rst>


.. _renew-did-s:

==============
Renew a number
==============

Renew a DID number from the **Actions** column on the My Numbers page. You can also renew multiple DID numbers at once with **Batch Actions**.

Before you begin
================

- You can renew DID numbers at any time.
- Expired numbers remain in the **Service Aging Pool (SAP)** for 34 days.
- If a number was manually canceled, restore it before renewing it.

Renew a single number
=====================

Use this flow when you need to renew one DID number from its row-level actions menu.

Step 1: Open the renew action
-----------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Locate the DID number you want to renew.
3. In the **Actions** column, click the |three-dots| button and select **Renew service**.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Renew service action for a DID number.

   **Fig. 1.** Renew service action.

Step 2: Confirm the renewal
---------------------------

1. In the **Renew DID(s)** pop-up window, select the billing period.
2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Renew DID number confirmation window.

   **Fig. 2.** Renew DID number confirmation window.

----

Renew multiple numbers
======================

Use this flow when you need to renew more than one DID number in the same batch action.

Step 1: Select numbers
----------------------

1. Go to **Phone Numbers > My Numbers**.
2. Select the DID numbers you want to renew.

.. figure:: https://doc.didww.com/_images/renew_select_numbers.png
   :figclass: align-center
   :alt: Selecting multiple DID numbers in the My Numbers table.

   **Fig. 3.** Selecting multiple DID numbers.

Step 2: Open the batch renew action
-----------------------------------

1. At the bottom of the page, open **Batch Actions**.
2. Select **Renew DIDs**.

.. figure:: https://doc.didww.com/_images/renew_batch_action.png
   :figclass: align-center
   :alt: Selecting Renew DIDs from the Batch Actions menu.

   **Fig. 4.** Selecting the Renew DIDs batch action.

Step 3: Confirm the renewal
---------------------------

1. In the **Renew DID(s)** pop-up window, select the billing period.
2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/renew_batch_confirm.png
   :figclass: align-center
   :alt: Renew DID(s) confirmation window for multiple DID numbers.

   **Fig. 5.** Confirming renewal for multiple DID numbers.

Related resources
=================

- :ref:`Reference fields <my_numbers_reference_fields>` — Review renewal, expiry, and billing-cycle fields.
- :doc:`../batch-actions-reference` — Review the **Renew DIDs** batch action.

.. |three-dots| image:: /img/new_user_panel/did_numbers/manage_phone_numbers/three_dots.png
   :alt: Actions menu
   :width: 22px


.. _my_numbers_remove_dids:

===============
Remove a number
===============

Remove a DID number from the **Actions** column on the My Numbers page. You can also remove multiple DID numbers at once with **Batch Actions**.

Remove a single number
======================

1. Go to **Phone Numbers > My Numbers**.
2. Locate the DID number you want to cancel.
3. In the **Actions** column, click the |three-dots| button and select **Cancel service**.

   .. figure:: https://doc.didww.com/_images/fig6.png
      :figclass: align-center
      :alt: Cancel service action for a single DID number.

      **Fig. 1.** Cancel service action.

4. In the confirmation dialog, optionally provide a cancellation reason.
5. Click **Confirm**.

   .. figure:: https://doc.didww.com/_images/fig7.png
      :figclass: align-center
      :alt: Confirmation screen for removing a single DID number.

      **Fig. 2.** Confirmation screen for removing a single DID number.

----

Remove multiple numbers
=======================

1. Go to **Phone Numbers > My Numbers**.
2. Select the DID numbers you want to cancel.
3. At the bottom of the page, open **Batch Actions**.
4. Select **Remove DIDs**.

   .. figure:: https://doc.didww.com/_images/fig9.png
      :figclass: align-center
      :alt: Remove DIDs batch action.

      **Fig. 3.** Remove DIDs batch action.

5. In the confirmation dialog, review the selected DID numbers and optionally provide a cancellation reason.
6. Click **Confirm**.

   .. figure:: https://doc.didww.com/_images/fig10.png
      :figclass: align-center
      :alt: Confirmation screen for removing multiple DID numbers.

      **Fig. 4.** Confirmation screen for removing multiple DID numbers.

Related resources
=================

- :doc:`restore-number` — Restore eligible manually canceled DID numbers.
- :doc:`../batch-actions-reference` — Review the **Remove DIDs** batch action.

.. |three-dots| image:: /img/new_user_panel/did_numbers/manage_phone_numbers/three_dots.png
   :alt: Actions menu
   :width: 22px


================
Restore a number
================

Restore a manually canceled DID number from the **Terminated** quick filter on the My Numbers page. You can also restore multiple terminated DID numbers at once with **Batch Actions**.

Before you begin
================

- You can restore only manually canceled DID numbers.
- If the number has active service time, you can restore it immediately at no additional cost.
- DID numbers remain in the **Service Aging Pool (SAP)** for 34 days after the expiration date.

Restore a single terminated number
==================================

Use this flow when you need to restore one DID number from its row-level actions menu.

1. Go to **Phone Numbers > My Numbers**.
2. Select the **Terminated** quick filter.
3. Locate the DID number you want to restore.
4. In the **Actions** column, click the |three-dots| button and select **Restore**.

   .. figure:: https://doc.didww.com/_images/fig1.png
      :figclass: align-center
      :alt: Restore action for a terminated DID number.

      **Fig. 1.** Restore action.

5. In the pop-up window, click **Submit** to send the restore request.

   .. figure:: https://doc.didww.com/_images/fig2.png
      :figclass: align-center
      :alt: Restore DID number request window.

      **Fig. 2.** Restore DID number request window.

----

Restore multiple terminated numbers
===================================

Use this flow when you need to restore more than one terminated DID number in the same batch action.

Step 1: Select terminated numbers
---------------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Select the **Terminated** quick filter.
3. Select the DID numbers you want to restore.

.. figure:: https://doc.didww.com/_images/restore_select_numbers.png
   :figclass: align-center
   :alt: Selecting multiple terminated DID numbers in the My Numbers table.

   **Fig. 3.** Selecting multiple terminated DID numbers.

Step 2: Open the batch restore action
-------------------------------------

1. At the bottom of the page, open **Batch Actions**.
2. Select **Restore Terminated DIDs**.

.. figure:: https://doc.didww.com/_images/restore_batch_action.png
   :figclass: align-center
   :alt: Selecting Restore Terminated DIDs from the Batch Actions menu.

   **Fig. 4.** Selecting the Restore Terminated DIDs batch action.

Step 3: Submit the restore request
----------------------------------

1. In the **Restore Terminated DID(s)** pop-up window, review the selected DID numbers.
2. Click **Submit**.

.. figure:: https://doc.didww.com/_images/restore_batch_confirm.png
   :figclass: align-center
   :alt: Restore Terminated DID(s) confirmation window for multiple DID numbers.

   **Fig. 5.** Submitting a restore request for multiple DID numbers.

Related resources
=================

- :ref:`Reference fields <my_numbers_reference_fields>` — Review SAP and restore eligibility details.
- :doc:`../batch-actions-reference` — Review the **Restore Terminated DIDs** batch action.

.. |three-dots| image:: /img/new_user_panel/did_numbers/manage_phone_numbers/three_dots.png
   :alt: Actions menu
   :width: 22px


.. _capacity_set_capacity_limits:

Set capacity limits
====================

Set capacity limits to control the maximum number of concurrent inbound calls for one or more DID numbers. Updating a capacity limit restricts call handling for the DID number, but it does not add more Capacity to the account.

.. important::

   Updating this value only limits concurrent calls for the DID. It does **not** increase your overall account capacity.

Limit capacity for a single DID number
--------------------------------------

1. Go to **My Numbers** in the DIDWW User Panel.
2. Locate the DID in the **Capacity** column.
3. Hover over the capacity value and click it to edit.
4. Enter the desired number of concurrent calls or clear the field to remove the limit.

.. figure:: https://doc.didww.com/_images/single_capacity_limit.png
   :alt: Editing capacity directly in the My Numbers list
   :figclass: align-center

   **Fig. 1.** Editing capacity directly in the **My Numbers** list.

----

Limit capacity for multiple DID numbers
---------------------------------------

1. Go to **My Numbers** in the DIDWW User Panel.
2. Select the checkboxes next to the DIDs you want to update.
3. At the bottom of the page, click **Batch Actions**.
4. From the dropdown menu, choose **Update Capacity Limit**.
5. Enter the desired capacity limit for concurrent calls in the pop-up window or clear the field to remove any existing limit.

.. figure:: https://doc.didww.com/_images/multiple_capacity_select.png
   :alt: Selecting multiple DID numbers and opening batch actions
   :figclass: align-center

   **Fig. 2.** Selecting multiple DIDs and opening batch actions


==========================================
Unassign DID numbers from a capacity group
==========================================

Unassign DID numbers from a Capacity group when they should no longer use the group's shared or metered channels.

Before you begin
================

- Review the DID number's capacity mode before unassigning it from a group. A DID+0 number needs additional Capacity to receive inbound calls. See :doc:`How capacity works <../../capacity/how-capacity-works>`.
- Review the Capacity group behavior and constraints before removing numbers from the group. See :ref:`Capacity groups <capacity_groups>`.
- If you plan to delete the group after unassigning DID numbers, see :doc:`Delete a Capacity group <../../capacity/how-to-guides/delete-capacity-group>`.

Step 1: Filter DID numbers by capacity group
============================================

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the **Active** or **All Numbers** tab.
3. Open **Filters** and enable the **Capacity group** filter.
4. Select the pool and Capacity group.

.. figure:: https://doc.didww.com/_images/step1filter-numbers.png
   :alt: Filter DID numbers by Capacity group
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Filter DID numbers by Capacity group

Step 2: Open the Update Capacity Group action
=============================================

1. Select the DID numbers.
2. At the bottom of the page, click **Batch Actions**.
3. Select **Update Capacity Group**.

.. figure:: https://doc.didww.com/_images/step3select_numbers.png
   :alt: Select DID numbers and open Update Capacity Group
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Open Update Capacity Group

Step 3: Unassign the capacity group
===================================

1. In the **Update Capacity Group** window, open the **Capacity group** dropdown.
2. Select **Unassign Capacity Group**.
3. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/unassign_capacity_group.png
   :alt: Unassign Capacity Group option
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Unassign Capacity Group

Related resources
=================

- :doc:`Capacity groups <../../capacity/capacity-groups>` — Understand group behavior and constraints.
- :doc:`How capacity works <../../capacity/how-capacity-works>` — Understand what happens when no channel is available.
- :doc:`Delete a Capacity group <../../capacity/how-to-guides/delete-capacity-group>` — Delete a group after DID numbers are unassigned.


==========
My Numbers
==========

My Numbers is the main workspace for DID numbers assigned to your account. Use it to monitor number status and time left, filter and search DID numbers assigned to your account, review assigned trunks, identity details, services, and capacity, and apply single-number or batch actions.

Key features
============

- View DID numbers assigned to your account and their status, time left, supported features, trunks, identities, services, and capacity.
- Filter numbers by status, country, region, number type, supported features, trunks, capacity, references, identity, address, and billing cycles.
- Assign or unassign voice and SMS trunks.
- Manage renewal, removal, restoration, billing cycles, and automatic renewal behavior.
- Manage capacity groups, dedicated channels, capacity limits, and next capacity mode.
- Apply configuration profiles to update voice, SMS, capacity, and description settings.
- Assign and unassign end-user details for numbers that require registration.
- Configure or remove CNAM OUT for supported numbers.
- Export DID numbers as CSV.

Get started
===========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Setup and activation**
      :link: did-number-setup-and-activation
      :link-type: doc
      :text-align: left

      Understand the initial configuration path for purchased and ported-in DID numbers.

   .. grid-item-card:: **Manage numbers**
      :link: manage-phone-numbers
      :link-type: doc
      :text-align: left

      Understand single-number settings, services, capacity, billing details, and registration-related controls.

   .. grid-item-card:: **How-to guides**
      :link: how-to-guides/index
      :link-type: doc
      :text-align: left

      Assign trunks, assign end-user details, manage CNAM OUT, renew, remove, and restore DID numbers.

References
==========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **My numbers reference**
      :link: my-numbers-reference
      :link-type: doc
      :text-align: left

      Look up My Numbers fields, values, statuses, service states, and UI indicators.

   .. grid-item-card:: **Filters reference**
      :link: filters-reference
      :link-type: doc
      :text-align: left

      Look up quick filters, default filters, additional filters, and bulk input rules.

   .. grid-item-card:: **Batch actions reference**
      :link: batch-actions-reference
      :link-type: doc
      :text-align: left

      Review available batch actions, when to use them, and their constraints.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Buy numbers**
      :link: ../buy-numbers/index
      :link-type: doc
      :text-align: left

      Purchase new DID numbers and download DIDWW pricelists.

   .. grid-item-card:: **Number billing**
      :link: ../number-billing
      :link-type: doc
      :text-align: left

      Understand setup charges, recurring charges, billing cycles, renewal periods, and capacity billing impact.

   .. grid-item-card:: **Export numbers**
      :link: userpanel_exports_didnumbers
      :link-type: ref
      :text-align: left

      Create and download DID number exports with number details, routing information, services, capacity, and selected filters.

   .. grid-item-card:: **Capacity**
      :link: ../capacity/index
      :link-type: doc
      :text-align: left

      Manage dedicated, metered, and hybrid inbound call capacity.

   .. grid-item-card:: **Configuration profiles**
      :link: ../configuration-profiles/index
      :link-type: doc
      :text-align: left

      Apply reusable voice, SMS, capacity, and description settings to DID numbers.

   .. grid-item-card:: **Identities & addresses**
      :link: ../../identities/index
      :link-type: doc
      :text-align: left

      Manage identity and address records used for registration and service activation.

   .. grid-item-card:: **Inbound trunks**
      :link: ../../voice/inbound-trunks/index
      :link-type: doc
      :text-align: left

      Create and manage inbound voice trunks for call routing.

   .. grid-item-card:: **SMS trunks**
      :link: ../../sms/sms-trunks/index
      :link-type: doc
      :text-align: left

      Create and manage SMS trunks for inbound messaging.

.. toctree::
   :maxdepth: 1
   :hidden:

   Setup and activation <did-number-setup-and-activation.rst>
   Manage numbers <manage-phone-numbers.rst>
   How-to guides <how-to-guides/index.rst>
   My numbers reference <my-numbers-reference.rst>
   Filters reference <filters-reference.rst>
   Batch actions reference <batch-actions-reference.rst>


==============
Manage numbers
==============

My Numbers page is the main workspace for managing DID numbers assigned to your account. It allows you to configure inbound routing, manage capacity, assign end-user details, control renewal behavior, and manage supported DID number services.

My Numbers provides two primary ways to manage DID numbers: the My Numbers table and the DID number details page.

My Numbers table
================

The My Numbers table lets you review and update DID numbers assigned to your account. It provides centralized tools for filtering, searching, exporting, monitoring lifecycle state, and applying single-number or batch updates.

For details about table fields, filters, and batch actions, see :doc:`my-numbers-reference`, :doc:`filters-reference`, and :doc:`batch-actions-reference`.

.. figure:: https://doc.didww.com/_images/mynumbers.png
   :alt: My Numbers table showing filters, batch actions, search controls, and row actions.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** DID number management from the My Numbers table.

View details page
=================

The View Details page is used to review and manage one DID number in more detail. It groups DID number information into Trunks, Capacity, Order Details, Billing, and Services sections.

To view details, click the DID number or use **Actions** > **Manage DID** for the selected DID number.

.. figure:: https://doc.didww.com/_images/view_details_overview.png
   :alt: DID number details page showing Trunks, Capacity, Order Details, Billing, and Services sections.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** DID number details page.

General information
===================

DID number information identifies the DID number and shows its current operational and lifecycle state. This information is used to determine whether the DID number is active, which features it supports, where it is located, and whether additional configuration or review may still be required.

Displayed DID number information includes identifying, status, lifecycle, and supported-feature information associated with the DID number.

Supported feature indicators show which DID number capabilities are available for the number, such as voice, SMS, fax, local CLI, or other supported DID features. A supported feature does not mean the related configuration is already complete. For example, a DID number may support inbound SMS, but SMS messages are not delivered until an inbound SMS trunk is assigned.

For DID number statuses, supported feature indicators, and related UI values, see :doc:`my-numbers-reference`.

Trunks
======

Trunks control where inbound calls and inbound SMS messages are routed for a DID number.

- Inbound voice trunks are used for inbound call routing.
- Inbound SMS trunks are used for inbound SMS message routing.

Voice and SMS trunk assignments are independent.

As shown in :doc:`did-number-setup-and-activation`, DID numbers require trunk assignment before inbound calls or inbound SMS messages can be delivered.

For trunk assignment fields and related UI values, see :doc:`my-numbers-reference`.

To learn how to assign trunks to your DID numbers, see :doc:`how-to-guides/assign-voice-trunk` and :doc:`how-to-guides/assign-sms-trunk`.

End user details
================

Some DID numbers require approved end-user details before they can become active.

End user details connect DID numbers to identity and address information used for regulatory verification and DID number activation.

Verification requirements depend on country, DID number type, and local telecommunications regulations.

When verification is required, the DID number remains pending until the submitted information is reviewed and approved.

For verification states, and other registration-related indicators, see :doc:`my-numbers-reference`.

To learn how to assign end-user details to your DID numbers, see :doc:`how-to-guides/assign-end-user-details`.

Capacity
========

Capacity controls how many concurrent inbound calls a DID number can receive.

Inbound call delivery depends on both assigned inbound voice trunks and available inbound capacity.

Depending on the DID number billing model and capacity configuration, inbound capacity may be provided through included channels, dedicated channels, or shared capacity groups.

Capacity limits can also be used to restrict concurrent inbound call handling for a DID number.

Capacity settings determine how inbound call capacity is allocated and how concurrent inbound calls are handled for the DID number.

For capacity-related fields, indicators, and channel values, see :doc:`my-numbers-reference`.

For capacity modes, channel allocation, and capacity configuration details, see :doc:`../capacity/index`. To change Channels included for a DID number, see :doc:`how-to-guides/change-next-capacity-mode`. To restrict concurrent inbound calls for a DID number, see :doc:`how-to-guides/set-capacity-limits`.

Order details
=============

Order details identify how and when the DID number was assigned to your account.

Order information connects the DID number to the original purchase or porting order associated with the DID number.

Order references and assignment timestamps are used to track DID number provisioning and lifecycle activity.

For order-related fields and values, see :doc:`my-numbers-reference`.

Billing
=======

Billing information determines how long a DID number remains active and how the DID number renews over time.

Billing settings are used to determine DID number expiry, billing period, renewal behavior, and remaining billing cycles.

Billing information is also used to identify DID numbers that require renewal, restoration, or removal.

For billing-related fields, lifecycle values, and renewal indicators, see :doc:`my-numbers-reference`.

For number billing concepts, including setup and recurring charges, see :doc:`../number-billing`.

For lifecycle tasks, see :doc:`how-to-guides/renew-number`, :doc:`how-to-guides/remove-number`, and :doc:`how-to-guides/restore-number`.

Billing cycles
--------------

The billing period defines the length of each renewal, while billing cycles control how many future automatic renewals can occur. A billing cycle follows the billing period configured for the DID number, so one cycle may represent a month, a quarter, a year, or another supported period.

Billing cycles can be used to keep a DID number renewing indefinitely or to schedule a limited number of renewals. This is useful for temporary projects, planned migrations, or DID numbers that should remain active until a known future date without requiring immediate cancellation.

An unlimited setting allows automatic renewal to continue until the setting is changed or the DID number is removed. When a specific number of billing cycles is set, the value decreases after each automatic renewal. When it reaches 0, the DID number does not renew again and expires at the end of its current paid service period.

For example, if a DID number with a monthly billing period is no longer needed after three more renewals, set its remaining billing cycles to 3. The DID number renews for three additional monthly periods. After the third renewal, the remaining value reaches 0 and the number expires when that final paid period ends.

.. note::

   - Billing cycles cannot be configured while purchasing a DID number. After the purchase is complete, set the remaining billing cycles from **Phone Numbers > My Numbers**.
   - Setting a limited number of billing cycles does not cancel a DID number immediately. The DID number remains active until all remaining billing cycles have been used. You can change the remaining billing cycles at any time before the DID number expires. To cancel a DID number immediately, remove it manually instead of waiting for the remaining billing cycles to complete.
   - When a DID number expires after all billing cycles have been used, it is moved to the Service Aging Pool (SAP), where it remains recoverable for 34 days before being permanently removed.

For billing period values and billing cycle values, see :ref:`My Numbers billing fields <my_numbers_billing_fields>`. To set the remaining billing cycles for one or more DID numbers, see :doc:`batch-actions-reference`.

Services
========

Services represent additional services associated with the DID number, such as Emergency Calling, CNAM OUT, or A2P messaging services.

Available services depend on factors such as country, DID number type, and regulatory requirements.

Some services require additional configuration, approval, verification, or linked resources before they become operational.

Service information shows the current state of services associated with the DID number.

.. figure:: https://doc.didww.com/_images/services.png
   :alt: Service information showing Emergency Calling, CNAM OUT, and Sender ID Verification states for a DID number.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** DID number services and service states.

For service indicators and service-related values, see :doc:`my-numbers-reference`.

For service configuration tasks, see :doc:`how-to-guides/configure-cnam-out`, :doc:`../../voice/emergency-calling/index`, and :ref:`Sender ID Verifications <user_panel_sms_campaign>`.

Related resources
=================

- :doc:`did-number-setup-and-activation` — Understand the initial configuration path for purchased and ported-in DID numbers.
- :doc:`my-numbers-reference` — Look up My Numbers fields, statuses, service states, billing values, and UI indicators.
- :doc:`../number-billing` — Understand setup charges, recurring charges, billing cycles, and capacity billing impact.
- :doc:`how-to-guides/index` — Configure trunks, assign end-user details, manage CNAM OUT, change next capacity mode, set capacity limits, renew DID numbers, remove DID numbers, and restore DID numbers.
- :doc:`how-to-guides/change-next-capacity-mode` — Change DID numbers between supported DID+0 and DID+2 capacity modes.
- :doc:`how-to-guides/set-capacity-limits` — Limit concurrent inbound calls for DID numbers.
- :doc:`../capacity/index` — Understand Capacity groups, dedicated channels, shared channels, metered channels, and capacity modes.
- :doc:`../configuration-profiles/index` — Manage reusable DID number configuration profiles.
- :doc:`../../identities/index` — Manage identities and address records.
- :doc:`../../voice/emergency-calling/index` — Configure Emergency Calling for supported DID numbers.
- :ref:`Caller Name Delivery (CNAM) <user_panel_cnam>` — Understand CNAM IN and CNAM OUT.
- :ref:`Sender ID Verifications <user_panel_sms_campaign>` — Register sender IDs for A2P SMS.


.. _my_numbers_reference:
.. _my_numbers_reference_fields:

====================
My Numbers reference
====================

My Numbers reference explains the fields, statuses, values, indicators, and service states shown in the My Numbers section and on DID number details pages.

----

Main fields
===========

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - DID number
     - Read-only
     - The telephone number assigned to the account. Selecting the DID number from the My Numbers table opens the DID number details page.
   * - Country / City
     - Read-only
     - The country and city associated with the DID number. Local numbers show the city. Non-local numbers may show the :ref:`number type <my_numbers_number_type_values>` instead.
   * - :ref:`Number type <my_numbers_number_type_values>`
     - Read-only
     - The classification of the DID number based on numbering type and routing category
   * - :ref:`Status <my_numbers_status_values>`
     - Read-only
     - The current lifecycle or operational condition of the DID number. Read together with routing, capacity, verification, and renewal fields.
   * - Time left
     - Read-only
     - The remaining time in the current service period. Status indicators associated with the DID number can show whether the remaining service time requires attention.
   * - :ref:`Supported features <my_numbers_supported_feature_icons>`
     - Read-only
     - Icons that show which capabilities the DID number can support. A supported feature does not mean the feature is configured or active.
   * - Description
     - Editable
     - A custom description used to identify the DID number. Can be updated for one number or by batch action.

.. _my_numbers_number_type_values:

Number type values
------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Local
     - A geographic DID number associated with a city or local area.
   * - Mobile
     - A DID number associated with mobile numbering.
   * - National
     - A DID number associated with national numbering.
   * - Shared Cost
     - A DID number type where call costs may be shared according to local numbering rules.
   * - Toll-free
     - A DID number type that allows callers to reach the number without standard caller-paid charges where supported.
   * - Global / UIFN
     - A global or Universal International Freephone Number type.

.. _my_numbers_status_values:

Status values
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - |green-status| Active
     - The DID number has remaining service time and can receive services when required routing and capacity configuration are complete.
   * - |yellow-status| Not Configured
     - Required voice routing or usable inbound capacity is missing. DID numbers in this state cannot receive inbound calls.
   * - |yellow-status| Awaiting Registration
     - End-user verification is required before activation can be completed.
   * - |yellow-status| Expiring Soon
     - The DID number will not renew automatically because no billing cycles remain.
   * - |yellow-status| Porting in progress
     - The DID number has been added to the account and is still in the porting process.
   * - |red-status| Blocked
     - The DID number is blocked and cannot receive incoming calls.
   * - |red-status| Terminated
     - The DID number has no service time left or was canceled.

.. _my_numbers_supported_feature_icons:

Supported features
------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Feature
     - Description
   * - |inbound-calls| Inbound calls
     - The DID number supports inbound call delivery through supported inbound voice trunk types.
   * - |local-cli| Local CLI
     - The DID number can be used as caller ID with DIDWW local routes.
   * - |fax| Inbound Fax
     - The DID number supports inbound fax using T.38 or G.711u passthrough.
   * - |sms-in| Inbound SMS
     - The DID number supports inbound SMS delivery through supported inbound SMS trunk types.
   * - |sms-out| Outbound P2P SMS
     - The DID number supports outbound person-to-person SMS through SMPP and HTTP.

----

Trunks
======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - :ref:`Inbound voice trunk <my_numbers_inbound_voice_trunk_values>`
     - Editable
     - The inbound voice trunk assigned to the DID number. The assigned trunk determines how inbound calls are routed from DIDWW to the configured destination. See :doc:`how-to-guides/assign-voice-trunk`.
   * - :ref:`Inbound SMS trunk <my_numbers_inbound_sms_trunk_values>`
     - Editable
     - The inbound SMS trunk assigned to the DID number. SMS routing requires an SMS-capable DID number. See :doc:`how-to-guides/assign-sms-trunk`.

.. _my_numbers_inbound_voice_trunk_values:

Inbound voice trunk values
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Voice: none
     - No inbound voice trunk is assigned.
   * - SIP trunk
     - A SIP trunk assigned for inbound call delivery. See :ref:`Creating a New SIP Trunk <user_panel_sipin_trunk>`.
   * - PSTN trunk
     - A PSTN trunk assigned for inbound call delivery. See :doc:`../../voice/inbound-trunks/creating-a-new-pstn-trunk`.
   * - phone.systems™ trunk
     - A phone.systems™ trunk assigned for inbound call delivery.
   * - Trunk group
     - A trunk group assigned for inbound call delivery. See :doc:`../../voice/inbound-trunks/creating-a-new-trunk-group`.

.. _my_numbers_inbound_sms_trunk_values:

Inbound SMS trunk values
------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - SMS: none
     - No inbound SMS trunk is assigned.
   * - SMS to Email trunk
     - An SMS trunk that delivers incoming messages to email. See :doc:`../../sms/sms-trunks/create-sms-to-email-trunk`.
   * - HTTP IN trunk
     - An SMS trunk that delivers incoming messages to an HTTP endpoint. See :doc:`../../sms/sms-trunks/create-sms-http-trunk-in`.
   * - SMPP ESME trunk
     - An SMS trunk that delivers incoming messages to an ESME connection. See :ref:`SMPP ESME <sms_esme>`.
   * - SMPP SMSC trunk
     - An SMS trunk that delivers incoming messages to an SMSC connection. See :ref:`SMPP SMSC <sms_smsc>`.
   * - SMS trunk group
     - An SMS trunk group assigned for inbound SMS delivery. See :doc:`../../sms/sms-trunks/trunk-group`.

----

.. _my_numbers_reference_end_user_details:

End user details
================

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Identity
     - Configurable
     - The identity record assigned to the DID number for registration or regulated services. Displays **None** when no identity is assigned. See :ref:`Identities <user_panel_identities>`.
   * - Address
     - Configurable
     - The address record assigned to the DID number for registration or regulated services. Displays **None** when no address is assigned. See :ref:`Addresses <user_panel_addresses>`.
   * - :ref:`Address Verification <my_numbers_verification_ref_states>`
     - Read-only
     - The Address Verification reference associated with an End-user verification request. See :ref:`Verifications <user_panel_verifications>`.
   * - Regulatory area
     - Read-only
     - The regulatory area used to determine registration or service requirements. Requirements can vary by country, region, number type, and service.

.. _my_numbers_verification_ref_states:

Address verification states
---------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - State
     - Description
   * - |green-verification| Active
     - End-user details have been verified and approved.
   * - |yellow-verification| Pending
     - End-user details are under review.
   * - |red-verification| Rejected / Not assigned
     - The DID number requires verified End-user details to activate. Assign or update the End-user information and resubmit it for verification. See :doc:`how-to-guides/assign-end-user-details`.

----

Capacity
========

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Capacity limit
     - Editable
     - The maximum number of concurrent inbound calls allowed for the DID number. Displays **Not configured** when no specific capacity limit is set, or a number when a limit is configured. Updating this value limits calls for the DID number and does not increase total account capacity. See :doc:`how-to-guides/set-capacity-limits`.
   * - Channels included
     - Editable when available
     - The included channel mode for the DID number. Values are **2 included** for DID+2 mode and **0 included** for DID+0 mode. See :doc:`../capacity/index`.
   * - Dedicated channels
     - Editable
     - Flat-rate channels assigned directly to the DID number. Displays **None** when no additional dedicated channels are assigned, or a number when channels are assigned. See :doc:`../capacity/flat-rate-channels`.
   * - Capacity group
     - Editable
     - The shared or metered Capacity group assigned to the DID number. Displays **None** when no Capacity group is assigned, or the Capacity group name when assigned. See :doc:`../capacity/capacity-groups`.

----

Order details
=============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Order ref.
     - Read-only
     - The order reference number associated with the DID number.
   * - Assigned on (UTC)
     - Read-only
     - The date and time when the DID number was assigned to the account.

----

.. _my_numbers_billing_fields:

Billing
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Renew price
     - Read-only
     - The price charged to renew the DID number for the selected billing period.
   * - Expiry date (UTC)
     - Read-only
     - The date and time when the current DID number service period ends.
   * - :ref:`Billing period <my_numbers_billing_period_values>`
     - Read-only
     - The renewal interval for the DID number.
   * - :ref:`Billing cycles left <my_numbers_billing_cycles_left_values>`
     - Editable
     - The number of remaining billing cycles before automatic renewal stops.

.. _my_numbers_billing_period_values:

Billing period values
---------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Recurring monthly
     - The DID number renews for 1 month at a time.
   * - Recurring quarterly
     - The DID number renews for 3 months at a time.
   * - Recurring semi-annually
     - The DID number renews for 6 months at a time.
   * - Recurring annually
     - The DID number renews for 12 months at a time.
   * - Recurring bi-annually
     - The DID number renews for 24 months at a time.

.. _my_numbers_billing_cycles_left_values:

Billing cycles left values
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Empty
     - The DID number renews indefinitely until you remove the DID number or change the billing cycles left value.
   * - More than 0
     - The DID number renews automatically until the remaining billing cycles reach 0.
   * - 0
     - Automatic renewal is disabled. The DID number moves toward expiration when the current service period ends.

----

Services
========

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Service
     - Description
   * - |emergency-service| :ref:`Emergency Calling <my_numbers_emergency_calling_statuses>`
     - Emergency Calling service for the DID number. See :doc:`../../voice/emergency-calling/index`.
   * - |a2p-service| :ref:`Sender ID Verification <my_numbers_a2p_campaign_statuses>`
     - Sender ID Verification service for outbound A2P SMS. See :ref:`Sender ID Verifications <user_panel_sms_campaign>`.
   * - |cnam-service| :ref:`CNAM OUT <my_numbers_cnam_out_statuses>`
     - Outbound caller name service for the DID number. See :doc:`how-to-guides/configure-cnam-out`.

.. _my_numbers_emergency_calling_statuses:

Emergency Calling statuses
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Status
     - Available action
     - Description
   * - |emergency-gray| Not activated
     - `Contact sales <mailto:sales@didww.com>`_
     - Emergency Calling is not enabled for the account or DID number.
   * - |emergency-gray| Not configured
     - :doc:`Configure <../../voice/emergency-calling/create-emergency-calling-service>`
     - Emergency Calling is available, but no emergency calling configuration is assigned to the DID number.
   * - |emergency-yellow| New
     - :doc:`View <../../voice/emergency-calling/manage-emergency-calling-service>`
     - Emergency Calling configuration has been created and is waiting for review.
   * - |emergency-yellow| In process
     - :doc:`View <../../voice/emergency-calling/manage-emergency-calling-service>`
     - Emergency Calling configuration is under review.
   * - |emergency-service| Active
     - :doc:`View <../../voice/emergency-calling/manage-emergency-calling-service>`
     - Emergency Calling is configured and active for the DID number.
   * - |emergency-red| Changes required
     - :doc:`View <../../voice/emergency-calling/manage-emergency-calling-service>`
     - Emergency Calling configuration requires corrections before it can be approved.
   * - |emergency-red| Cancellation pending
     - :doc:`View <../../voice/emergency-calling/manage-emergency-calling-service>`
     - Emergency Calling cancellation has been requested and is pending closure.

.. _my_numbers_cnam_out_statuses:

CNAM OUT statuses
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Status
     - Available action
     - Description
   * - |cnam-gray| Not configured
     - :doc:`Configure <how-to-guides/configure-cnam-out>`
     - CNAM OUT is not configured for the DID number.
   * - |cnam-yellow| Pending
     - —
     - CNAM OUT configuration has been submitted and is pending review.
   * - |cnam-service| Active
     - :doc:`Remove or Edit <how-to-guides/configure-cnam-out>`
     - CNAM OUT is configured and active for the DID number.
   * - |cnam-red| Cancellation pending
     - —
     - A CNAM OUT removal request has been submitted and is pending closure.

.. _my_numbers_a2p_campaign_statuses:

Sender ID Verification statuses
-------------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Status
     - Available action
     - Description
   * - |a2p-gray| Not configured
     - :doc:`Configure <../../../sms/sender-id-verifications/how-to-guides/index>`
     - The DID number is not assigned to a Sender ID Verification.
   * - |a2p-yellow| New
     - :ref:`View <user_panel_sms_campaign>`
     - A Sender ID Verification assignment has been created and is waiting for review.
   * - |a2p-yellow| Pending
     - :ref:`View <user_panel_sms_campaign>`
     - The Sender ID Verification assignment is under review.
   * - |a2p-service| Active
     - :ref:`View <user_panel_sms_campaign>`
     - The Sender ID Verification is active for the DID number.
   * - |a2p-red| Changes required
     - :doc:`View <../../../sms/sender-id-verifications/how-to-guides/resubmit-sender-id-verification>`
     - The Sender ID Verification requires corrections before it can be approved.
   * - |a2p-red| Cancellation pending
     - :ref:`View <user_panel_sms_campaign>`
     - Sender ID Verification cancellation has been requested and is pending closure.

----

Related resources
=================

- :doc:`manage-phone-numbers` — Understand how DID number management works.
- :doc:`filters-reference` — Look up My Numbers filters.
- :doc:`batch-actions-reference` — Review batch actions available for selected DID numbers.
- :doc:`../capacity/index` — Manage dedicated, shared, metered, and hybrid capacity.
- :doc:`../../identities/index` — Manage identities, addresses, and verification records.

.. |cnam| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-cnam@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |inbound-calls| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-inbound-calls@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |local-cli| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-local-termination@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |fax| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-fax@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |sms-in| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-p-2-p-sms-in@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |sms-out| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-p-2-p-sms-out@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |a2p| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-ap-2-sms@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |emergency| image:: /img/new_user_panel/buy_numbers/inlines/feature-icon-emergency@3x.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |green-status| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/greencircle.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |yellow-status| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/yellowcircle.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |red-status| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/redcircle.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |green-verification| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/greenverification.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |yellow-verification| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/yellowverification.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |red-verification| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/redverification.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |gray-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/grayservice.png
   :class: inline-img no-shadow
   :width: 67px
   :height: 20px

.. |green-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/greenservice.png
   :class: inline-img no-shadow
   :width: 67px
   :height: 20px

.. |yellow-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/yellowservice.png
   :class: inline-img no-shadow
   :width: 67px
   :height: 20px

.. |red-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/redservice3.png
   :class: inline-img no-shadow
   :width: 67px
   :height: 20px

.. |emergency-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/emergencyicon.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |a2p-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/a2psmsicon.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |cnam-service| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/cnamicon.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |emergency-gray| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/emergencygray.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |emergency-yellow| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/emergencyyellow.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |emergency-red| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/emergencyred.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |a2p-gray| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/a2psmsgray.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |a2p-yellow| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/a2psmsyellow.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |a2p-red| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/a2psmsred.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |cnam-gray| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/cnamgray.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |cnam-yellow| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/cnamyellow.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. |cnam-red| image:: /img/new_user_panel/did_numbers/identities_and_services_overview/cnamred.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _phone_numbers_number_billing:

==============
Number billing
==============

Number billing describes how DID number charges are shown before purchase, in the **Shopping Cart**, at **Checkout**, and after the number is assigned to your account. It covers setup fee (NRC), monthly fee (MRC), billing periods, incoming rates, quantity, VAT, and how the selected channel option can affect the DID number price.

How numbers are billed
======================

DID numbers are recurring services. During purchase, DIDWW shows the one-time setup fee (NRC), monthly fee (MRC), selected billing period, selected channel option, and any incoming rates before checkout.

DID number charges use a flat-rate billing model. The exact amount shown for a DID number can depend on the country, number type, selected DID group, quantity, billing period, and selected **Channels Included** option.

.. mermaid::

   flowchart LR

      A["DID number purchased"] --> C["Initial order total<br/>amount"]

      C --> D["Setup fee (NRC)<br/>applied once"]
      C --> E["Monthly fee (MRC)<br/>charged for selected<br/>billing period"]

      E --> F["DID number assigned<br/>to your account"]

      F --> G["Billing period<br/>ends"]

      G --> H{"Billing cycles<br/>left?"}

      H -->|"More than 0<br/>or Unlimited"| I["Renewed for next<br/>billing period"]

      I --> E

      H -.->|"0"| J["DID number expires when<br/>current service period ends"]

      classDef root fill:#e0f2fe,color:#1f2d3d,stroke:#38bdf8,stroke-width:2px;
      classDef charge fill:#fef3c7,color:#1f2d3d,stroke:#facc15,stroke-width:2px;
      classDef decision fill:#fee2e2,color:#1f2d3d,stroke:#fb923c,stroke-width:2px;
      classDef endState fill:#e0f2fe,color:#1f2d3d,stroke:#38bdf8,stroke-width:2px;

      class A,F,G,I root;
      class C,D,E charge;
      class H decision;
      class J endState;

For the full purchase flow, see :doc:`buy-numbers/how-to-buy`. For post-purchase billing fields, see :ref:`My Numbers billing fields <my_numbers_billing_fields>`.

Setup fee and monthly fee
=========================

Setup fee (NRC) and monthly fee (MRC) are shown separately so the first order total and the recurring renewal cost are clear.

The setup fee (NRC) is a one-time flat-rate charge applied when the DID number is purchased.

The monthly fee (MRC) is the recurring flat-rate monthly price of the DID number.

Billing period
==============

The billing period is selected in the **Shopping Cart** before checkout. It determines the length of the service period and the amount charged for the recurring portion of the order.

Longer billing periods combine several months of the monthly fee into one order. For example, if a semi-annual billing period is selected, the recurring charge is calculated as:

``Monthly fee × 6 months``

The recurring amount is charged for the full selected billing period. For example, if a DID number has an MRC of USD 2.00 and a 3-month billing period is selected, the recurring portion of the order is USD 6.00 per DID number before taxes and any other charges.

The selected period is reflected in the **Shopping Cart** summary, where DIDWW shows the monthly fee amount for that billing period, setup fee, subtotal, VAT, and total for DID(s).

At **Checkout**, the **Order Summary** shows the final order total, account balance, balance after the transaction, VAT, and the amount that will be charged.

.. note::
   Prorated DID number billing is available through the API, but this feature is not enabled by default. To enable prorated billing for your DIDWW account, contact `customer.care@didww.com <mailto:customer.care@didww.com>`_. Prorated billing does not apply to DID numbers purchased via the User Panel. For API details, see :ref:`Create Order <orders_v34_create_order>`.

Channels included
=================

The **Channels Included** option can affect the DID number price shown during purchase.

Some DID numbers can be purchased with included voice channels. In **Buy Numbers** and the **Shopping Cart**, the available options can include **0 channels** or **2 channels**, depending on the selected DID group.

The **2 channels** option includes two included voice channels in the DID number service. This option usually has a higher monthly fee than **0 channels**.

The **0 channels** option does not include dedicated inbound voice channels in the DID number service. After purchase, inbound call delivery still depends on additional capacity configuration.

Changing the selected channel option can affect the monthly fee shown in the **Shopping Cart** and **Checkout**.

After purchase, supported DID numbers can be changed between supported included-channel modes by changing the next capacity mode. The change applies to the next billing cycle unless the DID number is renewed immediately for the selected period. See :ref:`Change next capacity mode <change_next_capacity_mode>`.

For capacity configuration and channel allocation details, see :doc:`capacity/index`.

Orders, payments, and invoices
==============================

Number billing is reflected in several billing records. These records are related, but they are not always created at the same moment.

Purchasing a new DID number creates an order. Renewals and billable service changes do not create an order — they are processed directly against the prepaid balance. If the balance is insufficient, funds must be added before the transaction can complete. Adding funds creates a payment record and, for purchases, a receipt. All billable activity is summarised in a monthly invoice issued on the first day of the following month.

For order history, see :ref:`Orders <billing_history_orders>`. For payment history, see :ref:`Payments <billing_history_payments>`. For invoices and receipts, see :ref:`Invoices and Receipts <billing_invoices_and_receipts>`. For adding funds manually, see :ref:`Top Up Using Instant Payment <billing_add_funds_instant_payment>`.

Incoming rates
==============

The **Incoming Rate** column shows incoming usage rates associated with the DID group.

If a DID number has inbound call billing, the rate is shown in this column before purchase. This can apply to number types such as Toll-free, Shared Cost, or UIFN.

If a DID number has inbound SMS billing, the inbound SMS rate is also shown before purchase.

Incoming rates are usage-based charges. They are charged only when the DID number receives inbound calls or inbound SMS traffic.

Current rates can vary depending on the country, number type, DID group, selected channel option, and supported services. To review current pricing outside the purchase flow, see :doc:`buy-numbers/download-pricelists`.

After purchase
==============

After a DID number is purchased, **My Numbers** shows billing information for the assigned DID number. This includes the renewal price, expiry date, billing period, and billing cycles left.

Billing cycles left is managed after purchase from **My Numbers**, not during checkout. For the related **My Numbers** fields, see :ref:`My Numbers billing fields <my_numbers_billing_fields>`.

For renewal and lifecycle tasks, see :doc:`my-numbers/how-to-guides/renew-number`, :doc:`my-numbers/how-to-guides/remove-number`, and :doc:`my-numbers/how-to-guides/restore-number`.

Related resources
=================

- :doc:`buy-numbers/index` — Search available DID numbers and review pricing before checkout.
- :doc:`buy-numbers/how-to-buy` — Purchase DID numbers from Buy Numbers.
- :doc:`buy-numbers/download-pricelists` — Download DIDWW pricelists.
- :ref:`My Numbers billing fields <my_numbers_billing_fields>` — Review post-purchase billing fields in My Numbers.
- :doc:`capacity/index` — Understand capacity configuration and channel allocation.
- :doc:`../billing/index` — Manage invoices, payments, account balance, and billing activity.


.. _user_panel_porting:

==============
Number porting
==============

Easily transfer your existing phone numbers with our reliable Phone Number Porting service. Use the self-service platform to manage all tasks, schedule port-ins, track progress in real time, and handle bulk transfers or multiple projects with a seamless transition and minimal downtime.

The porting process typically begins with a portability check, followed by creating a porting request, providing the required information and documents, and submitting the request for review. After approval, the losing carrier confirms a porting date and the numbers are transferred to DIDWW.

Porting timelines vary depending on the country, number type, regulatory requirements, and the losing carrier's review process.

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR

      check(("Check portability")) --> create((" &nbsp; Create porting &nbsp; <br>request<br>"))
      create --> fulfill((" &nbsp; Complete &nbsp; <br>&nbsp;&nbsp; requirements &nbsp; &nbsp;"))
      fulfill --> submit(("&nbsp; Submit request &nbsp;"))

      submit --> review(("&nbsp; Porting review &nbsp;"))

      review --> approved(("&nbsp; Approved for &nbsp; <br> &nbsp; porting &nbsp; "))
      approved --> foc(("&nbsp; &nbsp; &nbsp; FOC date  &nbsp; &nbsp; &nbsp; <br> &nbsp; &nbsp; confirmed &nbsp; &nbsp; "))
      foc --> completed["Porting completed"]

      review -.-> changes_required(("&nbsp; &nbsp; &nbsp; Changes &nbsp; &nbsp; &nbsp; <br> &nbsp; &nbsp; required &nbsp; &nbsp; "))
      changes_required --> resubmit(("&nbsp; &nbsp; &nbsp; Resubmit &nbsp; &nbsp; &nbsp; <br> &nbsp; &nbsp; request &nbsp; &nbsp;"))
      resubmit --> review

      review -.-> canceled(("&nbsp; &nbsp; &nbsp; Canceled &nbsp; &nbsp; &nbsp; "))
      canceled --> closed["Porting canceled"]

      check:::customerAction
      create:::customerAction
      fulfill:::customerAction
      submit:::customerAction
      resubmit:::customerAction

      review:::staffAction
      approved:::staffAction
      foc:::staffAction

      changes_required:::status
      canceled:::status
      closed:::status

      completed:::reviewComplete

      classDef customerAction stroke:#38bdf8,fill:#e0f2fe,stroke-width:2px,color:#1f2d3d
      classDef status stroke:#fb923c,fill:#fee2e2,stroke-width:2px,color:#1f2d3d
      classDef staffAction stroke:#facc15,fill:#fef3c7,stroke-width:2px,color:#1f2d3d
      classDef reviewComplete stroke:#2dd4bf,fill:#ccfbf1,stroke-width:2px,color:#1f2d3d

Key concepts
============

Number porting in DIDWW is organized around three related workspaces:

- **Portability checks** determine whether a phone number can be ported to DIDWW.
- **Porting requests** group one or more phone numbers into a single porting submission.
- **Porting numbers** track the status, milestones, and dates of individual phone numbers within a porting request.

A single porting request can contain multiple porting numbers, and individual numbers may progress through the porting process independently.

FOC dates
=========

FOC (Firm Order Commitment) is the confirmed date when a phone number is scheduled to be ported.

FOC dates are assigned to individual porting numbers and can differ between numbers within the same porting request.

For more information, see :doc:`porting-numbers/view-porting-date-foc`.

Porting workspaces
==================

.. grid:: 1 1 2 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Porting requests**
      :link: porting-requests/index
      :link-type: doc
      :text-align: left

      Create, review, resubmit, and manage porting requests.

   .. grid-item-card:: **Portability checks**
      :link: portability-checks/index
      :link-type: doc
      :text-align: left

      Check whether phone numbers can be ported before creating a request.

   .. grid-item-card:: **Porting numbers**
      :link: porting-numbers/index
      :link-type: doc
      :text-align: left

      Track individual numbers, statuses, milestones, and FOC dates.

   .. grid-item-card:: **Port-out requests**
      :link: port-out-requests/index
      :link-type: doc
      :text-align: left

      Review numbers being transferred away from DIDWW and manage request outcomes.

.. toctree::
   :maxdepth: 1
   :hidden:

   Porting requests <porting-requests/index.rst>
   Portability checks <portability-checks/index.rst>
   Porting numbers <porting-numbers/index.rst>
   Port-out requests <port-out-requests/index.rst>

.. _porting_requests_index:

================
Porting requests
================

Porting requests are used to submit existing phone numbers for transfer to DIDWW.

A porting request groups one or more phone numbers together with the information, documents, and end-user details required for carrier review and approval.

How porting requests work
=========================

After a porting request is submitted, DIDWW reviews the request details and verifies that all required information and documents are provided.

The porting request progresses through its own lifecycle, while each phone number within the request is tracked separately through the Porting Numbers workspace. Depending on the country, number type, and carrier requirements, additional information or corrected documents may be requested before the request can continue.

Before a request can be submitted, DIDWW may require end-user details, a completed Letter of Authorization (LOA), the latest invoice from the current carrier, the current carrier account number, or additional supporting documents. The exact requirements depend on the country and number type selected during request creation.

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR
       create(("&nbsp; Create New &nbsp; <br> &nbsp; Porting Request &nbsp; ")) --> pending["Pending"]
       pending --> start(("&nbsp; Start Porting &nbsp; <br>Request"))
       pending -.-> requires_changes(("Porting Request<br>Requires Changes")) & cancel(("&nbsp; Cancel Porting &nbsp; <br> &nbsp; Request &nbsp;"))
       start --> process1["In Process"]
       process1 --> foc(("Porting Date<br>Confirmed (FOC)"))
       process1 -.-> cancel
       foc --> process2["In Process"]
       process2 --> completed["Completed"]
       cancel --> cancellation_pending["Cancellation Pending"]
       cancellation_pending --> confirm_cancel(("&nbsp; Confirm &nbsp; <br> &nbsp; Cancellation &nbsp; "))
       confirm_cancel --> canceled["Canceled"]
       requires_changes --> changes_required["Changes Required"]
       changes_required --> cancel & resubmit(("Resubmit Porting<br>Request"))
       resubmit --> pending

        create:::customer
        pending:::status
        start:::staff
        requires_changes:::staff
        cancel:::customer
        process1:::status
        foc:::staff
        process2:::status
        completed:::completed
        cancellation_pending:::status
        confirm_cancel:::staff
        canceled:::canceled
        changes_required:::status
        resubmit:::customer
       classDef status fill:#f9e6dc,stroke:#ff5c1a,stroke-width:2px,color:#1f2d3d
       classDef staff fill:#fff4cf,stroke:#ffb000,stroke-width:2px,color:#1f2d3d
       classDef customer fill:#d7ecfb,stroke:#008ce3,stroke-width:2px,color:#1f2d3d
       classDef completed fill:#d0f0ec,stroke:#00a99d,stroke-width:2px,color:#1f2d3d
       classDef canceled fill:#f6d6df,stroke:#e83f6f,stroke-width:2px,color:#1f2d3d

How-to guides
=============

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Create porting request**
      :link: create-porting-request
      :link-type: doc
      :text-align: left

      Create a porting request, upload required documents, and submit it for processing.

   .. grid-item-card:: **Resubmit porting request**
      :link: resubmit-porting-request
      :link-type: doc
      :text-align: left

      Update required information and resubmit a request in **Changes Required** status.

   .. grid-item-card:: **Cancel porting request**
      :link: cancel-porting-request
      :link-type: doc
      :text-align: left

      Cancel an entire porting request before it is completed.

   .. grid-item-card:: **Cancel specific number porting**
      :link: cancel-specific-number-porting
      :link-type: doc
      :text-align: left

      Cancel selected numbers inside a porting request.

   .. grid-item-card:: **Resolve Action Required status**
      :link: resolve-action-required-status
      :link-type: doc
      :text-align: left

      Resubmit numbers that require additional information or corrected documents.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Porting requests reference**
      :link: porting-requests-reference
      :link-type: doc
      :text-align: left

      Look up request statuses, filters, and table fields.

   .. grid-item-card:: **Number porting**
      :link: ../index
      :link-type: doc
      :text-align: left

      Understand porting requirements, timing, and cancellation basics.

   .. grid-item-card:: **Porting numbers**
      :link: ../porting-numbers/index
      :link-type: doc
      :text-align: left

      Understand individual porting numbers inside requests.

.. toctree::
   :maxdepth: 1
   :hidden:

   Create porting request <create-porting-request.rst>
   Resubmit porting request <resubmit-porting-request.rst>
   Cancel porting request <cancel-porting-request.rst>
   Cancel specific number porting <cancel-specific-number-porting.rst>
   Resolve Action Required status <resolve-action-required-status.rst>
   Porting requests reference <porting-requests-reference.rst>


Create porting request
======================

Start a new porting request by adding numbers, checking the requirements, and entering the required details.

Before you begin
----------------

    - At least one number is required to start a porting request.
    - Verify the **regulatory requirements** for the selected country and number type. See the full list at `DIDWW Phone Number Porting <https://www.didww.com/services/phone-number-porting>`__.
    - A **Letter of Authorization (LOA)** template must be downloaded, completed, signed, and uploaded before submission.
    - A valid **Identity & Address** must be created or selected to meet compliance requirements. :ref:`Create New Identity & Address <create_new_identity>`.
    - Ensure you have the **current carrier account number, the latest invoice**, and any additional documents.

.. note:: To avoid service interruption when porting is completed, create a :ref:`Configuration Profile <configuration_profiles_profiles_create>` in advance.

Step 1: Create new porting request
----------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Go to the **Porting Requests** tab.
3. Click **Create New**.

.. figure:: https://doc.didww.com/_images/1create-new-porting-request.png
   :figclass: align-center
   :alt: Number Porting page with Create New button
   :width: 100%

   **Fig. 1** Number Porting page with Create New button

Step 2: Enter DIDs
------------------

On the **New Porting Request** page, the **DIDs** section appears for entering numbers. Enter the DID(s) you want to port in, and then click **Continue**.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item:: **1.** Enter numbers with country, area, and local codes:
      :class: left-align-block

      ::

            35310111111
            353 1 0111111
            353 (1) 0111111
            353 (1) 011-1111

   .. grid-item:: **2.** List numbers in a column:
      :class: left-align-block

      ::

            35310111111
            35310111112
            35310111113
            35310111114

   .. grid-item:: **3.** Enter number ranges:
      :class: left-align-block

      ::

            35310001110 - 35310001114
            35310001120 - 30
            35310001140 - 35310001160
            35310001170 - 90

.. figure:: https://doc.didww.com/_images/step2-enter-dids.png
   :figclass: align-center
   :alt: Entered DIDs in the porting request form
   :width: 100%

   **Fig. 2** Entered DIDs in the porting request form

Step 3: Check regulatory requirements
-------------------------------------

To complete a porting request, you must meet the regulatory requirements for the selected country and number type. These requirements ensure that the numbers can be legally transferred.

1. On the right side of the page, select the **Country** and **Number type**.
2. Review the listed porting requirements for identity, business, or address verification.
3. Download the **Letter of Authorization (LOA) template**.
4. Complete **all fields** in the LOA template before submitting.

.. figure:: https://doc.didww.com/_images/step3-porting-regulation-requirements.png
   :figclass: align-center
   :alt: Porting requirements displayed for United States local numbers
   :width: 100%

   **Fig. 3** Porting requirements displayed for United States local numbers

Step 4: Assign country for unrecognized NANP toll-free numbers
--------------------------------------------------------------

.. note::
    - **NANP (North American Numbering Plan)** covers phone numbers in the Canada and United States toll-free numbers starting with **800**, **888**, **877**, and similar codes.
    - If you are not porting these numbers, this step will not be visible and can be skipped.
    - To continue the porting request without these unrecognized NANP Toll-Free numbers, select **Cancel**.

When porting toll-free numbers in the United States or Canada (NANP Toll-Free), assign a country for each unrecognized number.

1. In the list of unrecognized NANP Toll-Free numbers, select the checkboxes for the numbers you want to assign.
2. From the **Country** dropdown, select the correct country, and then select **Assign DID(s)**.
3. After all numbers have been assigned a country, select **Continue** to proceed.

.. figure:: https://doc.didww.com/_images/nanp.png
   :figclass: align-center
   :alt: Numbers with unrecognized country requiring manual assignment
   :width: 100%

   **Fig. 4** Numbers with unrecognized country requiring manual assignment

Step 5: Review and confirm numbers
----------------------------------

After entering the numbers, review the list to confirm which ones will be submitted for porting.

.. important::

    - The system automatically saves your progress for the new porting request with the numbers you entered at this stage.
    - If you don’t finish the porting request, you can return later and continue where you left off by opening **Create New** and selecting **Continue Previous Session**.
    - Your work remains saved until you complete the porting request for the selected country and number type, or cancel it manually.

Review grouped numbers by country and type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Numbers are grouped into tabs by country, number type, and requirements, each showing the total count of numbers. You can switch between tabs to view the numbers in each group, then select, copy, or delete them from the porting request.

.. note::
    - A separate porting request is created for each tab.
    - To discard numbers while continuing with the porting request from other tabs, select the tab, click the **X** icon, and confirm the action.

.. figure:: https://doc.didww.com/_images/step5-1review-numbers.png
   :figclass: align-center
   :alt: Reviewing and managing selected numbers before submitting a porting request
   :width: 100%

   **Fig. 5** Reviewing and managing selected numbers before submitting a porting request

Select, copy, or delete numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The numbers accepted for the porting request are listed so you can verify that all numbers you want to port are included. Select all, single, or multiple numbers to copy them for your records or delete any you don’t want to include in the porting request.

.. tab-set::
    :class: my-tabs

    .. tab-item:: *Single selection*

     Click a number to select a single DID.
     The selected DID will be highlighted.

        .. figure:: https://doc.didww.com/_images/step5-2single-select.png
           :figclass: align-center
           :alt: step5-2single-select
           :width: 100%

           **Fig. 5** step5-2single-select

    .. tab-item:: *Multiple selection (keyboard)*

     Hold **Command** (macOS) or **Ctrl** (Windows/Linux) and click each number you want to select.
     Each selected DID will remain highlighted.

        .. figure:: https://doc.didww.com/_images/step5-2command-multi-select.png
           :figclass: align-center
           :alt: Multiple selection (keyboard)
           :width: 100%

           **Fig. 5** Multiple selection (keyboard) apple command

    .. tab-item:: *Multiple selection (mouse)*

     Click and hold the mouse button, then drag across the numbers you want to select.
     All numbers within the dragged area will be highlighted.

        .. figure:: https://doc.didww.com/_images/step5-2multiselect-mouse.gif
           :figclass: align-center
           :alt: Multiple selection (mouse)
           :width: 100%

           **Fig. 5** Multiple selection (mouse)

    .. tab-item:: *Select all*

     Click **Select All** at the bottom of the list to highlight every number in the group. When all numbers are selected, the button changes to **Unselect All** so you can clear the selection.

        .. figure:: https://doc.didww.com/_images/step5-2selectall.png
           :figclass: align-center
           :alt: Selecting all numbers at once
           :width: 100%

           **Fig. 5** Selecting all numbers at once

Continue to end user details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After reviewing the grouped numbers by country, number type, and regulatory requirements, select the correct tab and click **Continue** to proceed to the next step.

.. figure:: https://doc.didww.com/_images/step5-4-continue.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 5** Click continue to proceed to the end user details step

Step 6: Fill in end user details
--------------------------------

After reviewing and confirming the numbers, a form opens where you must enter a **Friendly Name** for the porting request, select the required **End User Registration Details**, upload the **Required Documents**, and provide any **Additional Details** for the porting request.

.. note:: Return to the number list at any time by selecting **Back to List** at the bottom left of the page.

End user registration details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. From the **Identity** dropdown, select an existing identity or create a new one.
2. The associated **Address** for that identity will appear in the dropdown. Select the address, or click **Create New** to add a new address for the chosen identity.

.. figure:: https://doc.didww.com/_images/step6-1reg-details.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 5** Click continue to proceed to the end user details step

Required documents
~~~~~~~~~~~~~~~~~~

1. Download the **Letter of Authorization (LOA)** template.
2. Complete the LOA fully, sign it, and upload the file.
3. Upload the **Latest Invoice** for the numbers being ported.

.. note::
     - All uploaded files are encrypted for security.
     - Leave **Comment** for additional notes on the porting request (optional).

.. figure:: https://doc.didww.com/_images/step6-2documents.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 5** Click continue to proceed to the end user details step

Additional details
~~~~~~~~~~~~~~~~~~

1. Choose the **Preferred port in date** or leave it as **Earliest available**.
2. Provide the **Current carrier account number** to match the request with the carrier’s records.
3. Assign a **Configuration profile** from the dropdown, or click **Create New** to add a new one.
4. Select the DID number channels included by choosing the **Capacity** option (DID+2 or DID+0 plan). See `DID+0 and DID+2 capacity modes <https://www.didww.com/services/capacity#:~:text=DID%2B0%20and%20DID%2B2%20virtual%20number%20modes>`__.

.. figure:: https://doc.didww.com/_images/step6-3additional-details.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 5** Click continue to proceed to the end user details step

Step 7: Submit the porting request
----------------------------------

Review all details and documents, then select **Submit** to create the porting request for the selected country and number type.

.. note:: If your request includes more than one country, submitting will create the porting request for the currently opened group.


.. _resubmit-porting-request:

=========================
Resubmit porting request
=========================

Before a porting request can be processed, it goes through a **verification stage** to confirm that end user details are correct.
While in **Pending** status, the request is under review. If the information is **incorrect**, **incomplete**, or **cannot be verified**, the request will move to **Changes Required** status.
In this state, staff will provide a reason and, if needed, additional comments to help you resolve the issue before resubmitting.

Before you begin
================

- The porting request must be in **Changes Required** status.
- Updated end user details, documents, or carrier information must be available.

Step 1: Filter requests by status
==================================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Request Status** filter.
3. Select **Changes Required** to display the relevant porting requests.

.. figure:: https://doc.didww.com/_images/resubmit-1-filter.png
   :alt: Filter porting requests by Changes Required status.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Filtering porting requests in **Changes Required** status.

Step 2: Open the porting request edit page
==========================================

Locate the porting request, then click the **Reference ID** or use the **Actions (...)** menu and select **Edit**.

.. figure:: https://doc.didww.com/_images/resubmit-2-open-edit-page.png
   :alt: Opening the porting request edit page.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Opening the porting request to review details and rejection reasons.

Step 3: Review verification details and reject reason(s)
========================================================

On the **Edit Porting Request** page, review the **Verification Details** and **Reject Reason(s)** sections. These sections show why the request requires changes.

.. figure:: https://doc.didww.com/_images/resubmit-3-view-details.png
   :alt: Verification details and rejection reasons.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Verification details and rejection reasons for the porting request.

Step 4: Update identity or address information
==============================================

Depending on the rejection reason, update the assigned identity, address, or both.

1. On the **Edit Porting Request** page, click **Actions > Edit assigned identity** or **Actions > Edit assigned address**.
2. Update the required fields.

.. figure:: https://doc.didww.com/_images/resbumit-4-edit-assigned-address.png
   :alt: Editing assigned address or identity.
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Editing assigned address or identity based on rejection reasons.

3. Upload any missing or corrected documents.
4. Click **Submit**.

.. figure:: https://doc.didww.com/_images/resubmit-5-edit-address2.png
   :alt: Uploading proof documents.
   :figclass: align-center
   :width: 100%

   **Fig. 5.** Uploading proof documents and submitting changes.

Step 5: Reassign end user details
=================================

After updating the required information, reassign the updated end user details before resubmitting the request.

1. On the **Edit Porting Request** page, click **Actions > Assign end user details**.

.. figure:: https://doc.didww.com/_images/resubmit-6-assign-end-user-details.png
   :alt: Assign end user details.
   :figclass: align-center
   :width: 100%

   **Fig. 6.** Assigning end user details with the updated information.

2. In the **Assign End User Details** pop-up window, select the updated **Identity** and **Address**.
3. Upload the required **LOA** document.
4. Enter the **current carrier account number**.
5. Click **Submit**.

.. figure:: https://doc.didww.com/_images/resubmit-7-assign-end-user-details.png
   :alt: Uploading LOA and submitting.
   :figclass: align-center
   :width: 100%

   **Fig. 7.** Uploading LOA and required documents before resubmitting.

After the end user details are assigned, the porting request returns to **Pending** status for re-verification.

.. figure:: https://doc.didww.com/_images/resubmit-8-success.png
   :alt: End user details successfully assigned.
   :figclass: align-center
   :width: 100%

   **Fig. 8.** Confirmation message after end user details are assigned.

Related resources
=================

- :doc:`porting-requests-reference` — Review porting request statuses.
- :doc:`../index` — Review porting requirements before resubmitting.


.. _cancel-porting-request:

======================
Cancel porting request
======================

Cancel a porting request when the whole request should stop before it is completed.

Before you begin
================

The porting request must be in **Pending**, **In Process**, or **Changes Required** status.

Step 1: Open the porting request
=================================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Porting Requests** tab.
3. Click **Actions (...)** next to the porting request you want to cancel.
4. Select **Cancel request**.

.. note::

   For porting requests in **In Process** status, cancellations are reviewed by DIDWW staff.

   - When cancellation is still possible, the request is approved and the numbers are canceled.
   - If it is too late, the request is rejected and porting continues.

.. figure:: https://doc.didww.com/_images/cancel-porting-request.png
   :alt: Cancel a porting request from the Actions menu.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Canceling a porting request from the **Actions** menu.

Related resources
=================

- :doc:`../index` — Understand request and number-level cancellation behavior.
- :doc:`porting-requests-reference` — Review porting request statuses.


.. _cancel-specific-numbers-inside-porting-request:

==============================
Cancel specific number porting
==============================

Cancel selected numbers inside a porting request without canceling the whole request.

Before you begin
================

Numbers are grouped by **Porting Number Status**. You can request cancellation for a status group, but numbers in **Canceled**, **Cancellation Pending**, or **Completed** status cannot be canceled.

Step 1: Open the porting request
=================================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Porting Requests** tab.
3. Click **Actions (...)** next to the porting request.
4. Select **Edit**.

.. figure:: https://doc.didww.com/_images/cancel-specific-numbers1.png
   :alt: Open the porting request edit page.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Opening the **Edit Porting Request** page.

Step 2: Select the number status group
=======================================

1. On the **Edit Porting Request** page, find the **Porting Number Status** group you want to cancel.
2. Expand the status group if needed.
3. Click **Actions > Request cancellation** for the selected group.

.. figure:: https://doc.didww.com/_images/cancel-specific-numbers2.png
   :alt: Select a porting number status group.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Selecting the group of numbers for cancellation.

Step 3: Confirm the cancellation request
=========================================

Review the numbers in the **Request Cancelation** pop-up window, then click **Confirm**.

.. note::

   For porting requests in **In Process** status, cancellations are reviewed by DIDWW staff.

   - When cancellation is still possible, the request is approved and the numbers are canceled.
   - If it is too late, the request is rejected and porting continues.

.. figure:: https://doc.didww.com/_images/cancel-specific-numbers3-confirmation.png
   :alt: Confirm cancellation of a number group.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Confirming cancellation for a number group.

Related resources
=================

- :doc:`../index` — Understand request and number-level cancellation behavior.
- :doc:`../porting-numbers/request-cancelation` — Request cancellation from the Porting Numbers tab.


.. _resolve-action-required-for-porting-request:

==============================
Resolve Action Required status
==============================

Resolve **Action Required** status when specific numbers inside a porting request need additional information or corrected documents.

Step 1: Open the porting request
=================================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Porting Requests** tab.
3. Click **Actions (...)** next to the porting request.
4. Select **Edit**.

.. figure:: https://doc.didww.com/_images/action-required1.png
   :alt: Numbers in Action Required status.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Numbers grouped under **Action Required** status.

Step 2: Resubmit the action required numbers
============================================

1. Expand the **Action Required** group.
2. Click **Actions > Resubmit**.

.. figure:: https://doc.didww.com/_images/action-required2.png
   :alt: Resubmit Action Required numbers.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Selecting **Resubmit** for numbers in **Action Required** status.

Step 3: Add comments and supporting documents
=============================================

1. In the **Resubmit Porting Request** pop-up window, add comments that clarify the update.
2. Upload any required documents.
3. Click **Submit**.

.. figure:: https://doc.didww.com/_images/action-required3.png
   :alt: Resubmit Porting Request pop-up window.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Adding comments and documents before resubmitting.

Related resources
=================

- :doc:`porting-requests-reference` — Review porting request statuses and actions.
- :doc:`../porting-numbers/porting-numbers-reference` — Review porting number statuses.


.. _porting_requests_reference:

==========================
Porting requests reference
==========================

Porting requests reference explains the filters, table fields, and status values shown in the Porting Requests tab.

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Filter condition
     - Description
   * - Name
     - Contains text input
     - Filters requests by the request name.
   * - :ref:`Request status <porting_requests_status_values>`
     - Searchable single-select filter
     - Filters requests by request workflow status.
   * - Reference
     - Contains text input
     - Filters requests by reference ID.
   * - :ref:`Porting number status <porting_requests_number_status_values>`
     - Searchable single-select filter
     - Filters requests by number-level porting status.
   * - Country
     - Searchable single-select filter
     - Filters requests by country.
   * - :ref:`Type <porting_requests_type_values>`
     - Searchable single-select filter
     - Filters requests by DID number type.

Table fields
============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Reference
     - Read-only
     - The porting request reference ID. Select the reference to open the request details page.
   * - Name
     - Read-only
     - The name assigned to the porting request.
   * - :ref:`Request status <porting_requests_status_values>`
     - Read-only
     - The current workflow status of the porting request.
   * - Country
     - Read-only
     - The country associated with the porting request.
   * - :ref:`Type <porting_requests_type_values>`
     - Read-only
     - The DID number type used by the request.
   * - Quantity
     - Read-only
     - The number of DID numbers included in the request.
   * - Porting Time
     - Read-only
     - The estimated porting time window for the request.
   * - Updated At (UTC)
     - Read-only
     - The last time the request was updated.
   * - Created At (UTC)
     - Read-only
     - The time when the request was created.

.. _porting_requests_status_values:

Request status values
=====================

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Pending
     - The porting request has been created and is waiting for DIDWW review.
   * - In process
     - The porting request is being processed by DIDWW.
   * - Changes required
     - The porting request needs updates before it can continue.
   * - Completed
     - The porting request has been completed.
   * - Cancellation pending
     - A cancellation request has been submitted and is waiting for review.
   * - Canceled
     - The porting request has been canceled.

.. _porting_requests_number_status_values:

Porting number status values
============================

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Pending
     - The number has been added to the request and is waiting for processing.
   * - Portable
     - The number can be ported.
   * - Not portable
     - The number cannot be ported.
   * - In process
     - The number is being processed for porting.
   * - Action required
     - The number needs additional information or corrected documents before it can continue.
   * - FOC date set
     - The porting date for the number has been set.
   * - Cancellation pending
     - A cancellation request for the number is waiting for review.
   * - Canceled
     - The number porting has been canceled.
   * - Completed
     - The number porting has been completed.

.. _porting_requests_type_values:

Type values
===========

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Local
     - Geographic numbers associated with a city or local area.
   * - Mobile
     - Numbers associated with mobile numbering.
   * - National
     - Numbers associated with national numbering.
   * - Shared Cost
     - Numbers where call costs may be shared according to local numbering rules.
   * - Toll-free
     - Numbers callers can reach without standard caller-paid charges where supported.
   * - Global / UIFN
     - Global or Universal International Freephone Number types.

Related resources
=================

- :doc:`index` — Understand porting requests.
- :doc:`create-porting-request` — Create a porting request.
- :doc:`resubmit-porting-request` — Resubmit a request in **Changes required** status.
- :doc:`cancel-porting-request` — Cancel a porting request.
- :doc:`cancel-specific-number-porting` — Cancel selected numbers inside a request.
- :doc:`resolve-action-required-status` — Resolve numbers in **Action Required** status.


.. _portability_checks_index:

==================
Portability checks
==================

Portability checks verify whether numbers can be ported to DIDWW before a porting request is created. Use them when you need to confirm portability first, then start a porting request from eligible numbers after review.

How portability checks work
===========================

A portability check starts with a list of numbers. DIDWW reviews the numbers and updates the check status. After review, numbers can be marked as portable, not portable, or not recognized.

When a reviewed portability check includes portable numbers, you can start the porting process directly from that check instead of entering the same numbers again in a new request.

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR
       A1(("Create New<br>Portability Check")) --> B1["New"]
       B1 --> C1(("&nbsp; &nbsp; Review &nbsp; &nbsp; <br> &nbsp; &nbsp; Started &nbsp; &nbsp; "))
       C1 --> D1["Under Review"]
       D1 --> E1(("&nbsp; Reviewed &nbsp;"))
       E1 --> F1["Reviewed"]
       F1 --> G1(("Start Port In<br>For Portable DIDs"))
       F1 -.-> I1(("Delete<br>Portability Check"))
       G1 --> H1(("Create New<br>Porting Request"))
       B1 -.-> I1

        A1:::customerAction
        B1:::status
        C1:::staffAction
        D1:::status
        E1:::staffAction
        F1:::reviewComplete
        G1:::customerAction
        I1:::customerAction
        H1:::customerAction
       classDef customerAction stroke:#38bdf8,fill:#e0f2fe,stroke-width:2px
       classDef status stroke:#fb923c,fill:#fee2e2,stroke-width:2px
       classDef staffAction stroke:#facc15,fill:#fef3c7,stroke-width:2px
       classDef reviewComplete stroke:#2dd4bf,fill:#ccfbf1,stroke-width:2px

How-to guides
=============

.. grid:: 1 1 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Create portability check**
      :link: create-portability-check
      :link-type: doc
      :text-align: left

      Enter numbers and create a portability check.

   .. grid-item-card:: **Start port in from portability check**
      :link: start-port-in-from-portability-check
      :link-type: doc
      :text-align: left

      Start a porting request from reviewed portable numbers.

   .. grid-item-card:: **Delete portability check**
      :link: delete-portability-check
      :link-type: doc
      :text-align: left

      Delete a portability check when it is no longer needed.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Portability check reference**
      :link: portability-check-reference
      :link-type: doc
      :text-align: left

      Look up portability check statuses, filters, and table fields.

   .. grid-item-card:: **Create porting request**
      :link: ../porting-requests/create-porting-request
      :link-type: doc
      :text-align: left

      Create a porting request manually.

   .. grid-item-card:: **Number porting**
      :link: ../index
      :link-type: doc
      :text-align: left

      Review porting requirements and timing before creating a request.

.. toctree::
   :maxdepth: 1
   :hidden:

   Create portability check <create-portability-check.rst>
   Start port in from portability check <start-port-in-from-portability-check.rst>
   Delete portability check <delete-portability-check.rst>
   Portability check reference <portability-check-reference.rst>


.. _create_new_portability_check:

========================
Create portability check
========================

Create a portability check to verify whether numbers can be ported to DIDWW before creating a porting request.

Create a new portability check
==============================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Portability Checks** tab.
3. Click **Create New**.

.. figure:: https://doc.didww.com/_images/create-new1.png
   :alt: Number Porting page with Create New button.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Creating a new portability check.

Step 2: Enter the friendly name and DIDs
=========================================

1. On the **New Portability Check** page, enter a **Friendly Name**.
2. In the **DIDs** section, enter the numbers you want to check for portability.
3. Click **Continue**.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item:: Enter numbers with country, area, and local codes:
      :class: left-align-block

      ::

            35310111111
            353 1 0111111
            353 (1) 0111111
            353 (1) 011-1111

   .. grid-item:: List numbers in a column:
      :class: left-align-block

      ::

            35310111111
            35310111112
            35310111113
            35310111114

   .. grid-item:: Enter number ranges:
      :class: left-align-block

      ::

            35310001110 - 35310001114
            35310001120 - 30
            35310001140 - 35310001160
            35310001170 - 90

.. figure:: https://doc.didww.com/_images/create-new2-copy.png
   :alt: Entered DIDs in the portability check form.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Entered DIDs in the portability check form.

Step 3: Review the created portability check
============================================

After submitting the portability check, you are redirected to the **Edit Portability Check** page. Numbers are grouped by country and number type, and the new portability check has **New** status.

.. figure:: https://doc.didww.com/_images/create-new3-completed.png
   :alt: Created portability check results.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Created portability check with summarized results.

Related resources
=================

- :doc:`portability-check-reference` — Review portability check statuses.
- :doc:`start-port-in-from-portability-check` — Start a porting request from a reviewed portability check.


.. _start_port_in_from_portability_check:

====================================
Start port in from portability check
====================================

Start a porting request from a reviewed portability check when it contains numbers with **Portable** status.

Before you begin
^^^^^^^^^^^^^^^^

    - Make sure the portability check has at least **one portable number** in **Reviewed** status to start a porting request.
    - Verify the **regulatory requirements** for the selected country and number type. See the full list at `DIDWW Phone Number Porting <https://www.didww.com/services/phone-number-porting>`__.
    - Create or select a valid **Identity & Address** for the chosen country and number type to meet portability compliance requirements. See :ref:`Create New Identity & Address <create_new_identity>`.
    - Ensure you have the **current carrier account number, the latest invoice**, and any additional documents.

.. note:: To avoid service interruption when porting is completed, create a **Configuration Profile** in advance.

Step 1: Open the reviewed portability check
===========================================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Portability Checks** tab.
3. Locate the reviewed portability check and click **Actions (...) > Edit**.

.. figure:: https://doc.didww.com/_images/start-port-in-reviewed1.png
   :alt: Open a reviewed portability check.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Opening a reviewed portability check to start port-in.

Step 2: Submit portable numbers to port in
==========================================

On the **Edit Portability Check** page, numbers are grouped by **Country** and **Number Type**.

1. Select the **Country** and **Number Type** if multiple countries were checked, the review the list of numbers with **Portable** status.
2. Click **Submit to Port In** to start the porting process for all portable numbers in the selected group.

.. important::

   Only numbers with **Portable** status from the same country and number type can be submitted for porting.

.. figure:: https://doc.didww.com/_images/start-port-in-reviewed2.png
   :alt: Submit portable numbers to port in.
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Starting the porting process for portable numbers.

Step 3: Fill in end user details
================================

After the portability check is reviewed and you submit the portable numbers to port in, a new **Porting Request** form opens.
Here, you need to provide **End User Registration Details**, upload the **Required Documents**, and fill in any **Additional Details** required to proceed with creating the porting request.

End user registration details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Enter a **Friendly Name** to identify the porting request once it's created.
2. From the **Identity** dropdown, select an existing identity or create a new one.
3. Choose the associated **Address** from the dropdown, or click **Create New** to add a new address for the selected identity.

.. figure:: https://doc.didww.com/_images/start-port-in-reviewed3-create-new-porting1.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 3.** Click continue to proceed to the end user details step

Required documents
~~~~~~~~~~~~~~~~~~

1. Download the **Letter of Authorization (LOA)** template.
2. Complete the LOA fully, sign it, and upload the file.
3. Upload the **Latest Invoice** for the numbers being ported.

.. note::
   - All uploaded files are encrypted for security.
   - Leave **Comment** for additional notes on the porting request (optional).

.. figure:: https://doc.didww.com/_images/start-port-in-reviewed3-create-new-porting2.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 4.** Click continue to proceed to the end user details step

Additional details
~~~~~~~~~~~~~~~~~~

1. Choose the **Preferred port in date** or leave it as **Earliest available**.
2. Provide the **Current carrier account number** to match the request with the carrier’s records.
3. Assign a **Configuration profile** from the dropdown, or click **Create New** to add a new one.
4. Select the DID number channels included by choosing the **Capacity** option (DID+2 or DID+0 plan). See `DID+0 and DID+2 capacity modes <https://www.didww.com/services/capacity#:~:text=DID%2B0%20and%20DID%2B2%20virtual%20number%20modes>`__.

.. figure:: https://doc.didww.com/_images/start-port-in-reviewed3-create-new-porting3.png
   :figclass: align-center
   :alt: Click continue to proceed to the end user details step
   :width: 100%

   **Fig. 5.** Click continue to proceed to the end user details step

Step 4: Submit the porting request
==================================

Review all details and documents, then select **Submit** to create the porting request for the selected numbers, country, and number type.

Related resources
=================

- :doc:`../porting-requests/create-porting-request` — Create a porting request manually.
- :doc:`../index` — Review porting requirements before starting a request.


.. _delete_portability_check:

========================
Delete portability check
========================

Delete a portability check when it is no longer needed.

Before you begin
================

- Portability checks cannot be deleted while they are in **Under Review** status.

Step 1: Delete the portability check
=====================================

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Portability Checks** tab.
3. Click **Actions (...)** next to the portability check you want to delete.
4. Select **Delete**.

.. figure:: https://doc.didww.com/_images/delete1.png
   :alt: Delete a portability check from the Actions menu.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Deleting a portability check from the **Actions** menu.

Related resources
=================

- :doc:`portability-check-reference` — Review portability check statuses and actions.


.. _portability_check_reference:

===========================
Portability check reference
===========================

Portability check reference explains the filters, table fields, and status values shown in the Portability Checks tab.

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Filter condition
     - Description
   * - Name
     - Contains text input
     - Filters portability checks by the check name.
   * - :ref:`Status <portability_check_status_values>`
     - Searchable single-select filter
     - Filters portability checks by review status.
   * - Reference
     - Contains text input
     - Filters portability checks by reference ID.

Table fields
============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Reference
     - Read-only
     - The portability check reference ID. Select the reference to open the check details page.
   * - Name
     - Read-only
     - The name assigned to the portability check.
   * - :ref:`Status <portability_check_status_values>`
     - Read-only
     - The current review status of the portability check.
   * - Portable
     - Read-only
     - The number of numbers in the portability check that are portable.
   * - Not Portable
     - Read-only
     - The number of numbers in the portability check that are not portable.
   * - Updated At (UTC)
     - Read-only
     - The last time the portability check was updated.
   * - Created At (UTC)
     - Read-only
     - The time when the portability check was created.

.. _portability_check_status_values:

Status values
=============

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - New
     - The portability check has been created but has not been reviewed yet.
   * - Under review
     - The portability check is being reviewed by DIDWW.
   * - Reviewed
     - The portability check has been completed and the portable and not portable counts have been determined.

Related resources
=================

- :doc:`index` — Understand portability checks.
- :doc:`create-portability-check` — Create a portability check.
- :doc:`start-port-in-from-portability-check` — Start porting from a portability check.
- :doc:`delete-portability-check` — Delete a portability check.


.. _porting_numbers_index:

===============
Porting numbers
===============

Porting numbers are the individual phone numbers being transferred through a porting request. Use this section to track number-level progress, review confirmed FOC dates, apply configuration profiles, and manage cancellation requests.

How porting numbers work
========================

Each porting number progresses independently through the porting process. As a result, different numbers within the same porting request can have different statuses, review outcomes, and completion dates.

The Porting Numbers workspace provides visibility into number-level activity throughout the porting lifecycle. For example, you can review porting statuses, monitor confirmed Firm Order Commitment (FOC) dates, apply configuration profiles, or request cancellation for selected numbers.

When a number receives a confirmed FOC date, the date is assigned to that specific number. This allows numbers within the same request to be scheduled and completed independently when required by the losing carrier or local porting process.

.. mermaid::

   ---
   config:
     layout: dagre
     theme: mc
   ---
   flowchart LR

       CreateNewPortingRequest(("Create New<br>Porting Request")) --> Pending["Pending"]

       Pending --> ReviewStarted(("Review Started"))
       Pending -.-> RequestCancellation_Bottom(("&nbsp; Request &nbsp; <br> &nbsp; Cancellation &nbsp;"))

       ReviewStarted -.-> NotPortable["Not Portable"]
       ReviewStarted --> Portable["Portable"]

       Portable --> StartPortingRequest(("&nbsp; Start Porting &nbsp; <br>Request"))
       Portable -.-> RequestCancellation_Bottom

       StartPortingRequest --> InProcess["In Process"]

       InProcess --> PortingDateConfirmedFOC(("Porting Date<br>Confirmed FOC"))
       InProcess -.-> AdditionalInformationRequired(("&nbsp; &nbsp; Additional &nbsp; &nbsp;<br>&nbsp;Information&nbsp;<br>&nbsp;Required&nbsp;"))
       InProcess -.-> RequestCancellation2_Bottom(("&nbsp; Request &nbsp; <br> &nbsp; Cancellation &nbsp;"))

       PortingDateConfirmedFOC --> FOCDateSet["FOC Date Set"]
       FOCDateSet --> Completed["Completed"]

       AdditionalInformationRequired --> ActionRequired["Action Required"]
       ActionRequired --> Resubmit(("&nbsp; &nbsp; Resubmit &nbsp; &nbsp; "))
       Resubmit --> InProcess

       RequestCancellation_Bottom --> Canceled_Bottom["Canceled"]

       RequestCancellation2_Bottom --> CancellationPending_Bottom["Cancellation Pending"]

       CancellationPending_Bottom --> Canceled_Bottom
       CancellationPending_Bottom -.-> CancellationRejected_Bottom["Cancellation<br>Rejected"]

       CreateNewPortingRequest:::blueCircle
       Pending:::orangeRect
       ReviewStarted:::yellowCircle
       RequestCancellation_Bottom:::blueCircle
       NotPortable:::orangeRect
       Portable:::orangeRect
       StartPortingRequest:::yellowCircle
       InProcess:::orangeRect
       PortingDateConfirmedFOC:::yellowCircle
       AdditionalInformationRequired:::yellowCircle
       RequestCancellation2_Bottom:::blueCircle
       FOCDateSet:::orangeRect
       Completed:::tealRect
       ActionRequired:::orangeRect
       Resubmit:::blueCircle
       Canceled_Bottom:::redRect
       CancellationPending_Bottom:::redRect
       CancellationRejected_Bottom:::grayRect

       classDef blueCircle fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
       classDef yellowCircle fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
       classDef orangeRect fill:#fed7aa,stroke:#ea580c,stroke-width:2px
       classDef grayRect fill:#e5e7eb,stroke:#6b7280,stroke-width:2px
       classDef tealRect fill:#a7f3d0,stroke:#059669,stroke-width:2px
       classDef redRect fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#1f2d3d

       style NotPortable fill:#e5e7eb,stroke:#6b7280,stroke-width:2px

How-to guides
=============

.. grid:: 1 1 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **View porting date (FOC)**
      :link: view-porting-date-foc
      :link-type: doc
      :text-align: left

      View the confirmed FOC date for scheduled porting numbers.

   .. grid-item-card:: **Apply configuration profile**
      :link: apply-configuration-profile
      :link-type: doc
      :text-align: left

      Assign configuration profiles to selected porting numbers.

   .. grid-item-card:: **Request cancelation**
      :link: request-cancelation
      :link-type: doc
      :text-align: left

      Request cancellation for selected porting numbers.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Porting numbers reference**
      :link: porting-numbers-reference
      :link-type: doc
      :text-align: left

      Look up porting number statuses, filters, and table fields.

   .. grid-item-card:: **Number porting**
      :link: ../index
      :link-type: doc
      :text-align: left

      Understand FOC timing and cancellation behavior.

   .. grid-item-card:: :octicon:`git-pull-request` **Resubmit Porting Numbers**
       :link: resolve-action-required-for-porting-request
       :link-type: ref
       :text-align: left

       Resubmit numbers when additional information is required to proceed with the porting process.

   .. grid-item-card:: **Porting requests**
      :link: ../porting-requests/index
      :link-type: doc
      :text-align: left

      Understand porting requests.

.. toctree::
   :maxdepth: 1
   :hidden:

   View porting date (FOC) <view-porting-date-foc.rst>
   Apply configuration profile <apply-configuration-profile.rst>
   Request cancelation <request-cancelation.rst>
   Porting numbers reference <porting-numbers-reference.rst>


.. _view_foc_date:

=======================
View porting date (FOC)
=======================

View the confirmed FOC date for numbers that have been scheduled for porting.

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Porting Numbers** tab.
3. Use the **Porting Number Status** filter and select **FOC Date Set**.
4. The Porting Number Status column will display the FOC Date Set status. Hover over this status to see a tooltip showing the scheduled porting date in the format yyyy-mm-dd.

.. figure:: https://doc.didww.com/_images/view-foc-date.png
   :alt: View Porting Date (FOC) in the DIDWW User Panel.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Viewing numbers with their assigned FOC date.

Related resources
=================

- :doc:`../index` — Understand how FOC dates are assigned.
- :doc:`porting-numbers-reference` — Review porting number statuses.


.. _apply_configuration_profile_to_porting_numbers:

===========================
Apply configuration profile
===========================

Apply a configuration profile to multiple porting numbers so routing and capacity settings are assigned when the numbers are successfully ported.

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Porting Numbers** tab to view all numbers currently included in porting requests.
3. Select the checkboxes next to the numbers you want to update.
4. Open the **Batch Actions** menu.
5. Select **Apply configuration profile**.
6. Select the configuration profile.

.. figure:: https://doc.didww.com/_images/apply-configuration-profile.png
   :alt: Apply a configuration profile to selected porting numbers.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Applying a configuration profile to multiple porting numbers.

Related resources
=================

- :doc:`../../configuration-profiles/index` — Manage configuration profiles.
- :doc:`porting-numbers-reference` — Review Porting Numbers actions.


.. _request_cancelation_for_porting_numbers:

===================
Request cancelation
===================

Request the cancellation of selected numbers within an active porting request using the **Batch Actions** menu. This option is useful if you no longer want to proceed with porting specific numbers, without canceling the entire porting request.

1. In the DIDWW User Panel, go to **Phone Numbers > Number Porting**.
2. Open the **Porting Numbers** tab.
3. Select the checkboxes next to the numbers you want to cancel.
4. Open the **Batch Actions** menu and select **Cancel**.

.. note::

   For porting requests in **In Process** status, cancellations are reviewed by DIDWW staff.

   - When cancellation is still possible, the request is approved and the numbers are canceled.
   - If it is too late, the request is rejected and porting continues.

.. figure:: https://doc.didww.com/_images/request-cancelation-batch.png
   :alt: Request cancellation for selected porting numbers.
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Requesting cancellation for selected porting numbers.

Related resources
=================

- :doc:`../index` — Understand request and number-level cancellation behavior.
- :doc:`../porting-requests/cancel-specific-number-porting` — Cancel selected numbers from the Porting Requests tab.


.. _porting_numbers_reference:

=========================
Porting numbers reference
=========================

Porting numbers reference explains the filters, table fields, and status values shown in the Porting Numbers tab.

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Filter condition
     - Description
   * - Number
     - Contains text input
     - Filters porting numbers by the DID number.
   * - Country
     - Searchable single-select filter
     - Filters porting numbers by country.
   * - :ref:`Type <porting_numbers_type_values>`
     - Searchable single-select filter
     - Filters porting numbers by DID number type.
   * - :ref:`Porting number status <porting_numbers_status_values>`
     - Searchable single-select filter
     - Filters porting numbers by porting workflow status.
   * - Porting request
     - Searchable single-select filter
     - Filters porting numbers by the associated porting request.

Table fields
============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Number
     - Read-only
     - The DID number being ported.
   * - Country
     - Read-only
     - The country associated with the DID number.
   * - :ref:`Type <porting_numbers_type_values>`
     - Read-only
     - The DID number type.
   * - :ref:`Porting number status <porting_numbers_status_values>`
     - Read-only
     - The current porting workflow status for the number.
   * - Porting request
     - Read-only
     - The associated porting request reference. Select the reference to open the request details page.
   * - Config. Profile
     - Read-only
     - The configuration profile associated with the DID number.
   * - Capacity
     - Read-only
     - The assigned capacity and included channel information for the DID number.
   * - Porting fee
     - Read-only
     - The porting fee for the DID number.
   * - Setup
     - Read-only
     - The setup fee for the DID number.
   * - Monthly
     - Read-only
     - The monthly fee for the DID number.
   * - FOC Date (UTC)
     - Read-only
     - The firm order commitment date for the number.
   * - Created At (UTC)
     - Read-only
     - The time when the porting number entry was created.
   * - Updated At (UTC)
     - Read-only
     - The last time the porting number entry was updated.

.. _porting_numbers_status_values:

Porting number status values
============================

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Pending
     - The porting request has not been reviewed by DIDWW.
   * - Portable
     - The number is portable and the porting process can continue.
   * - Not portable
     - The number cannot be ported in.
   * - In process
     - The porting request has been reviewed and is currently in process.
   * - Action required
     - The request needs to be updated before it can continue.
   * - FOC date set
     - The porting date has been set.
   * - Cancelation pending
     - The request to cancel the number porting is under review.
   * - Canceled
     - The number porting has been canceled.
   * - Completed
     - The number porting has been completed.

.. _porting_numbers_type_values:

Type values
===========

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Type
     - Description
   * - Local
     - A geographic DID number associated with a city or local area.
   * - Mobile
     - A DID number associated with mobile numbering.
   * - National
     - A DID number associated with national numbering.
   * - Shared Cost
     - A DID number type where call costs may be shared according to local numbering rules.
   * - Toll-free
     - A DID number type that allows callers to reach the number without standard caller-paid charges where supported.
   * - Global / UIFN
     - A global or Universal International Freephone Number type.

Related resources
=================

- :doc:`index` — Understand porting numbers.
- :doc:`view-porting-date-foc` — View FOC dates.
- :doc:`apply-configuration-profile` — Apply configuration profiles.
- :doc:`request-cancelation` — Request cancellation for selected numbers.
- :doc:`../porting-requests/porting-requests-reference` — Review porting request statuses and filters.


.. _number_porting_port_out_requests:

=================
Port-out requests
=================

Port-out requests are used when phone numbers are being transferred away from DIDWW to another provider. This section explains what a port-out request represents, how DIDWW reviews outgoing transfer requests, and where approval or rejection is handled.

How port-out requests work
==========================

When another provider submits a port-in request for numbers currently active in DIDWW, the request appears in DIDWW as a port-out request. Port-out requests are reviewed from the **Port Out Requests** workspace and opened in the **View Port Out Request** page, where you can review the request details and decide whether the request should be approved or rejected.

Port-out handling is separate from porting numbers into DIDWW. Port-out requests apply to numbers already assigned to your DIDWW account and focus on whether those numbers can be released to the gaining provider.

Port-out requests that require your decision appear in **Action required** status. From the request details page, you can approve the request or reject it with a reject reason. Approving the request confirms that the numbers can be ported out. Rejecting the request stops the port-out request and changes the request status to **Rejected**.

Approving the request in the User Panel does not bill the customer immediately. The customer is billed only after DIDWW staff approves the customer-approved port-out request and creates the port-out order.

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR
       request_received(("&nbsp; Port-out request &nbsp; <br>created")) --> action_required["Action required"]
       action_required --> view_request(("&nbsp; Open request &nbsp; <br>details"))
       action_required -.-> expired["Expired"]

       view_request --> approve_request(("Approve request"))
       view_request --> reject_request(("&nbsp; Reject request &nbsp;"))

       approve_request --> approved_by_customer["Approved"]
       approved_by_customer --> staff_review(("DIDWW staff<br>approves request"))
       staff_review --> order_created(("&nbsp; Port-out order &nbsp;<br>created"))
       order_created --> fee_billed(("&nbsp; &nbsp; Port-out fee &nbsp; &nbsp; <br> billed"))
       fee_billed --> ported_out["Ported out"]

       reject_request --> rejected["Rejected"]

       request_received:::yellowCircle
       action_required:::orangeRect
       view_request:::blueCircle
       approve_request:::blueCircle
       reject_request:::blueCircle
       approved_by_customer:::orangeRect
       staff_review:::yellowCircle
       order_created:::yellowCircle
       fee_billed:::yellowCircle
       ported_out:::tealRect
       rejected:::grayRect
       expired:::grayRect

       classDef blueCircle fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#1f2d3d
       classDef yellowCircle fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#1f2d3d
       classDef orangeRect fill:#fed7aa,stroke:#ea580c,stroke-width:2px,color:#1f2d3d
       classDef grayRect fill:#e5e7eb,stroke:#6b7280,stroke-width:2px,color:#1f2d3d
       classDef tealRect fill:#a7f3d0,stroke:#059669,stroke-width:2px,color:#1f2d3d

How-to guides
=============

.. grid:: 1 1 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Manage port-out requests**
      :link: manage-port-out-requests
      :link-type: doc
      :text-align: left

      Approve or reject port-out requests in the DIDWW User Panel.

Related resources
=================

.. grid:: 1 1 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Port-out requests reference**
      :link: port-out-requests-reference
      :link-type: doc
      :text-align: left

      Look up filters, table fields, and workflow statuses used in Port Out Requests.

   .. grid-item-card:: **Number porting**
      :link: ../index
      :link-type: doc
      :text-align: left

      Return to the Number Porting overview.

   .. grid-item-card:: **Porting requests**
      :link: ../porting-requests/index
      :link-type: doc
      :text-align: left

      Review port-in requests handled inside DIDWW.

.. toctree::
   :maxdepth: 1
   :hidden:

   Manage port-out requests <manage-port-out-requests.rst>
   Port-out requests reference <port-out-requests-reference.rst>


.. _manage_port_out_requests:

========================
Manage port-out requests
========================

Manage port-out requests in DIDWW by reviewing transfer requests and deciding whether they can be approved or must be rejected.

Approve port-out requests
=========================

Approve a request when the numbers can be released to the gaining carrier. Once ported-out, the action cannot be undone.

Before you begin
----------------

The port-out request must be in **Action required** status before it can be approved.

Step 1: Open the port-out request
---------------------------------

1. Go to the **Phone Numbers > Number Porting > Port Out Requests** tab.
2. Filter the Port Out Requests by **Action required** status. `Click here to apply the filter <https://my.didww.com/#/porting/port_out_requests?status=pending_confirmation>`_.
3. Find the request you want to review and click on the Port Out Request **reference ID** or **Actions > View details** to open the **View Port Out Request** window.

.. figure:: https://doc.didww.com/_images/port-out-requests-table.png
   :alt: Port Out Requests table with an Action required request.
   :figclass: align-center

   **Fig. 1.** Opening a port-out request from the Port Out Requests table.

Step 2: Review the request details
----------------------------------

1. On the **View Port Out Request** page review the **General** details.

.. figure:: https://doc.didww.com/_images/view-port-out-request-general.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 2.** View Port Out Request page.

2. Open the **Numbers** section and confirm that the expected numbers appear in the **Port Out Request**.

.. figure:: https://doc.didww.com/_images/view-port-out-request-numbers.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 3.** View Port Out Request page.

Step 3: Approve the request
---------------------------

1. Click **Approve** in the upper-right corner.

.. figure:: https://doc.didww.com/_images/view-port-out-request-approve.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 2.** View Port Out Request page.

2. In the **Approve Port Out Request** pop-up, review the confirmation message that explains the numbers will be released to the gaining carrier and the action cannot be undone.
3. Click **Submit**.

.. figure:: https://doc.didww.com/_images/port-out-request-approve.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 2.** View Port Out Request page.

After the request is approved, DIDWW shows a success message and the request status changes to **Approved**.

----

Reject port-out requests
========================

Reject a request when the numbers should not be released to the gaining carrier.

Before you begin
----------------

- The port-out request must be in **Action required** status before it can be rejected.

Step 1: Open the port-out request
---------------------------------

1. Go to the **Phone Numbers > Number Porting > Port Out Requests** tab.
2. Filter the Port Out Requests by **Action required** status. `Click here to apply the filter <https://my.didww.com/#/porting/port_out_requests?status=pending_confirmation>`_.
3. Find the request you want to review.
4. Click on the Port Out Request reference ID or **Actions > View details** to open the **View Port Out Request** window.

.. figure:: https://doc.didww.com/_images/port-out-requests-table.png
   :alt: Port Out Requests table with an Action required request.
   :figclass: align-center

   **Fig. 1.** Opening a port-out request from the Port Out Requests table.

Step 2: Review the request details
----------------------------------

1. On the **View Port Out Request** page review the **General** details.

.. figure:: https://doc.didww.com/_images/view-port-out-request-general.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 2.** View Port Out Request page.

2. Open the **Numbers** section and see which numbers are pending to be ported out.

.. figure:: https://doc.didww.com/_images/view-port-out-request-numbers.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 2.** View Port Out Request page.

Step 3: Reject the request
--------------------------

1. On the **View Port Out Request** page, click **Reject** in the upper-right corner.
2. Confirm that the reject action opens the **Reject Port Out Request** pop-up.

.. figure:: https://doc.didww.com/_images/view-port-out-request-reject.png
   :alt: View Port Out Request page with Reject and Approve actions.
   :figclass: align-center

   **Fig. 4.** View Port Out Request page with the reject action highlighted.

3. Select the reason for rejection from the **Reject reason** dropdown.
4. Click **Submit**.

.. figure:: https://doc.didww.com/_images/port-out-request-reject.png
   :alt: Reject Port Out Request dialog with a reject reason list.
   :figclass: align-center

   **Fig. 5.** Reject Port Out Request dialog.

After the request is rejected, the port-out request status changes to **Rejected**.

Related resources
=================

- :doc:`index` — Understand what port-out requests are and how they fit into Number Porting.
- :doc:`port-out-requests-reference` — Review Port Out Requests filters, table fields, and status values.


.. _port_out_requests_reference:

===========================
Port-out requests reference
===========================

Port-out requests reference explains the filters, table fields, and status values shown in the Port Out Requests tab.

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Filter condition
     - Description
   * - Reference
     - Contains text input
     - Filters port-out requests by reference ID.
   * - :ref:`Status <port_out_requests_status_values>`
     - Searchable single-select filter
     - Filters port-out requests by workflow status.

Table fields
============

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Field
     - Access
     - Description
   * - Reference
     - Read-only
     - The port-out request reference ID.
   * - Created At (UTC)
     - Read-only
     - The time when the port-out request was created.
   * - :ref:`Status <port_out_requests_status_values>`
     - Read-only
     - The current workflow status of the port-out request.
   * - Number Qty.
     - Read-only
     - The number of DID numbers included in the port-out request.
   * - Total Fee
     - Read-only
     - The total fee shown for the port-out request.
   * - Expires At (UTC)
     - Read-only
     - The time when the current approval or review window expires.

.. _port_out_requests_status_values:

Status values
=============

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Action required
     - The port-out request requires additional user action before DIDWW can continue processing it.
   * - Approved
     - The port-out request has been approved.
   * - Rejected
     - The port-out request has been rejected.
   * - Expired
     - The port-out request expired before it was completed.
   * - Ported out
     - The DID number has been transferred away from DIDWW.

Related resources
=================

- :doc:`index` — Understand port-out requests.
- :doc:`manage-port-out-requests` — Approve or reject port-out requests.


.. _user_panel_voice:

=====
Voice
=====

The **Voice** section provides a comprehensive overview of services for managing voice communications, including Inbound and Outbound Trunks, Emergency Calling and CNAM capabilities. These features enable seamless call routing, caller name delivery, and emergency call support.

----

.. grid:: 1 2 2 4
    :gutter: 4
    :padding: 0

    .. grid-item-card:: :octicon:`plug` **Inbound Trunks**
        :link: inbound-trunks/index
        :link-type: doc
        :text-align: left

        Set up and manage inbound SIP trunks to receive calls from the public telephone network.

    .. grid-item-card:: :octicon:`broadcast` **Outbound Trunks**
        :link: outbound-trunks/index
        :link-type: doc
        :text-align: left

        Configure outbound SIP trunks to make calls to global destinations with reliable connectivity.

    .. grid-item-card:: :octicon:`alert` **Emergency Calling**
        :link: emergency-calling/index
        :link-type: doc
        :text-align: left

        Enable and manage emergency calling services to ensure compliance and reliable access to emergency numbers.

    .. grid-item-card:: :octicon:`id-badge` **CNAM**
        :link: cnam/index
        :link-type: doc
        :text-align: left

        Configure Caller Name (CNAM) services to display proper identification for outbound calls.



.. _user_panel_cnam:

.. |br| raw:: html

    <br>

===========================
Caller Name Delivery (CNAM)
===========================

Caller Name Delivery (CNAM) is a telecommunication feature that provides the calling party's name information to the recipient. While CNAM services are predominantly used in the United States, their availability and implementation can vary across different countries and operators.

DIDWW offers CNAM services categorized into two types:

    - **CNAM IN**: Delivers the caller’s name to the customer’s endpoint specified in trunk settings.
    - **CNAM OUT**: Assigns a caller’s name to the DID number, which is displayed to the receiving party during the call, provided the destination operator performs a CNAM lookup.

.. note::

   The effectiveness of CNAM OUT depends on the destination operator. If the destination operator performs a CNAM lookup and retrieves the value from the CNAM database, the assigned caller name will be displayed to the called party.

Use the following options to manage your CNAM:

.. grid:: 1 2 2 2
   :gutter: 5

   .. grid-item-card:: :octicon:`eye` **Enable CNAM IN**
      :link: user_panel_cnam_in
      :link-type: ref
      :text-align: left

      Learn how to enable CNAM IN for your inbound SIP trunk.

   .. grid-item-card:: :octicon:`database` **Manage CNAM OUT**
      :link: ../../phone-numbers/my-numbers/how-to-guides/configure-cnam-out
      :link-type: doc
      :text-align: left

      Enable or remove CNAM OUT for supported DID numbers.

.. raw:: html

    <br>

----

.. _user_panel_cnam_in:

Enable CNAM IN
--------------

CNAM IN can be enabled for **SIP** and **phone.systems** trunk types and will be delivered to the customer’s endpoint.

**Steps to Enable CNAM IN:**

 1. In the menu sidebar, expand the **Voice** section and select **Inbound Trunks**.
 2. Locate the desired trunk (SIP Trunk or phone.systems) and click on the **three dots** |three-dots| under the **Actions** column, then select **Edit**.

    .. figure:: https://doc.didww.com/_images/step1_open_trunk_settings.png
      :figclass: align-center
      :alt: Enable CNAM For SIP Trunk

      **Fig. 1.** Enable CNAM For SIP Trunk

 3. Expand the **CNAM IN** section to view the CNAM settings.
 4. Turn on the **Inbound CNAM Lookup** toggle to enable CNAM IN for the trunk and click **Submit** to save your changes.

    .. figure:: https://doc.didww.com/_images/enable_siptrunk_cnam.png
      :figclass: align-center
      :alt: Enable CNAM For SIP Trunk

      **Fig. 1.** Enable CNAM For SIP Trunk

.. |three-dots| image:: /img/new_user_panel/cnam/three-dots.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. |br| raw:: html

  <br>

.. _user_panel_voice_out_emergency:

Configure Outbound Trunks for Emergency Calling
===============================================

Configure outbound trunks to route emergency calls through DIDWW using verified DID numbers with active Emergency Calling Services, even if Outbound Termination is not enabled on your account.

.. note:: By default, all existing outbound trunks are set to **Allow all available DID(s) for emergency calling** once the Emergency Calling Service has been activated.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Create Outbound Trunk for Emergency Calling**
      :link: create_outbound_trunk_and_allow_all_dids_for_emergency_calling
      :link-type: ref
      :text-align: left

      Set up an outbound trunk using all verified DIDs for emergency calling.

   .. grid-item-card:: **Edit Outbound Trunk and Allow Specific DIDs**
      :link: configure_existing_outbound_trunk_and_allow_specific_dids_for_emergency_calling
      :link-type: ref
      :text-align: left

      Update an outbound trunk to allow selected verified DIDs for emergency calling.

----

.. raw:: html

   <br>

.. _create_outbound_trunk_and_allow_all_dids_for_emergency_calling:

Create Outbound Trunk & Allow All DIDs For Emergency Calling
--------------------------------------------------------------

You can create an **Outbound Trunk** even if **Outbound Termination** is not enabled on your account.
Once at least one **Emergency Calling Service** is activated for a DID number with the **Emergency Calling** feature, outbound trunks become available for emergency call routing.

.. important::
   - If **Outbound Termination** is not activated, outbound trunks can be used **only for emergency calls** from verified DID source numbers.
   - Voice termination to local and international destinations will remain restricted until Outbound Termination is enabled.
   - To activate outbound termination services, see :ref:`Get Access to Local and International Voice Termination <user_panel_voice_out_get_access>`.

Step 1: Open the Outbound Trunks Section
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the DIDWW User Panel, go to **Voice → Outbound Trunks**.
2. If no outbound trunks exist, click **Create New**.

.. figure:: https://doc.didww.com/_images/create_new_outbound_trunk_1.png
   :alt: Creating a new outbound trunk
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Creating a new outbound trunk.

Step 2: Configure the Outbound Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Enter a **Friendly Name** for the trunk.
2. Choose an **Authentication Method** Credentials & IP-Based.
3. Add one or more **Allowed SIP IP addresses**.
4. Expand the **Emergency Calling** section. The toggle **Allow all available DID(s) for emergency calling** is enabled by default, automatically including all verified source numbers with active Emergency Calling Services.
5. Click **Create** to finalize and generate the outbound trunk.

.. note::
   To use a specific DID number as the caller ID for emergency calls, disable the **Allow all available DID(s) for emergency calling** toggle.
   Then, select the desired DID number from the **Available CLI(s)** list and click the **right arrow ( > )** to move it to the **Allowed CLI(s)** section.

.. figure:: https://doc.didww.com/_images/create_new_outbound_trunk_2.png
   :alt: Configuring a new outbound trunk for emergency calling
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Configuring the outbound trunk with emergency calling enabled.

.. _view_outbound_trunk_credentials_for_emergency_calling:

Step 3: View Outbound Trunk Credentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After creating the outbound trunk, you will be redirected back to the **Outbound Trunks** page.
A confirmation message will appear once the trunk is successfully created.

To view the trunk credentials click the **key icon** in the **Credentials** column.

.. figure:: https://doc.didww.com/_images/create_new_outbound_trunk_3.png
   :alt: Outbound Trunk Credentials window displaying Emergency Calling CLI(s) field and showing which DIDs are allowed to make emergency calls.
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Viewing outbound trunk credentials and allowed Emergency Calling CLI(s).

Step 4: Verify Emergency Calling CLI(s)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The **Outbound Trunk Credentials** pop-up will appear, displaying the username, password, and other connection details.

In the **Emergency Calling CLI(s)** field, you will see either a list of allowed numbers or **Any**, which indicates that all DIDs with active Emergency Calling Services can be used for emergency calls.

.. figure:: https://doc.didww.com/_images/create_new_outbound_trunk_4.png
   :alt: Viewing and verifying Emergency Calling CLI(s) for the outbound trunk.
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Viewing and verifying Emergency Calling CLI(s) for the outbound trunk.

----

.. raw:: html

   <br>

.. _configure_existing_outbound_trunk_and_allow_specific_dids_for_emergency_calling:

Edit Outbound Trunk & Allow Selected DIDs For Emergency Calling
--------------------------------------------------------------------------

You can edit an existing **Outbound Trunk** to specify which DID numbers are permitted for emergency calling.
By default, all verified DIDs with active Emergency Calling Services are allowed, but you can limit this to selected numbers if needed.

Step 1: Edit the Outbound Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the DIDWW User Panel, go to **Voice → Outbound Trunks**.
2. Click **Actions (⋯)** next to the trunk you want to update.
3. Select **Edit** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/edit_existing_1.png
   :alt: Editing an existing outbound trunk from the DIDWW User Panel
   :figclass: align-center

   **Fig. 5.** Opening the Edit page for an existing outbound trunk.

Step 2: Allow Selected DIDs for Emergency Calling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Expand the **Emergency Calling** section.
2. Disable the **Allow all available DID(s) for emergency calling** toggle to choose specific numbers manually.
3. Use the **filters** or search options in the **Available CLI(s)** section to find the desired DID number(s).
4. Select the DID(s) and click the **right arrow ( > )** button to move them to the **Allowed CLI(s)** section.
5. Click **Submit** to save your configuration.

.. important::
   The **Available CLI(s)** list displays only DID numbers with an **active Emergency Calling Service**.

.. figure:: https://doc.didww.com/_images/edit_existing_outbound.gif
   :alt: Selecting specific DIDs for emergency calling in the outbound trunk configuration
   :figclass: align-center

   **Fig. 6.** Selecting and allowing specific DIDs for emergency calling.


.. |br| raw:: html

   <br />

.. _create_emergency_service:

================================
Create Emergency Calling Service
================================

Set up an emergency calling service for supported DID numbers by creating a request to activate the service.
Once activated, use DIDWW SIP outbound trunking to place calls to supported emergency service numbers.

.. important:: Emergency Calling service is not enabled by default. To enable it on your account, contact `sales@didww.com <mailto:sales@didww.com>`_.

----

.. raw:: html

    <br>

Before You Begin
------------------

    - At least one active DID number with **Emergency Calling** feature is required.
    - A valid **Identity & Address** must be created to meet compliance requirements. :ref:`Create New Identity & Address <create_new_identity>`.

.. note::
   Your account balance will be charged once the **Emergency Calling** service is successfully verified.

----

.. raw:: html

    <br>

Step 1: Create New Emergency Calling Service
--------------------------------------------

1. In the DIDWW User Panel, navigate to **Voice > Emergency Calling**.
2. Click **Create New** to start creating a new Emergency Calling service.

.. figure:: https://doc.didww.com/_images/emergency0.png
   :figclass: align-center
   :alt: Starting the creation of an Emergency Calling service

   **Fig. 1.** Creating a new Emergency Calling service.

.. raw:: html

    <br>

Step 2: Provide Service Details
-------------------------------

The Create Emergency Calling Service form will open, starting with the **Service Details** step, where you enter the basic information for your emergency calling request.

1. Enter a **Friendly Name** for your emergency calling request (e.g., ``Emergency Calling Service``).
2. Select the **Country** of the DID numbers that will be used as source numbers for making emergency calls.
3. Choose the **Number Type** of the DID numbers that will be enabled for emergency calling.
4. Click **Next** to continue to the **Verification Details** step.

.. note:: After entering the details, a summary section displays the estimated verification time, setup fee, and monthly fee per number.

.. figure:: https://doc.didww.com/_images/emergency1.png
   :figclass: align-center
   :alt: Entering service details

   **Fig. 2.** Entering service details.

.. raw:: html

    <br>

Step 3: Provide Verification Details
------------------------------------

Review the verification requirements and assign an **Identity** and **Address** for the emergency calling service.
These details must comply with local emergency service regulations and correspond to the **Country** and **Number Type** selected in the previous step.

1. From the **Identity** dropdown, select an existing identity. If no identity is available, click **Create New** to add a new one.
2. Once the identity is selected, choose the corresponding **Address** from the dropdown list. You can also click **Create New** to add a new address for the chosen identity.
3. Click **Next** to continue to the **Source Numbers** step.

.. note::
   - The selected identity and address will be assigned to the phone numbers used for emergency calling.
   - If the **Identity** does not meet the verification requirements, it cannot be selected. A tooltip will appear explaining why the identity is not eligible.

.. figure:: https://doc.didww.com/_images/emergency2.png
   :figclass: align-center
   :alt: Selecting verification identity and address details

   **Fig. 3.** Selecting the identity and address for emergency service verification.

.. raw:: html

    <br>

Step 4: Select Source Numbers (DIDs)
------------------------------------

Select the DID numbers that will be enabled for emergency calling.
Only numbers that match the selected **Identity**, **Country**, and **Number Type**, and support emergency calling, will be shown.

1. (Optional) Use the **DID Number** or **Description** filters to search for available numbers.
2. In the **Available Source Numbers** table, select the DID numbers you want to include using the checkboxes.
3. Review your selections, then click **Next** to continue to the **Summary** step.

.. note::
   - Selected DID numbers are added to the **Allowed source addresses** panel, where they are displayed as chips and can be removed if needed.
   - DID numbers linked to a different verified identity than the one selected in the **Verification Details** step (for example, used for **End User Registration**, **A2P SMS Campaigns**, or **CNAM**) will not appear in the available source numbers list. To include these numbers, select the same identity used for their verification.
   - If there are **more than 200** available source addresses, the table is paginated with 200 records per page.

.. figure:: https://doc.didww.com/_images/emergency3-gif.gif
   :figclass: align-center
   :alt: Selecting DID numbers for emergency calling

   **Fig. 4.** Selecting DID numbers for the Emergency Calling service.

.. raw:: html

    <br>

Step 5: Review and Submit
-------------------------------------

Review all information before submitting your emergency calling service request.
The summary displays your **Service Details**, **Verification Details**, selected **Source Numbers**, and the total **Setup** and **Recurring Fees**.

1. Confirm that the **Identity**, **Address**, and **Source Numbers** are correct.
2. Review the estimated verification time and charges under the **Summary** section.
3. Click **Submit** to send the emergency calling service request for verification.

.. important::
   Your account balance will be charged automatically once the emergency calling service is successfully verified.

.. figure:: https://doc.didww.com/_images/emergency4.png
   :figclass: align-center
   :alt: Reviewing and submitting the Emergency Calling service request.

   **Fig. 5.** Reviewing and submitting the Emergency Calling service request.

Step 6: Confirm Emergency Calling Service Agreement
---------------------------------------------------

After clicking **Submit** on the summary step, a confirmation window appears with important information about the **VoIP Emergency Calling Service**.
It is required to review and acknowledge the terms before the request can be created.

To proceed, review the information carefully, select the checkbox to confirm your acknowledgment, and click **Agree & Complete Order**.

.. important::
   By acknowledging these terms, you confirm that you have read and understood the information provided about the Emergency Calling Service. |br|
   You hereby accept responsibility to ensure that the end users of this service are aware of the stated information. |br|
   Once you click **Agree & Complete Order**, you confirm your agreement and authorize the creation of the Emergency Calling Service request for the selected numbers.

.. |br| raw:: html

   <br />

=================
Emergency Calling
=================

Configure Emergency Calling with DIDWW Phone Numbers.
Manage emergency calling settings and registrations for your phone numbers.
Stay compliant with regional regulations and guarantee that every call to emergency services reaches the correct Public Safety Answering Point (PSAP).

.. grid:: 1 2 2 3
   :gutter: 4

   .. grid-item::
      :class: left-align-block

      - Activate emergency calling for supported DID numbers.
      - Automatically validate caller location and address details.
      - Ensure compliance with regional emergency service regulations.

   .. grid-item::
      :class: left-align-block

      - Manage emergency registrations for multiple numbers.
      - Track verification status and registration progress.
      - Maintain secure, encrypted data for all registered services.

.. note::

   Emergency services are subject to regulatory and operational requirements that vary by country and are generally available only for business customers.

   As the eligibility criteria, onboarding process, and documentation requirements may differ depending on the country of interest, please contact our Sales team with the specific country you are interested in. They will be able to provide detailed information regarding availability, requirements, and the activation process.

----

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Emergency Calling**
      :link: create-emergency-calling-service
      :link-type: doc
      :text-align: left

      Register and enable emergency calling services for your account.

   .. grid-item-card:: :octicon:`gear` **Manage Emergency Calling**
      :link: manage-emergency-calling-service
      :link-type: doc
      :text-align: left

      Manage your Emergency Calling Service requests, update verification details, or modify assigned source numbers.

   .. grid-item-card:: :octicon:`gear` **Configure Outbound Trunks for Emergency Calling**
      :link: configure-emergency-calling-for-outbound-trunks
      :link-type: doc
      :text-align: left

      Set up and activate emergency calling for your outbound trunks.

   .. grid-item-card:: :octicon:`eye` **View Supported Emergency Calling Numbers**
      :link: supported-emergency-numbers
      :link-type: doc
      :text-align: left

      View the list of supported emergency numbers per country and service.

.. toctree::
  :maxdepth: 1
  :hidden:

   Create Emergency Calling <create-emergency-calling-service.rst>
   Manage Emergency Calling <manage-emergency-calling-service.rst>
   Configure Outbound Trunks for Emergency Calling <configure-emergency-calling-for-outbound-trunks.rst>
   Emergency Dialing Numbers <supported-emergency-numbers.rst>



.. |br| raw:: html

   <br />

.. _manage_emergency_service:

================================
Manage Emergency Calling Service
================================

When you create an Emergency Calling Service request, it goes through several stages from creation and verification to activation.
During this process, the submitted information and selected DID numbers are reviewed to ensure compliance with local emergency service requirements.

You can manage the service by resubmitting requests, removing source numbers, or canceling the Emergency Calling Service when needed.

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`location` **Change Emergency Calling Address**
      :link: change-emergency-calling-address
      :link-type: ref
      :text-align: left

      Submit a request to change the emergency address for an active Emergency Calling Service.

   .. grid-item-card:: :octicon:`sync` **Resubmit Emergency Calling Request**
      :link: resubmit-emergency-calling-request
      :link-type: ref
      :text-align: left

      Update the identity or address information and resubmit the request after changes are required.

   .. grid-item-card:: :octicon:`trash` **Remove Source Numbers from Emergency Calling**
      :link: remove-numbers-from-emergency-calling-request
      :link-type: ref
      :text-align: left

      Remove individual DID numbers from an existing Emergency Calling Service request without canceling the entire request.

   .. grid-item-card:: :octicon:`circle-slash` **Cancel Emergency Calling Service**
      :link: cancel-emergency-calling-request
      :link-type: ref
      :text-align: left

      Cancel a pending or active Emergency Calling Service request when it’s no longer needed.

----

.. raw:: html

   <br>

Emergency Calling Service Flow
------------------------------

This flow illustrates how an Emergency Calling Service request progresses through its stages until activation. The process begins with creating a new request and continues through review, confirmation, and approval.
The request can be canceled at any time while it is in **New**, **Changes Required**, or **Active** status.

.. figure:: https://doc.didww.com/_images/emergency_status_flow.png
    :alt: Emergency Calling Service Flow
    :class: align-center no-shadow wide-figure

Emergency Calling Service Statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Status**
     - **Description**
   * - New
     - Emergency Calling service verification has not been started yet.
   * - In Process
     - Emergency Calling service verification is in process.
   * - Changes Required
     - Emergency Calling service verification needs to be resubmitted.
   * - Active
     - Emergency Calling service is active.
   * - Pending Update
     - Emergency Calling service is active, but a request to change the emergency address is being processed.
   * - Canceled
     - Emergency Calling service has been canceled.

----

.. _change-emergency-calling-address:

Change Emergency Calling Address
--------------------------------

When an Emergency Calling Service is **Active**, you can submit a request to change the assigned emergency address.
Emergency calling remains active under the currently verified address while the new address is being verified.

After submission, the service enters **Pending Update** status until verification is completed.

.. important::
   - Address verification may take **up to 5 business days**.
   - Emergency calling remains active under the **currently verified address** until the update is verified.
   - While the service is in **Pending Update** status, no additional address change requests can be submitted.

Step 1. Locate the Emergency Calling Service and open Change Address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the DIDWW User Panel, go to **Voice → Emergency Calling**.
2. Locate an Emergency Calling Service with **Active** status.
3. Click **Actions (⋯)** and select **Change address**.

.. note::
   When the Emergency Calling Service is in **Pending Update** status, the **Change address** option is disabled.

.. figure:: https://doc.didww.com/_images/change_address1.png
   :alt: Change address option in Actions menu for active emergency calling service
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Change address option available for an Active Emergency Calling Service.

Step 2. Select a New Address and Submit the Request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Select a **new address** from the **Address** dropdown list.
2. Click **Submit**.

Once the new address is verified, the Emergency Calling Service status changes back to **Active**, and the new address is applied automatically.

.. note::
   If the address verification is rejected, the Emergency Calling Service status changes back to **Active** and continues using the previously verified address.

.. figure:: https://doc.didww.com/_images/change_address2.png
   :alt: Change emergency calling address window
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Selecting a new address for the Emergency Calling Service.

----

.. raw:: html

   <br>

.. _resubmit-emergency-calling-request:

Resubmit Emergency Calling Request
-----------------------------------

Before an Emergency Calling Service request can be activated, it must pass a **verification stage** to ensure that all submitted details are correct and compliant.
You can resubmit a request while it is in **New** or **Changes Required** status, if some details are **incorrect**, **incomplete**, or **did not pass verification**.
When the Emergency Calling Service request is in **Changes Required** status, a reason and any additional comments will be displayed to help you update and resubmit the request.

.. raw:: html

   <br>

Step 1. Filter Emergency Requests by Status: Changes Required (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the DIDWW User Panel, go to **Voice → Emergency Calling**.
2. Open the **Status** filter.
3. Select the **Changes Required** status to display the relevant Emergency Calling requests.

.. figure:: https://doc.didww.com/_images/resubmit_1_filter_numbers.png
   :alt: Filter emergency calling requests by status Changes Required
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Filtering Emergency Calling requests in Changes Required status.

Step 2. Open Emergency Calling Edit Page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Locate the Emergency Calling request, then click the **Reference ID** or use the **Actions (⋯)** menu and select **Edit**.

.. figure:: https://doc.didww.com/_images/resubmit_2_edit.png
   :alt: Opening the emergency calling request edit page
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Opening the emergency calling request to review details and rejection reasons.

Step 3. View Verification Details and Reject Reason(s)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On the **Edit Emergency Calling** request page, review the **Verification Details** and **Reject Reason(s)** sections.
This will show exactly why the request requires changes (for example, a missing proof of address).

.. figure:: https://doc.didww.com/_images/resubmit_3_reject_reasons.png
   :alt: View emergency calling verification details and rejection reasons
   :figclass: align-center
   :width: 100%

   **Fig. 5.** Emergency calling verification details and rejection reasons for the porting request.

Step 4. Update Verification Details
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. important::
   1. If the rejection reason requires changing the **Identity** information, or if any identity or address fields are locked from editing, it is recommended to :ref:`cancel the request <cancel-emergency-calling-request>` and :ref:`create a new Emergency Calling Service request <create_emergency_service>` instead of resubmitting it, unless the rejection is related to document updates.
   2. If the **Address** information is missing or incorrect (except for document updates), create a new address for the identity and select it when resubmitting the request.

Depending on the **rejection reason(s)**, you may be required to update either the **Identity** details, the **Address** details, or both.
For example, this may happen if the provided information is outdated, incomplete, or does not match the verification documents.

1. In the **Verification Details** block, click the **Identity** or **Address** names to open the corresponding edit page.
2. Update the required fields — for example, upload a new document or add missing information.

Step 5. Resubmit Emergency Service Verification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After reviewing the rejection reasons and updating the required **Identity** or **Address** information assigned to the Emergency Calling Service request, you can resubmit the same request for verification.

.. note::
   If you are unable to update the **Identity** information based on the rejection reason, or if the assigned **Address** cannot be modified, create a new address or :ref:`cancel the emergency request <cancel-emergency-calling-request>` instead.

1. To resubmit emergency calling service request, click **Actions → Resubmit**.

.. figure:: https://doc.didww.com/_images/resubmit_5_1.png
   :alt: Resubmitting the Emergency Calling Service request
   :figclass: align-center
   :width: 100%

   **Fig. 6.** Resubmitting the Emergency Calling Service request with updated verification details.

A **Resubmit Emergency Service Verification** pop-up window will appear, showing a banner with the rejection reason and any additional comments from staff (if provided).

.. note::
   The **Identity** field in the **Resubmit Emergency Service Verification** window cannot be changed or reselected.

2. Select the updated or new **Address** from the dropdown menu (or click **Create New Address** if the existing fields are disabled when updating the required address information).
3. Click **Submit** to resubmit your Emergency Calling Service request for verification.

.. figure:: https://doc.didww.com/_images/resubmit_5_2.png
   :alt: Resubmitting Emergency Calling Service verification
   :figclass: align-center
   :width: 100%

   **Fig. 7.** Resubmitting the Emergency Calling Service request after updating verification details.

Step 5. Emergency Calling Service Request Returns to In Process Status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After successfully resubmitting the request, the Emergency Calling Service status changes to **In Process**.
This indicates that the verification has been resubmitted.

.. figure:: https://doc.didww.com/_images/resubmit_6.png
   :alt: End user details successfully assigned
   :figclass: align-center
   :width: 100%

   **Fig. 8.** Confirmation message indicating successful reassignment of end user details.

----

.. raw:: html

   <br>

.. _remove-numbers-from-emergency-calling-request:

Remove Source Numbers from Emergency Calling
--------------------------------------------

You can remove verified source numbers from an existing Emergency Calling Service request at any time if they are no longer needed.

.. important::
   - When the Emergency Calling Service is **Active**, removing a number instantly disables its ability to place calls to supported emergency numbers.
   - If a number is removed while the request is in **New**, **Changes Required**, or **In Process** status, it will not be activated for emergency calling.

.. raw:: html

   <br>

Step 1. Open Emergency Calling Service Edit Page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the DIDWW User Panel, go to **Voice → Emergency Calling**.
2. Click the **Actions (⋯)** button next to the Emergency Calling Service request.
3. Select **Edit** from the dropdown menu.

.. note::
   You can also click the **Name / Ref. ID** of the Emergency Calling Service request to open the edit page directly.

.. figure:: https://doc.didww.com/_images/remove_source_numbers_1_edit.png
   :alt: Open Emergency Calling Service Edit Page
   :figclass: align-center
   :width: 100%

   **Fig. 9.** Opening the Emergency Calling Service Edit Page.

Step 2. Select Verified Source Numbers to Remove
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the **Verified Source Numbers** section, select the DID number you want to remove.
2. Once the number is selected, click **Remove**.

.. note::
   The **Remove** button is disabled until at least one number is selected.
   After selecting a number, the button becomes active and can be clicked to proceed with removal.

.. figure:: https://doc.didww.com/_images/remove_source_numbers_2.png
   :alt: Selecting verified source numbers to remove
   :figclass: align-center
   :width: 100%

   **Fig. 10.** Selecting verified source numbers for removal.

Step 3. Confirm Number Removal
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A **Remove Source Number(s)** confirmation window will appear.
Review the message, then click **Remove** to confirm.

.. note::
   The selected source number(s) will be removed immediately, and the emergency service for those numbers will be canceled.
   No refund will be issued for the remaining service time.

.. figure:: https://doc.didww.com/_images/remove_source_numbers_3.png
   :alt: Confirming removal of verified source numbers
   :figclass: align-center
   :width: 100%

   **Fig. 11.** Confirming the removal of verified source numbers.

----

.. raw:: html

   <br>

.. _cancel-emergency-calling-request:

Cancel Emergency Calling Service
--------------------------------

You can cancel an Emergency Calling Service request while it is in **New**, **Changes Required**, or **Active** status.
Canceling the request immediately deactivates the verified emergency source numbers assigned to the service, preventing them from making emergency calls.
The Emergency Calling Service will be removed right away and will not renew in the next billing cycle.

1. In the DIDWW User Panel, go to **Voice → Emergency Calling**.
2. Click **Actions (⋯)** next to the Emergency Calling Service request you want to cancel.
3. Select **Cancel Emergency Calling** from the dropdown menu.

.. note::
   Emergency Calling Service requests that are currently **In Process** cannot be canceled. |br|
   However, you can :ref:`remove individual verified source numbers <remove-numbers-from-emergency-calling-request>` at any time, regardless of status, if updates are needed for the numbers used to place emergency calls through outbound trunking.

.. figure:: https://doc.didww.com/_images/cancel_emergency_calling.png
   :alt: Canceling an Emergency Calling Service request in the DIDWW User Panel
   :figclass: align-center
   :width: 100%

   **Fig. 12.** Canceling an Emergency Calling Service request using the Actions menu.



.. |br| raw:: html

   <br />

Emergency Number Dialing Reference by Country
==============================================

A country-by-country reference of emergency numbers and how to dial them. Dial the number listed for the relevant country directly - without a country code and without symbols such as "+" or "0".

.. note:: This is a dialing reference only and does not reflect DIDWW's emergency service coverage. For accurate coverage, see the Buy numbers page in my.didww.com.

.. xlsx-table::
   :file: emergency_numbers_merged.xlsx
   :header-rows: 1


.. _user_panel_pstn_trunk:

==========
PSTN Trunk
==========

PSTN trunks allow you to forward incoming calls through Direct Inward Dialing (DID) to the Public Switched Telephone Network (PSTN).

.. note::
   Incoming calls forwarded to a PSTN trunk are charged per minute. The rate and availability depend on the destination PSTN phone number.

----

Create a New PSTN Trunk
=======================

To create an inbound PSTN trunk, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Click the **Create New** button in the top-right corner of the screen.
4. From the dropdown menu, select **PSTN Trunk**.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Creating a new PSTN Trunk

   **Fig. 1.** Creating a new PSTN Trunk

----

.. _user_panel_pstn_trunk_quick_configuration:

Quick PSTN Trunk Configuration Guide
====================================

To quickly configure a PSTN trunk, enter the required information below:

1. Enter a **Name** - Provide a unique name to identify the trunk.
2. Enter the **PSTN Phone Number** - Specify the destination number in E.164 format (e.g., ``12065550100``).
3. Click **Check Rate** and review the displayed per-minute rate.
4. Click the **Create** button to save and activate the configuration.

.. note::
   The rate and destination availability depend on the PSTN phone number. To review current pricing, see :ref:`DIDWW pricelists <services_coverage_pricing_access_pricelists>`.

.. figure:: https://doc.didww.com/_images/quick_configuration.png
   :figclass: align-center
   :alt: Quick PSTN trunk configuration with the per-minute rate displayed

   **Fig. 2.** Quick PSTN trunk configuration

----

.. _user_panel_pstn_trunk_advanced_configuration:

Advanced PSTN Trunk Configuration Guide
=======================================

For advanced configurations, you can customize additional PSTN trunk settings.

.. grid:: 1 3 3 3
   :gutter: 4
   :padding: 2

   .. grid-item-card:: :octicon:`gear` **General**
      :link: user_panel_pstn_trunk_general_settings
      :link-type: ref
      :text-align: left

      Configure the destination, capacity, and ringing timeout.

   .. grid-item-card:: :octicon:`number` **Number Translations**
      :link: user_panel_pstn_trunk_number_translations
      :link-type: ref
      :text-align: left

      Configure caller ID filtering using a number list.

   .. grid-item-card:: :octicon:`versions` **Trunk Group**
      :link: user_panel_pstn_trunk_trunk_group_configuration
      :link-type: ref
      :text-align: left

      Assign trunks to groups for failover and load balancing.

----

.. _user_panel_pstn_trunk_general_settings:

General
-------

The **General** tab defines the PSTN destination and call limits for the trunk.

You can configure the following settings:

- **Name** - Enter a unique name to identify the trunk.
- **PSTN Phone Number** - Enter the destination number in E.164 format to which calls are forwarded (e.g., ``12065550100``).

.. note:: Click **Check Rate** to check whether the destination is available and display its per-minute rate.

- **Capacity Limit** - Specify the maximum number of simultaneous calls allowed for the trunk. Leave the field set to **Unlimited** to apply no trunk-specific limit. When the limit is reached, the system attempts to route the call through another trunk in the trunk group.
- **Ringing Timeout** - Specify the maximum number of seconds to wait for a ``200 OK`` response after receiving an ``18x`` response. When the timeout is reached, the routing attempt ends with the **Ringing timeout** disconnect code.

.. figure:: https://doc.didww.com/_images/general.png
   :figclass: align-center
   :alt: General tab with PSTN destination, capacity, and ringing timeout settings

   **Fig. 3.** General tab

----

.. _user_panel_pstn_trunk_number_translations:

Number Translations
-------------------

The **Number Translations** tab configures caller ID filtering for the PSTN trunk.

- **CLI Number List** - Assign a **Number List** to allow or reject incoming calls based on full number matches, prefix matches, or length restrictions. For more information, see the :ref:`Number List <user_panel_voice_in_numberlist>` documentation page.

.. figure:: https://doc.didww.com/_images/number_translations.png
   :figclass: align-center
   :alt: Number Translations tab with the CLI Number List setting

   **Fig. 4.** Number Translations tab

----

.. _user_panel_pstn_trunk_trunk_group_configuration:

Trunk Group
-----------

PSTN Trunk group configuration is **optional** and should only be used when multiple trunks need to be assigned to a single trunk group for **failover** or **load balancing**.

You can configure the following settings:

- **Trunk Group** - Select the trunk group to assign the trunk to. A trunk can belong to only one trunk group. If no trunk groups exist, see the :ref:`Trunk Group Creation Guide <user_panel_trunk_group>`.
- **Priority** - Set the trunk priority within the trunk group. Trunks with lower values are tried first. Trunks with the same priority are ordered by weight. For more details, see :rfc:`2782`.
- **Weight** - Set the relative weight for trunks with the same priority. A higher value increases the likelihood that the trunk is selected. For more details, see :rfc:`2782`.

.. figure:: https://doc.didww.com/_images/trunk_group.png
   :figclass: align-center
   :alt: Trunk Group tab with trunk group, priority, and weight settings

   **Fig. 5.** Trunk Group tab

----

Edit PSTN Trunk
===============

To edit an existing PSTN Trunk, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Locate the PSTN trunk that you want to edit and click the |actions| button.
4. Click **Edit**.

.. figure:: https://doc.didww.com/_images/edit-trunk.png
  :figclass: align-center
  :alt: Actions Button.

  **Fig. 6.** Actions Button.

5. In **Edit Inbound PSTN Trunk**, make the required changes and click **Submit** to save them.

.. figure:: https://doc.didww.com/_images/edit-trunk2.png
  :figclass: align-center
  :alt: Edit Inbound PSTN Trunk.

  **Fig. 7.** Edit Inbound PSTN Trunk.

----

Delete PSTN Trunk(s)
====================

You can either delete a single PSTN trunk or delete multiple PSTN trunks by using batch actions.

.. note::
   Trunks assigned to DID numbers or in use cannot be deleted.

Delete a Single PSTN Trunk
--------------------------

To delete an existing PSTN Trunk, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Locate the PSTN trunk that you want to delete and click the |actions| button.
4. Click **Delete**.

.. figure:: https://doc.didww.com/_images/delete-trunk.png
   :figclass: align-center
   :alt: Actions button with the Delete action selected

   **Fig. 8.** Actions Button.

5. In the **Delete Trunk(s)** pop-up window, click **Delete** to confirm the trunk deletion.

.. figure:: https://doc.didww.com/_images/delete2.png
   :figclass: align-center
   :alt: Delete Trunk(s) confirmation window.

   **Fig. 9.** Delete Trunk(s) confirmation window.

Delete Multiple PSTN Trunks
---------------------------

To delete **multiple** existing PSTN Trunks, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Select the PSTN trunks you want to delete.
4. Click **Batch Actions** and then select **Delete Trunk(s)**.

.. figure:: https://doc.didww.com/_images/delete-trunks.png
   :figclass: align-center
   :alt: Batch Actions menu with Delete Trunk(s) selected

   **Fig. 10.** Batch Actions Button.

5. In the **Delete Trunk(s)** pop-up window, click **Delete** to confirm the trunk deletion.

.. figure:: https://doc.didww.com/_images/delete2.png
   :figclass: align-center
   :alt: Delete Trunk(s) confirmation window.

   **Fig. 11.** Delete Trunk(s) confirmation window.

----

Additional Information
======================

.. card:: **Assign Trunks to DID Numbers**
    :link: user_panel_assign_trunk
    :link-type: ref

    Learn how to configure DID numbers with trunks and trunk groups for routing inbound calls.

.. card:: **Create a SIP Trunk**
    :link: user_panel_sipin_trunk
    :link-type: ref

    Create and configure SIP trunks for inbound calls, set transport protocols, authentication, media options, and more.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button


.. |br| raw:: html

    <br>

.. _user_panel_sipin_trunk:

=========
SIP Trunk
=========

A **SIP trunk** is a virtual connection that delivers inbound voice calls from the **public telephone network (PSTN)** to an **IP-based phone system** over the internet.

----

Create a New SIP Trunk
=======================

To create an inbound SIP trunk, follow these steps:

    1. Navigate to the **Voice** section in the left-hand menu.
    2. Select **Inbound Trunks** from the submenu.
    3. Click the **Create New** button in the top-right corner of the screen.
    4. From the dropdown menu, select **SIP Trunk**.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: Adding a new SIP Trunk
  :width: 80%

  **Fig. 1.** Adding a new SIP Trunk

----

.. _user_panel_sip_trunk_host:

Quick SIP Trunk Configuration Guide
===================================

To quickly configure a SIP trunk, enter the required information below:

1. Enter a **Name** - Provide a unique name to identify the trunk.
2. Enter your **Host** - Specify the public IP address or domain name of your server.
3. Click the **Create** button to save and activate your configuration.

.. important:: Because the preferred server is set to **Auto**, your system must allow traffic from all :ref:`DIDWW SIP IPs <service_did_sip>`.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Basic SIP trunk configuration example
   :width: 80%

   **Fig. 2.** Basic SIP trunk configuration example

----

.. _user_panel_sipin_trunk_advanced_configuration:

Advanced SIP Trunk Configuration Guide
======================================

For advanced configurations, you can customize additional SIP trunk settings.

.. grid:: 1 3 3 3
   :gutter: 4
   :padding: 2

   .. grid-item-card:: :octicon:`gear` **General**
      :link: user_panel_sipin_trunk_general_settings
      :link-type: ref
      :text-align: left

      Core routing, addressing, and SIP behavior settings.

   .. grid-item-card:: :octicon:`number` **Number Translations**
      :link: user_panel_sipin_trunk_number_translations
      :link-type: ref
      :text-align: left

      Configure caller ID formatting, prefixes, and number lists.

   .. grid-item-card:: :octicon:`versions` **Trunk Group**
      :link: user_panel_sipin_trunk_trunk_group_configuration
      :link-type: ref
      :text-align: left

      Assign trunks to groups for failover and load balancing.

   .. grid-item-card:: :octicon:`key` **Authorization**
      :link: user_panel_sipin_trunk_authentication
      :link-type: ref
      :text-align: left

      Configure additional SIP digest authentication for the trunk.

   .. grid-item-card:: :octicon:`unmute` **Media & DTMF**
      :link: user_panel_sipin_trunk_media_dtmf
      :link-type: ref
      :text-align: left

      Configure codecs, RTP security, DTMF methods, and media handling.

   .. grid-item-card:: :octicon:`pulse` **Signalling**
      :link: user_panel_sipin_trunk_general_advanced_signaling_settings
      :link-type: ref
      :text-align: left

      Manage session timers, timeout policies, and call redirection behavior.

   .. grid-item-card:: :octicon:`shield-check` **Additional Services**
      :link: user_panel_sipin_trunk_additional_services
      :link-type: ref
      :text-align: left

      Configure STIR/SHAKEN, diversion handling, and CNAM lookup.

----

.. _user_panel_sipin_trunk_general_settings:

General
-------

The **General** tab defines how inbound SIP calls are routed to your SIP endpoint.

You can configure the following settings:

General properties
^^^^^^^^^^^^^^^^^^

- **Name** – Enter a unique name to identify the trunk.
- **Capacity Limit** – Specify the maximum number of simultaneous calls allowed for this trunk.

.. _user_panel_sip_trunk_port:

.. _user_panel_sip_trunk_registration:

.. _inbound-sip-registration-routing-settings:

.. _routing-method-settings:

Type
^^^^

The **Type** setting determines **how DIDWW delivers calls to your endpoint**.

.. tab-set::
   :class: my-tabs
   :sync-group: routing

   .. tab-item:: *Static Endpoint*
      :selected:
      :sync: static-sip-uri

      Use **Static Endpoint** when your SIP endpoint has a fixed, reachable address. DIDWW delivers calls
      to the configured SIP URI, built from **User Part of R-URI**, **Host**, and **Port**.

      - **User Part of R-URI** – Define the user part of the ``R-URI`` in the INVITE request.

        .. dropdown:: **Placeholder Variables**
           :animate: fade-in

           - ``{DID}`` – Inserts the called DID in E.164.
           - ``{CALL_CPC}`` – Calling party category. See :ref:`CPC usage <upcpc>`.

      - **Host** – Host part of the ``R-URI`` in the SIP ``INVITE`` request. This can be an IP address or a domain.
      - **Port** – Port part of the ``R-URI`` in the SIP ``INVITE`` request.

        .. dropdown:: **Port Auto-Resolution Behavior**
           :animate: fade-in

           If **Port** is left empty, DIDWW first attempts an ``SRV`` record lookup. |br|
           If no ``SRV`` record is found, it falls back to resolving the ``A`` record.

      - **Resolve R-URI** – Replace the host part of the ``R-URI`` with the resolved IP address.
      - **Network Protocol** – Select the IP protocol preference used when resolving the host.

        .. list-table::
           :widths: 20 80
           :header-rows: 1

           * - Option
             - Description
           * - IPv4 only
             - Use IPv4 exclusively.
           * - IPv6 only
             - Use IPv6 exclusively.
           * - Any
             - Use either IPv4 or IPv6.
           * - Prefer IPv4 over IPv6
             - Prefer IPv4 but fallback to IPv6.
           * - Prefer IPv6 over IPv4
             - Prefer IPv6 but fallback to IPv4.

      - **Transport** – Choose the protocol for SIP signaling: **UDP**, **TCP**, or **TLS**.

      - **Preferred Server** – Choose the DIDWW Point of Presence (POP) for routing:

        - **Auto (recommended):** Let DIDWW select the optimal SBC dynamically
        - **US:** LA, MIA, NY
        - **Germany:** FRA
        - **Singapore:** SG
        - **Hong Kong:** HK
        - **Netherlands:** AMS

        .. Important::
           - When using **Auto**, allow all inbound :ref:`DIDWW signaling and RTP IPs <service_did_sip>` on your equipment.
           - The **Auto** preferred server option acts as a failover. If there is any interruption on a single POP, calls are routed through an alternative DIDWW POP to maintain call continuity.
           - Ensure all POPs are enabled in :ref:`settings <trunks_settings>`. Disabling any POP may cause unnecessary routing hops.

        .. dropdown:: **Routing Examples by Preferred Server**
           :animate: fade-in

           The following figures illustrate how incoming calls are routed based on the selected preferred server:

           1. **Preferred Server: FRA** - Calls from the PSTN network reach the DIDWW HK SBC and are routed to the FRA POP.

               .. figure:: https://doc.didww.com/_images/fig2.svg
                  :figclass: align-center no-shadow
                  :alt: Preferred Server: FRA
                  :width: 80%

                  **Fig. 3.** Routing example with FRA as the preferred server.

           2. **Preferred Server: Auto** - Calls are dynamically routed from the same DIDWW SBC that received them.

               .. figure:: https://doc.didww.com/_images/fig3.svg
                  :figclass: align-center no-shadow
                  :alt: Preferred Server: Auto
                  :width: 55%

                  **Fig. 4.** Routing example with Auto as the preferred server.

      .. figure:: https://doc.didww.com/_images/fig3.png
         :figclass: align-center
         :alt: General tab

         **Fig. 5.** General tab for static endpoint type

   .. tab-item:: *Dynamic Registration*
      :sync: sip-registration

      .. raw:: html

           <h2 id="inbound-sip-registration-routing-settings" style="display:none;"></h2>
           <a href="creating-a-new-sip-trunk.html?routing=sip-registration#routing-method-settings" style="display:none;"></a>

      Use **Dynamic Registration** when your PBX or SBC has a dynamic IP address, operates behind NAT, or when you prefer registration-based routing. Your SIP peer initiates and maintains registration, and DIDWW sends incoming calls to the **Contact address** learned during the SIP ``REGISTER`` process.

      - **Use DID in R-URI** – Replaces the user part of the ``R-URI`` in the SIP ``INVITE`` with the DID number, instead of the user part received in the ``Contact`` header during registration.

      .. important::
           - DIDWW generates the registration credentials and displays them immediately after the trunk is created.
           - A maximum of **10 simultaneous registrations** are supported per trunk.
           - View your registration username and password by clicking the **trunk name** on the **Inbound Trunks** page. For detailed steps, see :ref:`how to view credentials <view_inbound_trunk_registration_credentials>`.

      .. figure:: https://doc.didww.com/_images/register.png
           :figclass: align-center
           :alt: General tab for dynamic registration type

           **Fig. 6.** General tab for dynamic registration type

----

.. _user_panel_sipin_trunk_number_translations:

Number Translations
-------------------

The **Number Translations** tab defines the caller ID format delivered to your SIP endpoint.

- **CLI Format** – Select how the Caller ID (CLI) is formatted for incoming calls:

  .. list-table::
         :widths: 20 80
         :header-rows: 1

         * - Option
           - Description
         * - **E.164**
           - Converts the CLI to E.164 format (Country Code + Area Code + Number). This is the default option.
         * - **Raw**
           - Passes the caller ID unchanged.
         * - **Local**
           - Converts the CLI to local format (Area Code + Number).

- **CLI Prefix** – Prepend a custom prefix to the incoming CLI for identification or routing purposes.
- **CLI Number List** – Assign a **Number List** to allow or reject incoming calls based on full number matches, prefix matches, or length restrictions. For more information, see the :ref:`Number List <user_panel_voice_in_numberlist>` documentation page.

.. warning::
   - CLI format conversion may not work correctly for calls originating from outside the country of the DID.
   - Number Lists work by **matching** the inbound CLI. If you modify the **CLI format** and **CLI prefix**, you may need to adjust your numbers in the **Number List** accordingly.

.. figure:: https://doc.didww.com/_images/number_translations.png
     :figclass: align-center
     :alt: Number translations tab

     **Fig. 7.** Number translations tab

----

.. _user_panel_sipin_trunk_trunk_group_configuration:

Trunk Group
-----------

SIP Trunk group configuration is **optional** and should only be used when multiple trunks need to be assigned to a single trunk group for **failover** or **load balancing**.

You can configure the following settings:

- **Trunk Group** – Select the trunk group to assign the trunk to. A trunk can belong to only one trunk group. If no trunk groups exist, refer to the :ref:`Trunk Group Creation Guide <user_panel_trunk_group>`.
- **Priority** – Set the trunk priority within the trunk group. Trunks with lower values are tried first. Trunks with the same priority are ordered by weight. For more details, see :rfc:`2782`.
- **Weight** – Set the relative weight for trunks with the same priority. A higher value increases the likelihood that the trunk is selected. For more details, see :rfc:`2782`.
- **Re-routing Disconnect Codes** – Select the disconnect codes that trigger call rerouting to another trunk in the group. For available codes and their meanings, see :ref:`SIP Response Codes <inbound_technical_sip_response_codes_in_call_logs>`.

.. figure:: https://doc.didww.com/_images/trunk_group.png
  :figclass: align-center
  :alt: Trunk Group tab

  **Fig. 8.** Trunk Group tab

----

.. _user_panel_sipin_trunk_authentication:

Authorization
-------------

Authorization is an **optional** SIP Trunk setting that allows the trunk to be authenticated using **digest authentication (credentials)**. Use this feature only if your SIP server requires authentication.

To enable authorization, configure the following settings:

    .. list-table::
       :widths: 20 80
       :header-rows: 1

       * - **Setting**
         - **Description**
       * - **Enable Authorization**
         - Enables authentication for the SIP trunk for incoming INVITE requests from DIDWW.
       * - **Auth User**
         - Defines the username for authentication.
       * - **Auth Password**
         - Defines the password for authentication.
       * - **From User**
         - Specifies a custom user in the **From** field instead of the Caller ID.
       * - **From Domain**
         - Specifies a custom **From** domain in SIP messages.

.. figure:: https://doc.didww.com/_images/authorization.png
  :figclass: align-center
  :alt: Authorization tab

  **Fig. 9.** Authorization tab

----

.. _user_panel_sipin_trunk_media_dtmf:

Media & DTMF
------------

The **Media & DTMF** section allows you to configure codec preferences, Dual-Tone Multi-Frequency (DTMF) signaling, and real-time transport protocol (RTP) settings.

You can configure the following settings:

- **Allowed RTP IP Addresses** – Define the IP addresses that are allowed to send RTP media packets to this SIP trunk. To restrict RTP sources, enter up to 10 IP addresses or subnets in the following format: ``IPv4[/mask]`` or ``IPv6[/mask]``, e.g., ``203.0.113.5/32, 2001:db8::1/128``.

.. note::
   - If left blank, RTP packets are accepted from any source.
   - If the mask is omitted, ``/32`` is used for IPv4 and ``/128`` is used for IPv6.

- **Codecs** – Select the codecs to include in the SDP offer. Selected codecs can be removed individually, or you can click **Remove All** to clear the selection. Reorder selected codecs to set their priority; the first codec has the highest priority. For a list of supported codecs, see :ref:`Supported Codecs <service_did_sip_codecs>`.
- **SRTP Mode** – Select the Secure Real-time Transport Protocol (SRTP) mode used for media encryption. DIDWW supports **TLS** for secure SIP signaling and `SRTP <https://en.wikipedia.org/wiki/Secure_Real-time_Transport_Protocol>`_ for media encryption.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **Disabled**
       - Do not use SRTP media encryption.
     * - **SRTP SDES**
       - Negotiate SRTP keys using `Session Description Protocol Security Descriptions <https://en.wikipedia.org/wiki/SDES>`_.
     * - **SRTP DTLS**
       - Negotiate SRTP keys using `Datagram Transport Layer Security <https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security>`_.
     * - **SRTP ZRTP**
       - Negotiate SRTP keys using the `ZRTP key agreement protocol <https://en.wikipedia.org/wiki/ZRTP>`_.

- **DTMF Send Mode** – Select how Dual-Tone Multi-Frequency (DTMF) signals are sent from DIDWW to your equipment.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **Disable sending**
       - Do not send DTMF signals to your equipment.
     * - **RFC 2833**
       - Send DTMF events using the ``telephone-event`` RTP payload. This is the default option.
     * - **SIP INFO application/dtmf-relay**
       - Send DTMF events in SIP ``INFO`` requests using the ``application/dtmf-relay`` content type.
     * - **SIP INFO application/dtmf**
       - Send DTMF events in SIP ``INFO`` requests using the ``application/dtmf`` content type.

- **DTMF Receive Mode** – Select how Dual-Tone Multi-Frequency (DTMF) signals are received by DIDWW from your equipment. For more details, see :ref:`DTMF options <service_did_sip_dtmf>`.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **RFC 2833**
       - Receive DTMF events using the ``telephone-event`` RTP payload. This is the default option.
     * - **SIP INFO application/dtmf-relay OR application/dtmf**
       - Receive DTMF events in SIP ``INFO`` requests using either the ``application/dtmf-relay`` or ``application/dtmf`` content type.
     * - **RFC 2833 OR SIP INFO**
       - Receive DTMF events using either the ``telephone-event`` RTP payload or SIP ``INFO`` requests.

- **RTP Timeout** – Define the maximum time, in seconds, before a call is disconnected if no RTP packets are received.

  .. note:: RTP Timeout value must be between 5 and 600 seconds.

- **Force Symmetric RTP** – Send media to the source IP address and port of received RTP packets, ignoring the remote address negotiated in the SDP.

  .. warning::
     Enabling **Force Symmetric RTP** may expose the call to an RTP Bleed attack, where an attacker can hijack the RTP stream by sending crafted packets from a different source address. Restrict accepted RTP sources using **Allowed RTP IP Addresses** to mitigate this risk.

- **Symmetric RTP Ignore RTCP** – When **Force Symmetric RTP** is enabled, use only RTP packets when switching the media path and ignore RTCP packets.
- **RTP Ping** – After SDP negotiation is complete, send several empty RTP packets to trigger RTP transmission on the remote side.

.. figure:: https://doc.didww.com/_images/media_and_dtmf.png
   :figclass: align-center
   :alt: Media & DTMF tab

   **Fig. 10.** Media & DTMF tab

----

.. _user_panel_sipin_trunk_general_advanced_signaling_settings:

Signalling
----------

The **Signalling** tab allows you to configure **SIP session management, transaction timeouts, failover behavior, call transfers, and redirects**. These optional settings help maintain **call stability**, prevent **unnecessary call drops**, and optimize **failover handling** in case of network failures.

.. _user_panel_sipin_trunk_general_advanced_signaling_settings_timeout:

You can configure the following settings:

- **SIP Session Timers** – Enable DIDWW to initiate SIP session timer negotiation. Session timers periodically refresh the SIP session and terminate it when the remote endpoint stops responding. For more details, see `RFC 4028 <https://datatracker.ietf.org/doc/html/rfc4028>`_.
- **SST MIN Timer** – Set the minimum session interval. The default value is 600 seconds.
- **SST MAX Timer** – Set the maximum session interval. The default value is 900 seconds.
- **SST Session Expires** – Define the ``Session-Expires`` header value. The value must be within the range defined by **SST MIN Timer** and **SST MAX Timer**.
- **SST Refresh Method** – Select the SIP method used to refresh the session.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **Invite**
       - Refresh the session using an ``INVITE`` request. This is the default option.
     * - **Update**
       - Refresh the session using an ``UPDATE`` request.
     * - **Update fallback Invite**
       - Use an ``UPDATE`` request when supported and fall back to ``INVITE`` when necessary.

- **SST Accept 501** – Do not terminate the call after receiving a SIP ``501`` response to a session update request.
- **SIP Timer B** – Set the timeout for an ``INVITE`` transaction, in milliseconds. The default value is 8000 ms. For more details, see `RFC 3261 Section 17.1.1.2 <https://www.rfc-editor.org/rfc/rfc3261.html#section-17.1.1.2>`_.
- **DNS SRV Failover Timer** – Set how long DIDWW waits for an ``INVITE`` transaction before rerouting to the next DNS SRV target, in milliseconds. The default value is 2000 ms.
- **Ringing Timeout** – Set the maximum time to wait for a ``200 OK`` response after receiving an ``18x`` response, in seconds. When exceeded, the routing attempt ends with the **Ringing timeout** disconnect code.
- **Max Transfers** – Set the maximum number of SIP ``REFER`` requests processed for call transfers. The default value is 0.
- **Max 30x Redirects** – Set the maximum number of SIP ``301`` or ``302`` redirect responses followed during call rerouting. The default value is 0.

.. figure:: https://doc.didww.com/_images/signaling.png
  :figclass: align-center
  :alt: Signalling tab

  **Fig. 11.** Signalling tab

----

.. _user_panel_sipin_trunk_additional_services:

Additional Services
-------------------

The **Additional Services** tab contains STIR/SHAKEN handling, diversion settings, and CNAM lookup.

.. _up_stir_shaken:

.. _user_panel_sipin_trunk_general_stir_shaken:

.. _user_panel_sipin_trunk_general_cnam_in:

You can configure the following settings:

- **STIR SHAKEN Mode** – Select how STIR/SHAKEN information is delivered in SIP signaling. The STIR/SHAKEN framework helps prevent caller ID spoofing by verifying the authenticity of the calling number.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **Disabled**
       - Do not include additional STIR/SHAKEN headers.
     * - **Relay Identity header**
       - Relay the Identity header in SIP ``INVITE`` messages.
     * - **Add PAI, P-Attestation-Indicator, P-Origination-ID**
       - Add the listed attestation and identity headers to the SIP ``INVITE`` request.
     * - **Relay Identity header + Add PAI, P-Attestation-Indicator, P-Origination-ID**
       - Relay the Identity header and add the listed attestation headers to the SIP ``INVITE`` request.
     * - **Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID**
       - Add verification status and attestation headers to the SIP ``INVITE`` request.

.. note::
   The **Relay Identity header** option is not enabled by default. To enable it for your DIDWW account or from the originating side, contact our sales team at `sales@didww.com <mailto:sales@didww.com>`_.

- **Diversion Relay Policy** – Control how PSTN Diversion information is delivered in SIP signaling.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **Disabled**
       - Do not relay the Diversion header.
     * - **Diversion header in SIP URI format**
       - Format and relay the Diversion header as a SIP URI, for example, ``sip:user@sip.didww.com``.
     * - **Diversion header in TEL URI format**
       - Format and relay the Diversion header as a TEL URI, for example, ``tel:+123456789``.

- **Diversion Inject Mode** – Control whether DIDWW adds its own Diversion information to outgoing SIP messages.

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **Disabled**
       - Do not add a DIDWW-generated Diversion header.
     * - **Add Diversion header with DID number**
       - Add a DIDWW-generated Diversion header containing the associated DID number.

.. note:: If both **Diversion Relay Policy** and **Diversion Inject Mode** are enabled at the same time, two Diversion headers may be included in the SIP message, which may cause unexpected behavior on your system.

- **Enable CNAM Lookup** – Retrieve and display the caller name associated with a US CLI. The caller name is delivered as the display name in the SIP ``From`` header.

  - The system queries a remote CNAM database when a call originates from the US.
  - Billing applies only if the lookup is successful.

  .. warning::
     If a **Trunk Group** is used and any of its trunks have CNAM lookup enabled:

     - A CNAM lookup will be performed for all incoming calls.
     - A successful lookup will be billed additionally per call.
     - The retrieved CNAM value will be displayed only for trunks with CNAM lookup enabled.

**CNAM in the SIP From Header**

The following examples show how CNAM appears in the **From** header:

    - **CNAM lookup not enabled:** ``"12899230448" <sip:12899230448@46.19.213.14>;tag=24-6917EC3D-6453984E000C1C1E-5EA5B700``
    - **CNAM lookup enabled and lookup successful:** ``"KRIS TOTAL" <sip:15203981500@46.19.213.14>;tag=24-7EB42886-645381060002B85A-5EB5C700``
    - **CNAM lookup enabled but lookup failed:** ``"Unavailable" <sip:15203981500@46.19.213.14>;tag=24-7EB42886-645381060002B85A-5EB5C700``

The CNAM value is also displayed in the **Source Name** field in :ref:`inbound call logs <inbound_cdr_logs>`.

.. figure:: https://doc.didww.com/_images/additional_services.png
  :figclass: align-center
  :alt: Additional Services tab with STIR/SHAKEN, diversion, and CNAM lookup settings

  **Fig. 12.** Additional Services tab

----

.. _view_inbound_trunk_registration_credentials:

View Inbound SIP Registration Credentials
=========================================

If your inbound SIP trunk uses :ref:`Dynamic Registration <user_panel_sip_trunk_registration>`, the system automatically generates a unique set of credentials. You can view these credentials by clicking on the **trunk name** on the **Inbound Trunks** page.

.. figure:: https://doc.didww.com/_images/credentials1.png
  :figclass: align-center
  :alt: Accessing SIP Registration credentials on the Inbound Trunks page

  **Fig. 13.** Accessing SIP Registration credentials.

A **SIP Credentials** pop-up window will appear, showing the necessary details for registering your SIP endpoint:

The pop-up displays the following information:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Field**
     - **Description**
   * - **Username**
     - The unique, system-generated username required for your SIP endpoint to register with DIDWW.
   * - **Password**
     - The password required for registration. Select the **eye** icon to view the password in clear text.
   * - **Host**
     - The DIDWW SIP server hostname your SIP endpoint must register to (e.g., ``sip.didww.com``). For more details, see :ref:`General SIP Information <service_did_sip>`.

.. figure:: https://doc.didww.com/_images/credentials2.png
  :figclass: align-center
  :alt: My SIP Trunk SIP Credentials pop-up window

  **Fig. 14.** SIP Registration Credentials pop-up.

----

.. _user_panel_sipin_trunk_edit:

Edit SIP Trunk
================

To edit an existing SIP Trunk, follow these steps:

    1. Navigate to the **Voice** section in the left-hand menu.
    2. Select **Inbound Trunks** from the submenu.
    3. Locate the SIP trunk that you want to edit and click the |actions| button.
    4. Click **Edit**.

    .. figure:: https://doc.didww.com/_images/actions_edit.png
      :figclass: align-center
      :alt: Actions Button.

      **Fig. 15.** Actions Button.

    5. In **Edit Inbound SIP Trunk**, make the required changes and click **Submit** to save them.

    .. figure:: https://doc.didww.com/_images/edit_screen.png
      :figclass: align-center
      :alt: Edit Inbound SIP Trunk.

      **Fig. 16.** Edit Inbound SIP Trunk.

----

.. _user_panel_sipin_trunk_registration_history:

View Registration History
=========================

.. note::
   The **Registration History** is available only for trunks that use :ref:`Dynamic Registration <user_panel_sip_trunk_registration>`. It displays recent successful registration intervals for the selected trunk.

Follow these steps to view the Registration History:

    1. Go to the **Voice** section in the menu.
    2. Select **Inbound Trunks**.
    3. Find the trunk you want to inspect and open the **Actions** menu.
    4. Click **View Registration History**.

    .. figure:: https://doc.didww.com/_images/registration_statistics1.png
      :figclass: align-center
      :alt: Opening the Registration History window from the Actions menu.

      **Fig. 17.** Opening the Registration History window.

Registration History Chart
--------------------------

The Registration History chart shows **successful registration intervals**, indicating when a valid ``Contact`` header was active for call routing.

.. note::
    - The chart shows the times when the trunk was successfully registered and online. Individual SIP ``REGISTER`` requests or failed attempts are not displayed.
    - Registration data is available for the **last 7 days**. If no successful registrations occurred in this period, no data will appear.
    - Registration activity is shown in **one-minute intervals**.

Hover over any point in the chart to view details about that registration interval, including:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Field**
     - **Description**
   * - **Contact**
     - The Contact address used by your system during registration.
   * - **IP/Port**
     - The source IP address and port used for the registration.
   * - **Transport Protocol**
     - The transport protocol used for the registration (UDP, TCP, or TLS).
   * - **User Agent**
     - The User-Agent string reported by the registering system.
   * - **Expires**
     - The registration lifetime (Expires value) provided by your endpoint.

.. figure:: https://doc.didww.com/_images/registration_statistics2.png
   :figclass: align-center
   :alt: SIP Registration History chart.

   **Fig. 18.** SIP Registration History chart.

You can zoom in to focus on a specific time range. Click and drag across the chart to select the period you want to view.

.. figure:: https://doc.didww.com/_images/registration_statistics_gif.gif
  :figclass: align-center
  :alt: Zooming and narrowing the Registration History chart.

  **Fig. 19.** Zooming into a selected part of the chart.

----

Delete SIP Trunk(s)
===================

You can either delete a single SIP trunk or delete multiple SIP trunks by using batch actions.

    .. note:: Trunks assigned to DID numbers or in use cannot be deleted.

Delete a Single SIP Trunk
-------------------------

To delete an existing SIP Trunk, follow these steps:

    1. Navigate to the **Voice** section in the left-hand menu.
    2. Select **Inbound Trunks** from the submenu.
    3. Locate the SIP trunk that you want to delete and click the actions button.
    4. Click **Delete**.

    .. figure:: https://doc.didww.com/_images/actions_delete.png
      :figclass: align-center
      :alt: Actions Button.

      **Fig. 20.** Actions Button.

    5. In the pop-up Delete Trunk(s) window click **Delete** to confirm the Trunk deletion.

    .. figure:: https://doc.didww.com/_images/delete_one.png
      :figclass: align-center
      :alt: Delete a Single Trunk.

      **Fig. 21.** Delete a Single Trunk.

Delete Multiple SIP Trunks
--------------------------

To delete **multiple** existing SIP Trunks, follow these steps:

    1. Navigate to the **Voice** section in the left-hand menu.
    2. Select **Inbound Trunks** from the submenu.
    3. Select the SIP trunks that you want to delete.
    4. Click on the **Batch Actions** button and click **Delete**.

    .. figure:: https://doc.didww.com/_images/delete_batch_actions.png
      :figclass: align-center
      :alt: Batch Actions Button.

      **Fig. 22.** Batch Actions Button.

    5. In the pop-up Delete Trunk(s) window click **Delete** to confirm the Trunk deletion.

    .. figure:: https://doc.didww.com/_images/delete_batch.png
      :figclass: align-center
      :alt: Delete Multiple Trunks

      **Fig. 23.** Delete Multiple Trunks.

----

Additional Information
=======================

.. card:: **General SIP Information**
    :link: service_did_sip
    :link-type: ref

    Learn more about DIDWW inbound signaling, RTP IPs, supported codecs, DTMF transport methods, and encryption.

.. card:: **Assign Trunks to DID Numbers**
    :link: user_panel_assign_trunk
    :link-type: ref

    Learn how to configure DID numbers with trunks and trunk groups for routing inbound calls.

.. card:: **Create a Trunk Group**
    :link: user_panel_trunk_group
    :link-type: ref

    Discover how to create and configure a trunk group for failover and load balancing.

.. card:: **STIR/SHAKEN**
    :link: service_did_stir_shaken
    :link-type: ref

    Understand STIR/SHAKEN, how it works, and the available handling modes for the Voice IN service.

.. card:: **CPC Usage**
    :link: upcpc
    :link-type: ref

    Explore the Calling Party Category (CPC), its functionality, and usage examples in SIP URIs.

.. |inline_create| image:: /img/new_user_panel/trunks/voice_in/sip/inline_create.png
   :class: no-shadow no-lightbox
   :width: 67.5px
   :height: 30px

.. |right_arrow| image:: /img/new_user_panel/trunks/voice_in/sip/right_arrow.svg
   :class: no-shadow no-lightbox
   :width: 30px
   :height: 30px

.. |left_arrow| image:: /img/new_user_panel/trunks/voice_in/sip/left_arrow.svg
   :class: no-shadow no-lightbox
   :width: 30px
   :height: 30px

.. |actions| image:: /img/new_user_panel/trunks/voice_in/trunk_group/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. Automatically update URL when switching between Dynamic Registration and Static Endpoint tabs
.. raw:: html

   <script>
   (function () {
     document.addEventListener("click", function (event) {
       const tab = event.target.closest('[role="tab"], .sd-tab-item, .sd-tab-label, button, a');
       if (!tab) return;

       const label = (tab.textContent || "").trim();

       if (label.includes("Dynamic Registration")) {
         const newUrl = `${location.pathname}?routing=sip-registration#routing-method-settings`;
         try {
           history.replaceState(null, "", newUrl);
         } catch (e) {}
         return;
       }

       if (label.includes("Static Endpoint")) {
         const newUrl = `${location.pathname}#routing-method-settings`;
         try {
           history.replaceState(null, "", newUrl);
         } catch (e) {}
         return;
       }
     });
   })();
   </script>


.. _user_panel_trunk_group:

============
Trunk Groups
============

An inbound trunk group combines multiple SIP and PSTN trunks into a single routing configuration. It distributes incoming calls among those trunks and supports failover to backup trunks when a preferred trunk is unavailable.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: Inbound Trunks

  **Fig. 1.** Inbound Trunks

----

Create a New Trunk Group
========================

To create an inbound trunk group, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Click the **Create New** button and select **Trunk Group**.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :alt: Creating a new trunk group

  **Fig. 2.** Creating a new trunk group.

The **Create Inbound Trunk Group** page opens. Configure the following settings:

- **Name** - Enter a unique name to identify the trunk group.
- **Capacity Limit** - Optionally specify the maximum number of simultaneous calls allowed for the trunk group. Leave the field set to **Unlimited** if no restrictions are required. Calls that exceed the limit are rejected.
- **Trunks** - Select one or more inbound trunks to include in the trunk group. Each trunk can belong to only one trunk group.

After completing the configuration, click **Create** to save the trunk group.

.. figure:: https://doc.didww.com/_images/create.png
  :figclass: align-center
  :alt: Create Inbound Trunk Group page with Name, Capacity Limit, and Trunks settings

  **Fig. 3.** Creating a new trunk group.

----

Edit Trunk Group
================

To edit an existing trunk group, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Locate the trunk group that you want to edit, click the **Actions** button, and select **Edit**.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Actions Button

  **Fig. 4.** Actions Button.

4. In **Edit Inbound Trunk Group**, make the required changes and click **Submit** to save them.

.. figure:: https://doc.didww.com/_images/edit.png
  :figclass: align-center
  :alt: Edit Inbound Trunk Group page with Name, Capacity Limit, and Trunks settings

  **Fig. 5.** Editing a trunk group.

----

Manage Priority and Weight
==========================

The **Priority** and **Weight** settings control how calls are distributed among the trunks in a group.

Priority
--------

The **Priority** setting determines the order in which trunks are used for routing calls. Trunks with lower priority numbers are used first. This setting is useful for failover scenarios, ensuring backup trunks are only used when higher-priority trunks are unavailable.

Weight
------

The **Weight** setting distributes call traffic among trunks with the same priority. Trunks with higher weights handle a greater share of calls, enabling effective load balancing.

Adjust Priorities and Weights
-----------------------------

To modify the **Priority** or **Weight** settings:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Locate the trunk group that you want to configure and click the |+-symbol| icon to display its trunks.
4. Locate the trunk that you want to configure, click the **Actions** button, and select **Edit**.

.. figure:: https://doc.didww.com/_images/edit-trunk-action.png
   :figclass: align-center
   :alt: Expanded inbound trunk group with the Edit action selected for a trunk

   **Fig. 6.** Editing a trunk within a trunk group.

5. On the **Edit Trunk** page, select the **Trunk Group** tab.
6. Update the **Priority** and **Weight** values as needed.
7. Click **Submit** to save the changes.

.. note::
   Use **Priority** to define the order in which trunks are used, and **Weight** to balance call traffic among trunks with the same priority.

.. figure:: https://doc.didww.com/_images/priority-and-weight.png
   :figclass: align-center
   :alt: Trunk Group tab with Priority and Weight settings

   **Fig. 7.** Priority and Weight settings for a trunk.

----

Delete Trunk Group
==================

To delete an existing trunk group, follow these steps:

1. Navigate to the **Voice** section in the left-hand menu.
2. Select **Inbound Trunks** from the submenu.
3. Locate the trunk group that you want to delete and click the |actions| button.
4. Click **Delete**.

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center
  :alt: Actions Button

  **Fig. 8.** Actions Button.

In the confirmation dialog, choose one of the following options:

- **Delete Trunk Group only** - Removes the trunk group while keeping its associated trunks.

- **Delete Trunk Group and Trunks** - Deletes the trunk group and all trunks included in it.

.. warning::
   If the trunk group is assigned to any DID numbers, you must unassign it before deleting the group.

Click **Delete** to confirm.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :alt: Deleting a trunk group

  **Fig. 9.** Deleting a trunk group.

----

Additional Information
======================

.. _user_panel_assign_trunk_card:

.. card:: **Assign Trunks to DID Numbers**
    :link: user_panel_assign_trunk
    :link-type: ref

    Understand how to configure DID numbers with trunks and trunk groups for routing inbound calls.

.. _user_panel_sipin_trunk_card:

.. card:: **Create a SIP Trunk**
    :link: user_panel_sipin_trunk
    :link-type: ref

    Create and configure SIP trunks for inbound calls, set transport protocols, authentication, media options, and more.

.. _service_did_sip_card:

.. card:: **General SIP Information for Inbound Services**
    :link: service_did_sip
    :link-type: ref

    Access general SIP information, including supported IP addresses, RTP ports, encryption options, codecs, and DTMF transport methods.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/trunk_group/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |+-symbol| image:: /img/new_user_panel/trunks/voice_in/trunk_group/+-symbol.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _user_panel_voice_in:

==============
Inbound Trunks
==============

DIDWW **Inbound SIP Trunking** ensures reliable, scalable, and high-quality voice traffic delivery from local, mobile, and toll-free numbers worldwide. Our flexible **trunk group architecture** provides **automatic failover protection**, **load balancing**, and **configurable call routing** to optimize call handling.

**Getting Started with Inbound SIP Trunks**

Follow these steps to set up and configure your inbound SIP trunk:

    1. **Create a SIP Trunk**. See the :ref:`Creating a New SIP Trunk <user_panel_sipin_trunk>`
    2. **Assign Your Trunk to a DID**. Learn how in :ref:`Assign a voice trunk <user_panel_assign_trunk>`
    3. **Configure Routing & Capacity**. Adjust settings in :ref:`Routing Settings <trunks_settings>`

**Key Features**

    - **Preferred server selection**: Choose specific Points of Presence (POPs) for each SIP trunk to ensure redundancy and low-latency services.
    - **Link failure protection**: Trunk groups automatically use alternate links in case of failure, based on configured priorities.
    - **Load balancing**: Distribute network traffic among multiple servers for optimal performance. Assign weight factors to define traffic sharing between trunks.
    - **Re-routing disconnect codes**: Select the SIP response codes and DIDWW-specific failure conditions that trigger routing to another trunk in the group.
    - **Configurable ringing timeouts**: Set timeouts for call connection failures and route timed-out calls to another trunk in the group.
    - **Capacity limits**: Set the maximum number of concurrent calls per trunk to manage call volumes effectively.
    - **Number List**: Block specific phone numbers or prefixes from making calls to your service, helping reduce unwanted or spam calls.

**Supported Trunk Types**

    - :ref:`SIP <service_did_sip>`: Incoming calls are delivered to your designated infrastructure using the `Session Initiation Protocol (SIP) <https://en.wikipedia.org/wiki/Session_Initiation_Protocol>`_.
    - `PSTN <https://en.wikipedia.org/wiki/Public_switched_telephone_network>`_: Incoming calls are routed to your specified telephone number using DIDWW PSTN Termination.
    - :ref:`phone.systems™ <service_phone_systems2>`: Calls are distributed via a cloud-based virtual PBX software.

----

.. grid:: 1 1 3 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plug` **SIP Trunk**
      :link: creating-a-new-sip-trunk
      :link-type: doc
      :text-align: left

      Set up and configure a SIP trunk for VoIP call routing and connectivity.

   .. grid-item-card:: :octicon:`broadcast` **PSTN Trunk**
      :link: creating-a-new-pstn-trunk
      :link-type: doc
      :text-align: left

      Establish a PSTN trunk to connect with traditional telephony networks.

   .. grid-item-card:: :octicon:`git-merge` **Trunk Group**
      :link: creating-a-new-trunk-group
      :link-type: doc
      :text-align: left

      Combine multiple trunks into a single group for redundancy and load balancing.

   .. grid-item-card:: :octicon:`arrow-right` **Assign a voice trunk**
      :link: user_panel_assign_trunk
      :link-type: ref
      :text-align: left

      Assign voice trunks to DID numbers for inbound call routing.

   .. grid-item-card:: :octicon:`list-unordered` **Inbound Number Lists**
      :link: number-lists
      :link-type: doc
      :text-align: left

      Manage inbound number lists to organize and control call routing efficiently.

   .. grid-item-card:: :octicon:`gear` **Routing Settings**
      :link: settings/index
      :link-type: doc
      :text-align: left

      Configure routing settings to control how calls are distributed through trunks.

   .. grid-item-card:: :octicon:`file` **Technical Specification**
      :link: technical-data/index
      :link-type: doc
      :text-align: left

      Review detailed technical data and specifications for trunk configuration and compatibility.

.. toctree::
  :maxdepth: 1
  :hidden:

  SIP Trunk <creating-a-new-sip-trunk.rst>
  PSTN Trunk <creating-a-new-pstn-trunk.rst>
  Trunk Group <creating-a-new-trunk-group.rst>
  Inbound Number Lists <number-lists.rst>
  Routing Settings <settings/index.rst>
  Technical Specification <technical-data/index.rst>


.. |br| raw:: html

    <br>

.. _user_panel_voice_in_numberlist:

====================
Inbound Number Lists
====================

The **Number List** feature in the DIDWW user panel allows you to manage inbound call filtering by specifying which phone numbers or prefixes should be **allowed or rejected**. These lists can be linked to inbound **SIP** and **PSTN** trunks, ensuring that only approved calls go through while unwanted ones are rejected.

This guide walks you through the process of creating a **Number List**, adding numbers or prefixes, and configuring rules to either **allow or reject** calls. You’ll learn how to:

    - **Create a Number List** and assign it to an inbound **SIP** or **PSTN** trunk.
    - **Define specific numbers or prefixes** to allow or reject calls.
    - **Manage Number Lists**, including editing and deleting entries.
    - **Analyze call rejection error codes** to troubleshoot blocked calls and adjust settings.

Pick one of the following options to proceed:

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **1. Create a Number List**
      :link: user_panel_voice_in_numberlist_create
      :link-type: ref
      :text-align: center

      Set up a Number List to allow or reject calls based on full number or prefix matches.

   .. grid-item-card:: **2. Add and Configure Numbers in the Number List**
      :link: user_panel_voice_in_numberlist_manage
      :link-type: ref
      :text-align: center

      Learn to add numbers, set actions, and define length limits in a Number List.

   .. grid-item-card:: **3. Assign a Number List to a Trunk**
      :link: user_panel_voice_in_numberlist_assign
      :link-type: ref
      :text-align: center

      Assign a Number List to an Inbound SIP or PSTN Trunk to filter calls by number or prefix.

   .. grid-item-card:: **Number List Examples & Use Cases**
      :link: user_panel_voice_in_numberlist_examples
      :link-type: ref
      :text-align: center

      See examples of Number List configurations for allowing or rejecting calls.

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_create:

1. Create a Number List
=======================

Before you can filter inbound calls, you need to create a **Number List**. This list will store numbers and prefixes that can later be assigned to a **SIP** or **PSTN** trunk for call filtering.

Follow these steps to create a **Number List** to filter inbound calls.

Step 1: Open the Create Inbound Number List
-------------------------------------------

    1. Go to the **Voice** menu.
    2. Select **Inbound Trunks**.
    3. Open the **Number Lists** tab.
    4. Click **Create New** to start the setup.

    .. figure:: https://doc.didww.com/_images/fig1.1.png
      :figclass: align-center
      :alt: Number Lists Create New Button
      :width: 100%

      **Fig. 1.** Number Lists Create New Button

Step 2: Configure the Number List
---------------------------------

On the **Number List** creation screen, configure the list based on your requirements:

    1. Enter a **Friendly Name** (e.g., **Blocked Callers**).
    2. Select a **Mode**:

       - **Full Number Match**: The number(s) must include the exact full source calling number to apply this rule.
       - **Prefix Match**: The number(s) must include a prefix. This rule applies only if the source number matches your entered prefix(s).
    3. Set the **Default Action**:

       - **Allow call**: All calls will be allowed if no matching numbers are found in your number list.
       - **Reject call**: All calls will be rejected if no matching numbers are found in your number list.

    .. figure:: https://doc.didww.com/_images/fig2.png
      :figclass: align-center
      :alt: Configure the Number List
      :width: 100%

      **Fig. 2.** Configure the Number List

Step 3: Create the Number List
------------------------------

Click **Create** to save your new **Number List**. It will now appear in the **Number Lists** section.

    .. figure:: https://doc.didww.com/_images/fig2.1.png
      :figclass: align-center
      :alt: Create the Number List
      :width: 100%

      **Fig. 3.** Create the Number List

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_manage:

2. Add and Configure Numbers in the Number List
===============================================

After creating a **Number List**, the next step is to configure it by adding numbers or prefixes, setting actions to **allow** or **reject** calls, and, if using prefixes, defining length limits.

Follow these steps to add numbers to an existing **Number List**.

Step 1: Open the Number List
----------------------------

    1. Go to the **Voice** menu.
    2. Select **Inbound Trunks**.
    3. Open the **Number Lists** tab.
    4. Choose the list where you would like to add or manage numbers and click the |actions| button.
    5. Select **Manage Numbers** or click **Add Numbers**.

    .. figure:: https://doc.didww.com/_images/step1_open_the_add_numbers.png
      :figclass: align-center
      :alt: Open Manage or Add Numbers.
      :width: 100%

      **Fig. 4.** Open Manage or Add Numbers.

Step 2: Add Numbers to the Number List
--------------------------------------

On the **Manage Numbers** page, you can view and modify the list of previously added numbers. You can add new numbers, remove existing ones, or adjust their settings to **allow** or **reject** calls based on your needs.

    1. Click **Add Numbers** from the **Manage Numbers** page or within the **Number List** page to open the number entry dialog.

    .. figure:: https://doc.didww.com/_images/fig4.png
      :figclass: align-center
      :alt: Add Number Button.
      :width: 100%

      **Fig. 5.** Add Number Button.

    2. When the **Add Numbers** pop-up appears, enter the **Numbers or prefixes to be added** to the list.

        - Separate multiple numbers with a comma (e.g., ``15551234567, 1234567890``).

    .. figure:: https://doc.didww.com/_images/fig4.1.png
      :figclass: align-center
      :alt: Comma Separated Numbers
      :width: 100%

      **Fig. 6.** Comma Separated Numbers

Step 3: Configure Number Actions & Save Changes
-----------------------------------------------

A mandatory action must be selected to either **allow** or **reject** calls for the added numbers or prefixes.

    1. Select an **Action**:

         - **Allow call**: The call will be allowed if the source number matches a number or prefix in your list. This action overrides any rules set in your number list.
         - **Reject call**: The call will be rejected if the source number matches a number or prefix in your list. This action overrides any rules set in your number list.
    2. **(Optional)** When using prefixes for routing, adjust the **Min. Length** and **Max. Length** fields. These settings define the range of phone numbers the rule applies to:

         - **Min. Length**: The shortest phone number that can match the prefix (**default: 0**).
         - **Max. Length**: The longest phone number that can match the prefix (**default: 100**).
    3. Click **Submit** to save the changes.

    .. figure:: https://doc.didww.com/_images/configure_number_actions.png
      :figclass: align-center
      :alt: Number List Settings
      :width: 100%

      **Fig. 7.** Number List Settings

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_assign:

3. Assign a Number List to a Trunk
==================================

After creating and configuring your **Number List**, you can assign it to a trunk to apply inbound call filtering rules.

Number Lists can be assigned to either a **SIP Trunk** or a **PSTN Trunk**, depending on your routing setup.
Choose one of the options below:

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Assign a Number List to a SIP Trunk**
      :link: user_panel_voice_in_numberlist_assign_sip
      :link-type: ref
      :text-align: center

      Apply your Number List to a SIP trunk to filter inbound calls.

   .. grid-item-card:: **Assign a Number List to a PSTN Trunk**
      :link: user_panel_voice_in_numberlist_assign_pstn
      :link-type: ref
      :text-align: center

      Apply your Number List to a PSTN trunk to filter inbound calls.

.. _user_panel_voice_in_numberlist_assign_sip:

Assign a Number List to a SIP Trunk
-----------------------------------

Follow these steps to assign a Number List to a **SIP Trunk**.

Step 1: Open the SIP Trunk
~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Go to the **Voice > Inbound Trunks** menu.
    2. Choose an existing **SIP Trunk** by clicking its name, or create a new one (see :ref:`SIP Trunk documentation <user_panel_sipin_trunk>`).

    .. figure:: https://doc.didww.com/_images/voice_trunks.png
      :figclass: align-center
      :alt: Selecting an inbound SIP trunk
      :width: 100%

      **Fig. 8.** Selecting an inbound SIP trunk

Step 2: Assign the Number List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Open the **Number Translations** tab, locate **CLI Number List**, and select the Number List you want to assign.
    2. Click **Submit** to save the changes.

    .. warning::
       Number Lists match inbound caller ID (CLI). If you change the **CLI format** or **CLI prefix** in the :ref:`SIP Trunk <user_panel_sipin_trunk>` settings, update your **Number List** entries to match the new format.

    .. figure:: https://doc.didww.com/_images/sip_trunk.png
      :figclass: align-center
      :alt: Assigning a Number List to a SIP Trunk
      :width: 100%

      **Fig. 9.** Assigning a Number List to a SIP Trunk

.. _user_panel_voice_in_numberlist_assign_pstn:

Assign a Number List to a PSTN Trunk
------------------------------------

Follow these steps to assign a Number List to a **PSTN Trunk**.

Step 1: Open the PSTN Trunk
~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Go to the **Voice > Inbound Trunks** menu.
    2. Choose an existing **PSTN Trunk** or create a new one (see :ref:`PSTN Trunk documentation <user_panel_pstn_trunk>`).

    .. figure:: https://doc.didww.com/_images/pstn1.png
      :figclass: align-center
      :alt: Selecting an inbound PSTN trunk
      :width: 100%

      **Fig. 10.** Selecting an inbound PSTN trunk

Step 2: Assign the Number List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Open the **Number Translations** tab, locate **CLI Number List**, and select the Number List you want to assign.
    2. Click **Submit** to save the changes.

    .. figure:: https://doc.didww.com/_images/pstn2.png
      :figclass: align-center
      :alt: Assigning a Number List to a PSTN Trunk
      :width: 100%

      **Fig. 11.** Assigning a Number List to a PSTN Trunk

----

.. raw:: html

    <br>

Edit or Delete a Number List
============================

To edit or delete an existing **Number List**, such as changing its **name, mode, or default action**, follow these steps:

    1. Go to **Inbound Trunks > Number Lists**.
    2. Locate the list you want to edit or delete.
    3. Click the |actions| button next to the list and choose:

       - **Edit**: Modify the **Friendly Name**, **Mode**, or **Default Action** and click **Update** to save changes.
       - **Delete**: If the list is **not assigned** to a trunk, confirm deletion when prompted.

    .. figure:: https://doc.didww.com/_images/edit_delete_number_lists.png
      :figclass: align-center
      :alt: Editing a Number List
      :width: 100%

      **Fig. 12.** Editing a Number List.

.. important::
   If a **Number List** is assigned to a trunk, it **cannot be deleted**.
   To check where it is in use:

       1. Go to **Inbound Trunks**.
       2. Use the **CLI Number List** filter to find trunks using the list.
       3. Remove the **Number List** from the trunk before attempting deletion.

----

.. raw:: html

    <br>

Edit or Delete Numbers in a Number List
========================================

After adding numbers to a **Number List**, you can modify their settings or remove them as needed. Each number can be configured to **allow or reject calls**, ensuring precise call filtering.

To edit or delete a number in a **Number List**, follow these steps:

    1. Open the **Number List** that contains the number.
    2. Locate the number you want to modify or remove.
    3. Click the |actions| button next to the number and choose:

        - **Edit** to update the number, prefix or its action (**Allow/Reject**), then click **Save**.
        - **Delete** to remove the number and confirm the action.

    .. figure:: https://doc.didww.com/_images/fig5.png
      :figclass: align-center
      :alt: Editing or deleting a number in a Number List
      :width: 100%

      **Fig. 13.** Editing or deleting a number in a Number List.

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_reject_code:

Call Logs & Number List Rejection Codes
========================================

When a call is rejected due to **Number List filtering**, it will appear in the **Inbound Call Logs** with the following error message:

        - **Error code:** 403
        - **Response:** Rejected by trunk settings

This error message in the call logs indicates that the call was blocked by **Number List** settings before it could reach the trunk destination.

.. raw:: html

    <br>

.. raw:: html

   <a id="why_403_error_customer_trunk_not_foudn_occur"></a>
   <h3>Why does this error occur?</h3>

If a number is included in a **Number List** with the action **Reject Call**, the system blocks the call **before routing it to the trunk destination**.

This prevents further call processing, leading to the **403** error.

.. raw:: html

    <br>

.. raw:: html

   <a id="how_to_check_call_logs_rejected_calls_due_to_number_lists"></a>
   <h3>How can I check inbound call rejections caused by a Number List?</h3>

Follow these steps to analyze calls rejected due to a **Number List**:

    1. Navigate to **Logs & Analytics > Call Logs** and select the **Inbound** tab.
    2. Look for calls that failed with the **Rejected by trunk settings** response. (You can also filter by status: **Failed**.)
    3. Check if the caller’s number is listed in your **Number List**.

    .. figure:: https://doc.didww.com/_images/call_logs.png
      :figclass: align-center
      :alt: Call Rejection Error Code
      :width: 100%

      **Fig. 14.** Call Rejection Error Code

.. note:: If you want to **allow** a blocked number, go to your **Number List** settings and change its action to **Allow Call** or remove it from the list.

----

.. raw:: html

    <br>

Additional Resources
====================

.. card:: **Number List Examples & Use Cases**
    :link: user_panel_voice_in_numberlist_examples
    :link-type: ref

    Learn how to configure Number Lists with real-world scenarios, such as blocking spam calls, allowing only specific prefixes, or restricting unwanted callers.

.. card:: **Create a SIP trunk**
    :link: user_panel_sipin_trunk
    :link-type: ref

    Create and configure SIP trunks for inbound calls, set transport protocols, authentication, media options, and more.

.. card:: **Inbound Call Logs**
    :link: inbound_cdr_logs
    :link-type: ref

    Review and analyze your inbound call logs, which provide detailed records of inbound call activity.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow no-lightbox
   :width: 30px
   :height: 30px
   :alt: Actions button

.. toctree::
  :maxdepth: 1
  :hidden:

  Number list examples <number-list-examples.rst>



.. _user_panel_voice_in_numberlist_examples:

Number List Examples & Use Cases
================================

This section provides real-world examples of how to use **Number Lists** to manage inbound call filtering. You'll learn how to add numbers and set rules to allow or block calls based on specific criteria.

With **Number Lists**, you can:

    - **Block unwanted calls** from specific prefixes or numbers.
    - **Allow calls** from specific prefixes or numbers, while blocking all other calls.
    - **Load Balance** your traffic based on the incoming CLI.

Choose one of the following examples:

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **1. Block Calls from a Specific Prefix**
      :link: user_panel_voice_in_numberlist_examples_block_prefix
      :link-type: ref
      :text-align: center

      Learn how to create a number list, which blocks calls from a specific prefix.

   .. grid-item-card:: **2. Block a Specific Phone Number**
      :link: user_panel_voice_in_numberlist_examples_block_number
      :link-type: ref
      :text-align: center

      Learn how to create a number list, which blocks calls from a specific phone number.

   .. grid-item-card:: **3. Allow Calls from Specific Countries and Block Others**
      :link: user_panel_voice_in_numberlist_examples_allow
      :link-type: ref
      :text-align: center

      Learn how to create a number list, which allows calls from a specific prefix, but blocks others.

   .. grid-item-card:: **4. Use Number Lists for Load Balancing**
      :link: user_panel_voice_in_numberlist_examples_lb
      :link-type: ref
      :text-align: center

      Learn how to use number lists as a load balancing tool for different SIP endpoints.

.. note::
   After setting up your **Number List**, make sure to **assign it to an Inbound SIP Trunk** so the call filtering rules take effect. For more details, see the :ref:`Assign a Number List to a SIP Trunk <user_panel_voice_in_numberlist_assign>` guide.

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_examples_block_prefix:

Example 1: Block Calls from a Specific Prefix
----------------------------------------------

**Scenario:** A company receives frequent spam calls from numbers starting with **1234**, disrupting operations. To block these calls follow the steps:

Step 1: Create a Number List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Navigate to **Inbound Trunks > Number Lists**.
    2. Click **Create New** and enter a **friendly name** (e.g., *Spam Blocklist*).
    3. Set the **Mode** to **Prefix Match**.
    4. Set the **Default Action** to **Allow Call**.
    5. Click **Create**.

    .. figure:: https://doc.didww.com/_images/fig7.png
      :figclass: align-center
      :alt: Creating a Number List
      :width: 100%

      **Fig. 1.** Creating a Number List

Step 2: Add the Prefix to the Number List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Click the |actions| button next to the newly created **Number List**.
    2. Select **Manage Numbers**.
    3. Click **Add Numbers**.
    4. Enter **1234** in the input field (this blocks all calls starting with **1234**) and set the action to **Reject Call**.
    5. Click **Submit**.

    .. figure:: https://doc.didww.com/_images/fig8.png
      :figclass: align-center
      :alt: Adding a Prefix to Block Calls
      :width: 100%

      **Fig. 2.** Adding a Prefix to Block Calls

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_examples_block_number:

Example 2: Block a Specific Phone Number
-----------------------------------------

**Scenario:** A customer service agent reports that **15551234567** is making repeated nuisance calls and should be blocked.

Step 1: Create a Number List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Navigate to **Inbound Trunks > Number Lists**.
    2. Click **Create New** and enter a **friendly name** (e.g., *Number Blocklist*).
    3. Set the **Mode** to **Full Numbers Match**.
    4. Set the **Default Action** to **Allow Call**.
    5. Click **Create**.

    .. figure:: https://doc.didww.com/_images/example2_create.png
      :figclass: align-center
      :alt: Creating a Number List for Blocking Specific Numbers
      :width: 80%

      **Fig. 3.** Creating a Number List for Blocking Specific Numbers

Step 2: Add the Number to the List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Click the |actions| button next to the **Number List**.
    2. Select **Manage Numbers**.
    3. Click **Add Numbers**.
    4. Enter **15551234567** in the input field and set the action to **Reject Call**.
    5. Click **Submit**.

    .. figure:: https://doc.didww.com/_images/fig10.png
      :figclass: align-center
      :alt: Adding a Number to Block Calls
      :width: 100%

      **Fig. 4.** Adding a Number to Block Calls

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_examples_allow:

Example 3: Allow Calls from Specific Countries and Block Others
----------------------------------------------------------------

**Scenario:** A company wants to accept calls only from **UK-based (44)** and **German (49)** customers while blocking all other inbound calls.

Step 1: Create a Number List
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Navigate to **Inbound Trunks > Number Lists**.
    2. Click **Create New** and enter a **friendly name** (e.g., *UK & Germany Only*).
    3. Set the **Mode** to **Prefix Match**.
    4. Set the **Default Action** to **Reject Call**.
    5. Click **Create**.

    .. figure:: https://doc.didww.com/_images/fig11.png
      :figclass: align-center
      :alt: Creating a Number List for Country-Based Filtering
      :width: 100%

      **Fig. 5.** Creating a Number List for Country-Based Filtering

Step 2: Add the Allowed Prefixes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Click the |actions| button next to the **Number List**.
    2. Select **Manage Numbers**.
    3. Click **Add Numbers**.
    4. Enter **44, 49** in the input field (this allows calls from the UK and Germany) and set the action to **Allow Call**.
    5. Click **Submit**.

    .. figure:: https://doc.didww.com/_images/fig12.png
      :figclass: align-center
      :alt: Adding Country Codes to Allow Calls
      :width: 100%

      **Fig. 6.** Adding Country Codes to Allow Calls

----

.. raw:: html

    <br>

.. _user_panel_voice_in_numberlist_examples_lb:

Example 4: Use Number Lists for Load Balancing
----------------------------------------------

**Scenario:** A global service provider needs to route incoming calls based on the caller's country code (CLI prefix), while using a single DID number.

**Solution:** To manage this, the provider assigns specific number lists to trunks within a trunk group. The system uses the CLI prefix to match the call to the correct number list and selects the appropriate trunk for routing.

For example:

    - Calls from the United States (prefix ``1``) are routed to a US-based trunk.
    - Calls from the United Kingdom (prefix ``44``) are routed to a UK-based trunk.

This setup enables efficient load balancing and region-specific routing while maintaining a single DID.

Step 1: Create Number Lists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Go to **Inbound Trunks > Number Lists**.
    2. Click **Create New** and enter a **friendly name** (e.g., *US Source Filter*).
    3. Set the **Mode** to **Prefix Match**.
    4. Set the **Default Action** to **Reject Call**.
    5. Click **Create**.

    .. figure:: https://doc.didww.com/_images/fig1e4.png
      :figclass: align-center
      :alt: Creating a Number List for Load Balancing - US
      :width: 100%

      **Fig. 7.** Creating a Number List for Load Balancing (US)

    6. Click the |actions| button next to the **US Source Filter** Number List.
    7. Select **Manage Numbers**.
    8. Click **Add Numbers**.
    9. Enter **1** and set the action to **Allow Call**.
    10. Click **Submit**.

    .. figure:: https://doc.didww.com/_images/fig2e4.png
      :figclass: align-center
      :alt: Adding US Prefix
      :width: 100%

      **Fig. 8.** Adding 1 Prefix for US

    11. Repeat the steps above to create a second list named *UK Source Filter* and add prefix **44**.

    .. figure:: https://doc.didww.com/_images/fig3e4.png
      :figclass: align-center
      :alt: UK and US Source Filter Number Lists
      :width: 100%

      **Fig. 9.** UK and US Source Filter Number Lists

Step 2: Assign Number Lists to Trunks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To assign the number lists to trunks see the :ref:`Assign a Number List to a SIP Trunk <user_panel_voice_in_numberlist_assign>` guide or follow these steps:

    1. Go to **Voice > Inbound Trunks**
    2. Edit an existing trunk or :ref:`create a new trunk <user_panel_sipin_trunk>`.
    3. Open the **Number Translations** tab and locate **CLI Number List**.
    4. Select the **Number List** you want to assign and click **Submit** to save the changes.
    5. Repeat the steps above for both trunks.

    .. figure:: https://doc.didww.com/_images/fig4e4.png
      :figclass: align-center
      :alt: Assign the Number Lists to Trunks
      :width: 100%

      **Fig. 10.** Assign the Number Lists to Trunks

Step 3: Create a Trunk Group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To create a trunk group see the :ref:`create a trunk group <user_panel_trunk_group>` guide or follow these steps:

    1. Go to **Voice > Inbound Trunks**.
    2. Click **Create New** and select **Trunk Group**.
    3. Enter the trunk group **Name**.
    4. In **Trunks**, add **US SIP Trunk** and **UK SIP Trunk**, then click **Create**.

    .. figure:: https://doc.didww.com/_images/fig5e4.png
      :figclass: align-center
      :alt: Create a Trunk Group
      :width: 100%

      **Fig. 11.** Create a Trunk Group.

Step 4: Assign the Trunk Group to a DID Number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1. Navigate to **Phone Numbers > My Numbers**.
    2. Select the desired **DID number** and click on the voice trunk field.

    .. note:: If the DID has no trunks assigned, the trunk field will display ``Voice: none``.

    3. Assign the **Load Balancing Trunk Group** and click **Confirm**.

    .. figure:: https://doc.didww.com/_images/fig6e4.png
      :figclass: align-center
      :alt: Assigning the Trunk Group to a DID Number.
      :width: 100%

      **Fig. 12.** Assigning the Trunk Group to a DID Number

Result
~~~~~~

    - Calls with prefix ``1`` (US) are routed to **US SIP Trunk**.
    - Calls with prefix ``44`` (UK) are routed to **UK SIP Trunk**.
    - All other calls are rejected by default.

This setup allows a single DID number to intelligently route incoming traffic to country-specific trunks, improving routing efficiency and regional control.

.. tip:: Scale the trunk group to include as many trunks and number lists as needed to achieve traffic load balancing in expected countries or regions.

----

.. raw:: html

    <br>

Additional Resources
====================

.. card:: **Inbound Number List**
    :link: user_panel_voice_in_numberlist
    :link-type: ref

    Learn how to create, configure, and manage Number Lists to filter inbound calls by allowing or rejecting specific numbers or prefixes linked to SIP trunks.

.. card:: **Create a SIP trunk**
    :link: user_panel_sipin_trunk
    :link-type: ref

    Create and configure SIP trunks for inbound calls, set transport protocols, authentication, media options, and more.

.. card:: **Create a Trunk Group**
    :link: user_panel_trunk_group
    :link-type: ref

    Discover how to create and configure a trunk group for failover and load balancing purposes.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow no-lightbox
   :width: 30px
   :height: 30px
   :alt: Actions button


.. _trunks_settings:

================
Routing Settings
================

The Routing Settings allow you to configure your desired (:ref:`Preferred Servers <presence>`) that you would like to use with your trunks.

To select Point of Presence (POP), select "Routing Settings" in Voice > Inbound Trunks section (Fig. 1):

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Inbound Trunks window

A window will open with available DIDWW servers, which can be enabled/disabled for Preferred Servers list (Fig. 2):

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** Preferred Routing Settings window

.. note::
  If each or few of DIDWW POPs are selected in Preferred Routing, make sure that your server is configured to accept traffic from their :ref:`designated IPs <service_did_sip>`

========================
Technical Specifications
========================

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`device-mobile` **SIP**
      :link: sip
      :link-type: doc
      :text-align: left

      Learn about SIP setup, IP ranges, ports, encryption, codecs, and DTMF support.

   .. grid-item-card:: :octicon:`file` **Call Logs & Response Codes**
      :link: call-logs-response-codes
      :link-type: doc
      :text-align: left

      View and interpret call log response codes to troubleshoot call issues.

   .. grid-item-card:: :octicon:`id-badge` **Caller ID Formats**
      :link: caller-id-formats
      :link-type: doc
      :text-align: left

      Learn about supported Caller ID formats (RAW, E.164, LOCAL) and how to customize them per trunk using CLI Prefix.

   .. grid-item-card:: :octicon:`sync` **Failover**
      :link: failover
      :link-type: doc
      :text-align: left

      Learn how DIDWW handles SIP failover and load balancing using DNS SRV and trunk groups for high availability.

   .. grid-item-card:: :octicon:`inbox` **Fax Services**
      :link: fax-services
      :link-type: doc
      :text-align: left

      Set up fax over IP using T.38 or G.711 protocols.

   .. grid-item-card:: :octicon:`shield-check` **STIR/SHAKEN**
      :link: stir-shaken
      :link-type: doc
      :text-align: left

      Learn about caller ID authentication and STIR/SHAKEN compliance.

   .. grid-item-card:: :octicon:`broadcast` **Toll-Free Dialing Format**
      :link: tfdialscheme
      :link-type: doc
      :text-align: left

      View country-specific formats for dialing Toll-Free DIDs.

   .. grid-item-card:: :octicon:`globe` **UIFN Dialing Format**
      :link: uifndialscheme
      :link-type: doc
      :text-align: left

      View country-specific dialing formats for Universal International Freephone Numbers.

   .. grid-item-card:: :octicon:`cpu` **CPC Usage**
      :link: cpc-usage
      :link-type: doc
      :text-align: left

      Understand CPC values for toll-free calls and their role in call routing and billing.

   .. grid-item-card:: :octicon:`arrow-switch` **Inbound Call Redirection Methods**
      :link: redirecting-calls
      :link-type: doc
      :text-align: left

      Redirect inbound calls using 30x and REFER methods.

.. toctree::
   :maxdepth: 1
   :hidden:

   sip.rst
   call-logs-response-codes.rst
   caller-id-formats.rst
   failover.rst
   fax-services.rst
   stir-shaken.rst
   tfdialscheme.rst
   uifndialscheme.rst
   cpc-usage.rst
   redirecting-calls.rst

.. toctree::
   :maxdepth: 1

.. _service_did_sip:

=======================
General SIP Information
=======================

SIP Signaling Addresses
-----------------------

DIDWW may originate inbound calls to your SIP endpoint using two delivery methods:

- **Static SIP URI**
- **SIP Registration**

Each method uses different SIP endpoints.

Static SIP URI
^^^^^^^^^^^^^^^

When forwarding calls to your equipment using a **static SIP URI**, calls will originate from the following DIDWW SIP endpoints:

============ ==================== ====================
Location      IPv4 address        IPv6 address
============ ==================== ====================
New York      46.19.209.14        2a01:ad00:1:14::14
Frankfurt     46.19.210.14        2a01:ad00:2:14::14
Los Angeles   46.19.212.14        2a01:ad00:4:14::14
Miami         46.19.213.14        2a01:ad00:5:14::14
Singapore     46.19.214.14        2a01:ad00:6:14::14
Hong Kong     46.19.215.14        2a01:ad00:7:14::14
Amsterdam    185.238.173.14       2a01:ad00:8:14::14
============ ==================== ====================

SIP Registrars
^^^^^^^^^^^^^^

When using **SIP Registration** to dynamically register your SIP trunk, configure your system to register to one of the following DIDWW SIP registrar hostnames.

Use ``sip.didww.com`` for automatic DNS-based load balancing between locations, or select a regional hostname to force registration to a specific location.

+----------------------+----------------------+------------------------+
| Host                 | IPv4 address         | IPv6 address           |
+======================+======================+========================+
|                      | 46.19.209.49         | 2a01:ad00:1:1::49      |
| sip.didww.com        +----------------------+------------------------+
|                      | 185.238.173.49       | 2a01:ad00:8:1::49      |
+----------------------+----------------------+------------------------+
| nyc.sip.didww.com    | 46.19.209.49         | 2a01:ad00:1:1::49      |
+----------------------+----------------------+------------------------+
| ams.sip.didww.com    | 185.238.173.49       | 2a01:ad00:8:1::49      |
+----------------------+----------------------+------------------------+

----

.. raw:: html

    <br>

SIP Signaling Source Ports
--------------------------

DIDWW originates inbound SIP signaling using the following **source ports**, regardless of whether SIP URI delivery or SIP Registration is used:

- **UDP:** source port ``5060``
- **TCP / TLS:** dynamic source ports ``5070–65535``

Ensure that your firewall or SBC allows SIP signaling from the DIDWW signaling IP addresses listed in the sections above.

----

.. raw:: html

    <br>

RTP addresses
-------------

Our system sends RTP packets from the following subnets:

* 46.19.208.0/21
* 185.238.172.0/22
* 2a01:ad00:1:2::/64
* 2a01:ad00:1:14::/64
* 2a01:ad00:2:1::/64
* 2a01:ad00:2:14::/64
* 2a01:ad00:4::/64
* 2a01:ad00:4:14::/64
* 2a01:ad00:5::/64
* 2a01:ad00:5:14::/64
* 2a01:ad00:6::/64
* 2a01:ad00:6:14::/64
* 2a01:ad00:7:1::/64
* 2a01:ad00:7:14::/64
* 2a01:ad00:8:1::/64
* 2a01:ad00:8:14::/64

with RTP port-range: 1024-65535

----

.. raw:: html

    <br>

RTCP
----

We transmit and receive RTCP packets from port = rtp_port + 1 (as recommended in `RFC3550 <https://tools.ietf.org/html/rfc3550#section-11>`_).
Additionally, we are able to receive RTCP packets on the same port as RTP, considering utilizing RTCP conflicts avoidance payloads (payload types 72-76).

----

.. raw:: html

    <br>

SIP OPTIONS
-----------

DIDWW is responding on SIP OPTIONS while sending requests to signaling IPs. It will respond on UDP 5060, TCP 5060 and TLS 5061 ports.

Please note that SIP OPTIONS responses are not related to call processing.

----

.. raw:: html

    <br>

Encryption
----------

Our system supports **TLS** for secure **SIP signaling transport** and `SRTP <https://en.wikipedia.org/wiki/Secure_Real-time_Transport_Protocol>`_ for media encryption.

Supported SRTP key negotiation mechanisms:
    - `SDES <https://en.wikipedia.org/wiki/SDES>`_
    - `DTLS <https://tools.ietf.org/html/rfc5764>`_
    - `ZRTP <https://en.wikipedia.org/wiki/ZRTP>`_

.. note::
   - Encryption applies only to the **DIDWW ↔ Customer** call leg. Encryption is not maintained end-to-end, and any other call legs outside this connection are not encrypted.

----

.. raw:: html

    <br>

.. _service_did_sip_codecs:

Supported codecs
----------------

  .. list-table::
     :widths: 20 80
     :header-rows: 1

     * - Option
       - Description
     * - **PCMU**
       - G.711 μ-law audio codec.
     * - **PCMA**
       - G.711 A-law audio codec.
     * - **G729**
       - G.729 audio codec.
     * - **G723**
       - G.723.1 audio codec.
     * - **L16**
       - Linear PCM audio codec.
     * - **G726-16**, **G726-24**, **G726-32**, **G726-40**
       - G.726 audio codec at the selected bit rate.
     * - **G721**
       - G.721 audio codec.
     * - **GSM**
       - GSM Full Rate audio codec.
     * - **Speex**
       - Speex audio codec.
     * - **telephone-event**
       - RTP payload used for RFC 2833 DTMF events.

----

.. raw:: html

    <br>

.. _service_did_sip_dtmf:

DTMF transport methods
----------------------

DTMF signaling is supported as follows:

* Telephone-event `RFC2833 <https://tools.ietf.org/html/rfc2833>`_
* SIP INFO `draft-kaplan-dispatch-info-dtmf-package-00 <https://tools.ietf.org/html/draft-kaplan-dispatch-info-dtmf-package-00>`_

    * application/dtmf-relay
    * application/dtmf

By default RFC 2833 enabled



.. _inbound_technical_sip_response_codes_in_call_logs:

===============================
SIP Response Codes in Call Logs
===============================

SIP response codes in Call Logs provide detailed information about how inbound calls were processed. These codes help identify call failures, SIP signaling issues, redirection events, and other outcomes, making them essential for troubleshooting and analyzing call behavior.

.. raw:: html

    <br>

SIP Response Code Categories
-----------------------------

SIP response code groups follow :rfc:`3261` and categorize call outcomes based on the type of SIP signaling response.

.. list-table::
   :header-rows: 1
   :widths: 5 9 49

   * - Code
     - Category
     - Description
   * - 2xx
     - Successful
     - The request succeeded and the call was answered or completed normally.
   * - 3xx
     - Redirection
     - Additional routing or redirection is required to complete the request.
   * - 4xx
     - Client Error
     - The request could not be processed due to an issue on the caller or endpoint side (e.g., 400, 403, 404).
   * - 5xx
     - Server Error
     - The destination server encountered an internal error or is unable to process the request.
   * - 6xx
     - Global Failure
     - The request cannot be completed by any destination.

.. raw:: html

    <br>

Disconnect Initiator
--------------------

Call Logs include a Disconnect Initiator that indicates which side ended the call.

.. list-table::
   :header-rows: 1
   :widths: 10 70

   * - Value
     - Description
   * - System
     - The DIDWW platform terminated the call due to configuration limits, timeout, or insufficient balance, or internal logic.
   * - Origination
     - The calling party or upstream network terminated the call before or during delivery.
   * - Destination
     - The customer’s SIP endpoint terminated the call.

.. raw:: html

    <br>

SIP Response Codes
--------------------

.. xlsx-table::
   :file: disconnect-codes-corrected.xlsx
   :header-rows: 1


.. |br| raw:: html

  <br>

.. _call_transfers_use_cases:

Configure Call Transfers
========================

Transfer inbound calls to a new destination (PSTN number or SIP URI) using either a **30x Redirect** SIP response or an in-dialog **SIP REFER** request. This enables call routing decisions to be made dynamically during call handling rather than being fixed in advance.

Transfers are typically triggered by a SIP system such as a PBX, IVR, AI agent, or custom application when a call needs to be forwarded, escalated, or handed off to another destination. In this case, the system sends a **30x** response or a **REFER** request, and a new outbound call is initiated to the target destination using the configured :ref:`Outbound Trunk <outbound_trunk_create_trunk>`.

To use call transfers, both **Inbound** and **Outbound** SIP trunks must be configured, and the platform must be capable of generating valid SIP signaling for the selected transfer method.

.. note::
   For protocol-level details, examples, and diagrams, see :ref:`Inbound Call Redirection Methods <user_panel_call_redirection_outbound>`.

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: :octicon:`arrow-up-right` **1. Create Outbound SIP Trunk**
      :link: call_transfers_outbound_trunk
      :link-type: ref
      :text-align: left

      Create the outbound trunk DIDWW will use to place the redirected or transferred call.

   .. grid-item-card:: :octicon:`arrow-down-left` **2. Create Inbound SIP Trunk**
      :link: call_transfers_inbound_trunk
      :link-type: ref
      :text-align: left

      Create the inbound trunk, enable the required transfer method, and link it to the outbound trunk using the same credentials.

   .. grid-item-card:: :octicon:`arrow-switch` **3. Configure Your SIP Platform**
      :link: call_transfers_platform
      :link-type: ref
      :text-align: left

      Configure your platform to transfer calls using SIP 30x Redirect or SIP REFER.

----

.. _call_transfers_outbound_trunk:

1. Create Outbound SIP Trunk
----------------------------

To enable call transfers, the outbound SIP trunk must be configured to accept signaling from **DIDWW Inbound SIP IPs**. This allows a new outbound call to be initiated to the transfer destination when a **30x Redirect** or **SIP REFER** request is received.

The outbound trunk must use **Credentials & IP-Based** authentication, and the same credentials are reused by the inbound trunk to authorize transfer-related signaling.

Before You Begin
^^^^^^^^^^^^^^^^

Access to DIDWW outbound trunks is required. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`. |br|

Step 1: Open Outbound Trunks and Start Creation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/outbound1.png
  :figclass: align-center
  :alt: Opening Outbound Trunks and starting outbound trunk creation
  :width: 100%

  **Fig. 1.** Opening Outbound Trunks and starting outbound trunk creation

Step 2: Configure and Create the Outbound SIP Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Enter a descriptive **Name** (for example, ``Call Transfers``).
2. Keep **Credentials & IP-Based** authentication selected.
3. In **Allowed SIP IP addresses**, allow:

   - Your SIP platform’s **outbound SIP signaling IPs**, if your system uses fixed IP addresses
   - The :ref:`DIDWW inbound SIP IPs <service_did_sip>`, required for call redirection and transfers

   Copy the full DIDWW inbound SIP IP list below, based on your IP version:

.. tab-set::
   :class: my-tabs

   .. tab-item:: IPv4

      ::

         46.19.209.14 46.19.210.14 46.19.212.14 46.19.213.14 46.19.214.14 46.19.215.14 185.238.173.14

   .. tab-item:: IPv6

      ::

         2a01:ad00:1:14::14 2a01:ad00:2:14::14 2a01:ad00:4:14::14 2a01:ad00:5:14::14 2a01:ad00:6:14::14 2a01:ad00:7:14::14 2a01:ad00:8:14::14

4. Click **Create** to save the trunk.

.. warning::
    - You can allow all traffic by adding ``0.0.0.0/0``, which removes all IP restrictions. Although SIP Digest Authentication will still verify requests using valid credentials, this configuration is **not recommended**. Always restrict access to known signaling IPs whenever possible.

    - For advanced outbound SIP trunk configuration, see :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/outbound2.png
   :figclass: align-center
   :alt: Configuring and creating the outbound SIP trunk for call transfers
   :width: 100%

   **Fig. 2.** Configuring and creating the outbound SIP trunk for call transfers

.. _call_transfers_outbound_copy_credentials:

Step 3: View Outbound Trunk Credentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When the outbound trunk is created, you can view its credentials by selecting the key icon in the Credentials column on the Outbound Trunks page.

1. Go to **Voice > Outbound Trunks**.
2. Locate your outbound trunk and click the **key icon** in the **Credentials** column.
3. The trunk credentials will appear, showing the **Username** and **Password**
   (click the **eye icon** to reveal the password).

.. note::
   - These credentials will be reused in the :ref:`Authorization <call_transfers_inbound_auth>` tab of the inbound SIP trunk to authorize call redirection and transfers via the outbound trunk.
   - The same credentials must also be used by your SIP platform for outbound SIP authentication.

.. figure:: https://doc.didww.com/_images/outbound3.png
  :figclass: align-center
  :alt: Viewing outbound trunk credentials for reuse on the inbound trunk
  :width: 100%

  **Fig. 3.** Viewing outbound trunk credentials for reuse on the inbound trunk

----

.. _call_transfers_inbound_trunk:

2. Create Inbound SIP Trunk
---------------------------

To process call transfer requests, the inbound SIP trunk must be configured to authorize **30x Redirect** responses or **SIP REFER** requests generated during call handling. This ensures that transfer signaling is accepted and validated before a new outbound call is initiated.

The inbound trunk must use the same **IP version** (IPv4 or IPv6) as the outbound trunk, have **Authorization** enabled, and reuse the **same credentials** configured on the outbound SIP trunk. The required transfer method (**30x Redirect** or **SIP REFER**) must also be enabled.

Before You Begin
^^^^^^^^^^^^^^^^

- At least one DID number is required to receive inbound calls. |br|
- You need the outbound trunk **Username** and **Password** from :ref:`Step 3 <call_transfers_outbound_copy_credentials>`.

Step 1: Open Inbound Trunks and Start Creation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/inbound1.png
  :figclass: align-center
  :alt: Opening Inbound Trunks and starting inbound SIP trunk creation
  :width: 100%

  **Fig. 4.** Opening Inbound Trunks and starting inbound SIP trunk creation

Step 2: Configure General Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the **General** tab, enter a descriptive **Name** (for example, ``Call Transfers``).
2. Select **Static Endpoint**.
3. Configure your platform destination (**Host**), **Transport**, and **Port** as required by your platform.
4. In **Network Protocol**, select the IP version that matches the outbound trunk configuration.

.. important::
   The **Network Protocol** on the inbound trunk must **match** the IP addresses allowed on the outbound trunk. |br|

   - If the outbound trunk allows **IPv4** addresses, set the inbound trunk to **IPv4 only**
   - If the outbound trunk allows **IPv6** addresses, set the inbound trunk to **IPv6 only**

   A mismatch between IP versions will prevent call transfers from completing successfully.

.. figure:: https://doc.didww.com/_images/inbound2.png
  :figclass: align-center
  :alt: Configuring inbound trunk general settings and network protocol
  :width: 100%

  **Fig. 5.** Configuring inbound trunk general settings and network protocol

.. _call_transfers_inbound_auth:

Step 3: Enable and Configure Authorization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To authorize redirect/transfer requests, inbound trunk authorization must be enabled using the **same credentials** as the outbound trunk.

1. Open the **Authorization** tab.
2. Turn on **Enable Authorization**.
3. Paste the **Auth User** and **Auth Password** values copied from the outbound trunk credentials
   (see :ref:`View Outbound Trunk Credentials <call_transfers_outbound_copy_credentials>`).

.. note::
   DIDWW uses these credentials to authenticate the outbound leg initiated after a redirect or transfer request.

.. figure:: https://doc.didww.com/_images/inbound3.png
  :figclass: align-center
  :alt: Enabling authorization and pasting outbound trunk credentials on the inbound trunk
  :width: 100%

  **Fig. 6.** Enabling authorization and pasting outbound trunk credentials on the inbound trunk

Step 4: Enable Call Transfer Method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configure signaling limits based on the transfer method you plan to use.

.. tab-set::
   :class: my-tabs
   :sync-group: transfer-method

   .. tab-item:: SIP REFER
      :sync: refer

      Enable support for in-dialog SIP REFER transfers.

      1. Open the **Signalling** tab.
      2. Set **Max Transfers** to **1** or higher.

      .. important::
         If **Max Transfers** is set to ``0``, SIP REFER requests will be rejected.

      .. figure:: https://doc.didww.com/_images/inbound4_refer.png
        :figclass: align-center
        :alt: Enabling Max Transfers for SIP REFER on the inbound SIP trunk
        :width: 100%

        **Fig. 7.** Enabling Max Transfers for SIP REFER on the inbound SIP trunk

   .. tab-item:: 30x Redirect
      :sync: redirect

      Enable support for SIP 3xx redirect responses.

      1. Open the **Signalling** tab.
      2. Set **Max 30x Redirects** to **1** or higher.

      .. important::
         If **Max 30x Redirects** is set to ``0``, SIP redirect responses will be rejected.

      .. figure:: https://doc.didww.com/_images/inbound4_30x.png
        :figclass: align-center
        :alt: Enabling Max 30x Redirects on the inbound SIP trunk
        :width: 100%

        **Fig. 8.** Enabling Max 30x Redirects on the inbound SIP trunk

Step 5: Create the Trunk
^^^^^^^^^^^^^^^^^^^^^^^^

Click **Create** to save the inbound SIP trunk.

.. figure:: https://doc.didww.com/_images/inbound5.png
  :figclass: align-center
  :alt: Creating the inbound SIP trunk for call transfers
  :width: 100%

  **Fig. 9.** Creating the inbound SIP trunk for call transfers

Step 6: Assign the Inbound SIP Trunk to Your DID Numbers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Inbound calls can be redirected/transferred only after the DID number is routed to the inbound trunk.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number(s) you want to assign to the inbound SIP trunk.
3. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/inbound6.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 10. Selecting **Update Trunks** from the Batch Actions menu

4. From the dropdown menu, choose the **Call Transfers** trunk you created earlier.
5. Click **Confirm** to apply the changes.

.. figure:: https://doc.didww.com/_images/inbound7.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 11. Assigning the newly created SIP trunk to the selected DID(s)

----

.. _call_transfers_platform:

3. Configure Your SIP Platform
------------------------------

Configure your SIP platform (PBX, IVR, AI agent, or custom SIP application) to instruct DIDWW to redirect or transfer inbound calls.

Before You Begin
^^^^^^^^^^^^^^^^

- Identify the appropriate DIDWW outbound signaling endpoint to use (e.g., ``fra.eu.out.didww.com``). See :ref:`Signaling Endpoints <voice-out-signaling-endpoints>`.
- Ensure your SIP platform supports generating **SIP 30x responses** or **in-dialog SIP REFER requests**.

Step 1: Build the Destination SIP URI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Your SIP platform must construct the transfer destination as a SIP URI in the following format::

   sip:NEW_PSTN_NUMBER@<outbound_endpoint>

Where:

- ``NEW_PSTN_NUMBER`` is the destination number in E.164 format
- ``<outbound_endpoint>`` is a DIDWW outbound signaling endpoint (for example, ``fra.eu.out.didww.com``)

.. note::
   This SIP URI must be included in the **Contact** header for SIP 30x redirects,
   or in the **Refer-To** header for SIP REFER transfers.

Step 2: Configure Call Transfers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

During inbound call handling, your SIP platform must trigger the transfer by sending the appropriate SIP signaling request or response to DIDWW.

.. tab-set::
   :class: my-tabs
   :sync-group: transfer-method

   .. tab-item:: SIP REFER
      :sync: refer

      Use this method when the call must be **answered first** before performing the call transfer.

      1. Answer the inbound call to establish a SIP dialog.
      2. Send an in-dialog SIP **REFER** request to DIDWW.
      3. Include the destination SIP URI in the **Refer-To** header::

            Refer-To: <sip:1234567890@fra.eu.out.didww.com>

      4. Wait for DIDWW to respond with ``200 OK`` or ``202 Accepted``.

      DIDWW then initiates a new outbound call using your **Outbound SIP Trunk**.

      For protocol details and examples, see :ref:`REFER Transfer Method <call_redirection_refer>`.

   .. tab-item:: 30x Redirect
      :sync: redirect

      Use this method when the transfer destination can be determined **before answering the call**.

      1. Receive the inbound SIP ``INVITE`` from DIDWW.
      2. Do **not** answer the call.
      3. Respond with a SIP **3xx** response (for example, ``302 Moved Temporarily``).
      4. Include the destination SIP URI in the **Contact** header::

            Contact: <sip:1234567890@fra.eu.out.didww.com>

      5. DIDWW validates the redirect and initiates a new outbound call using your **Outbound SIP Trunk**.

      For protocol details and examples, see :ref:`30x Redirect Method <call_redirection_302>`.

Step 3: Make a Test Call and Verify Call Transfer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verify that call transfers work as expected based on the method used.

.. tab-set::
   :class: my-tabs
   :sync-group: transfer-method

   .. tab-item:: SIP REFER
      :sync: refer

      1. Place a call to your DIDWW number routed to your SIP platform.
      2. Ensure the call is answered to establish a SIP dialog.
      3. Trigger a SIP **REFER** transfer from your platform.
      4. Confirm the original call leg ends and a new outbound call is established.

   .. tab-item:: 30x Redirect
      :sync: redirect

      1. Place a call to your DIDWW number routed to your SIP platform.
      2. Ensure the call is **not answered** by your platform.
      3. Confirm a SIP **3xx** response is sent.
      4. Verify the call is redirected and two-way audio is established with the destination.

.. note::
    Review the :ref:`Inbound <inbound_cdr_logs>` and :ref:`Outbound <outbound_cdr_logs>` **CDR Logs** to verify call flow details and confirm that the outbound leg was initiated successfully. |br|
    If you encounter issues during testing, contact **DIDWW Support** at support@didww.com.


Caller ID Formats
=================

You can edit Caller ID format settings in the **Voice > Inbound Trunks** section. Each SIP trunk you create can have its own Caller ID settings. The available Caller ID formats are:

    .. list-table::
       :header-rows: 1

       * - Format
         - Description
         - Example
       * - **RAW**
         - Sends the Caller ID exactly as it is received from the originating side.
         - Caller ID is sent without modification.
       * - **E.164**
         - Sends the Caller ID in the format `+<Country Code><Area Code><Number>`.
         - `+1 212 5551234` (United States, Country Code: `1`, Area Code: `212`, Number: `5551234`)
       * - **LOCAL**
         - Sends the Caller ID in the local format `<Area Code><Number>`.
         - `212 5551234` (Area Code: `212`, Number: `5551234`)

To further modify the Caller ID, use the **CLI Prefix** input field (Fig 1.). This setting allows you to add a prefix to the Caller ID. For example, if you specify the `+` symbol, it will be added at the beginning of every received Caller ID.

.. figure:: https://doc.didww.com/_images/CLI_prefix.png
    :figclass: align-center
    :alt: Inbound Trunk CLI Prefix
    :width: 60%

    **Fig. 1.** Inbound Trunk CLI Prefix

.. note::
    DIDWW ensures the accurate transfer of Caller ID (CLI) for all local calls. However, the accurate transfer of international Caller IDs may not always be guaranteed due to factors beyond DIDWW's control, such as third-party provider limitations.


.. _upcpc:

=========
CPC Usage
=========

Calling Party Category (**CPC**) values identify the type of network or device from which a call originates. CPC information can be delivered either within the **SIP URI** or in the **From header** of SIP INVITE messages.

.. important::

   CPC delivery is disabled by default.
   To enable it, you may need to either configure your SIP trunk manually
   (see :ref:`CPC in SIP URI configuration <upcpc_trunk_config>`)
   or request support activation for CPC delivery in the **From header**
   (see :ref:`CPC in From Header <upcpc_from_header>`).

----

CPC in a SIP URI
================

This method delivers the **CPC value** as part of the **SIP URI**, allowing you to identify the call source type directly from the request URI.

.. note::
   CPC in SIP URI is supported for **Toll-Free** numbers only.

CPC Values
-----------

The following CPC values indicate the source type of the incoming call:

.. list-table::
   :widths: 20 50
   :header-rows: 1

   * - **CPC Value**
     - **Source Type**
   * - ``01``
     - Standard landline
   * - ``02``
     - Mobile network
   * - ``03``
     - Public payphone
   * - ``04``
     - Unclassified or unavailable source

SIP URI Format and Examples
---------------------------

The CPC (Calling Party Category) value can be added **before or after** the DID, depending on the placeholder position, but it always appears before the “@” symbol in the SIP URI.

.. code-block:: text

   {DID}{CALL_CPC}@my.domain.com
   {CALL_CPC}{DID}@my.domain.com

**Examples:**

The examples below show how the DID ``18003864279`` is formatted in SIP URIs, with the last two digits representing the **CPC** value.

.. code-block:: text

   Landline source number: 1800386427901@my.domain.com
   Mobile source number:   1800386427902@my.domain.com
   Payphone source number: 1800386427903@my.domain.com
   Unknown source number:  1800386427904@my.domain.com

.. _upcpc_trunk_config:

SIP Trunk Configuration
-----------------------

To enable this feature, include the ``{CALL_CPC}`` variable in **User Part of R-URI** on the SIP trunk's **General** tab.

1. Navigate to **Voice → Inbound Trunks** in the User Panel.
2. :ref:`Edit an existing inbound SIP trunk <user_panel_sipin_trunk_edit>`.
3. Open the **General** tab and enter the ``{CALL_CPC}`` variable in **User Part of R-URI**.
4. Click **Submit** to save the changes.

.. note::
    - If you do not have an existing SIP trunk, :ref:`create a new one <user_panel_sipin_trunk>`.
    - Additional variables such as ``{DID}`` or custom symbols can be configured in addition to the ``{CALL_CPC}`` variable.

.. figure:: https://doc.didww.com/_images/cpc.png
  :figclass: align-center
  :alt: Inbound SIP trunk General tab with the CALL_CPC variable in User Part of R-URI
  :width: 80%

  **Fig. 1.** Inbound SIP Trunk configuration with ``{CALL_CPC}`` variable.

----

.. _upcpc_from_header:

CPC in From Header
==================

This method delivers the **CPC value** within the **From** header of the SIP INVITE message, allowing you to identify the call source type directly from SIP signaling.
In this case, CPC values are represented in text format, for example: ``<ordinary>``.

.. note::
   CPC delivery in the **From** header is **not enabled by default**.
   To enable this feature for your inbound SIP trunks, please contact support@didww.com.

CPC Values
-----------

The following CPC values indicate the source type of the incoming call when included in the **From** header:

.. list-table::
   :widths: 20 50
   :header-rows: 1

   * - **CPC Value**
     - **Source Type**
   * - ``<ordinary>``
     - Standard landline
   * - ``<cellular>``
     - Mobile network
   * - ``<payphone>``
     - Public payphone
   * - ``<unknown>``
     - Unclassified or unavailable source

From Header Format and Example
------------------------------

In this configuration, the **CPC** value is included as a parameter in the SIP **From** header.

.. code-block:: text

   From: <sip:{DID}@your.sip.domain;cpc=value>;tag=12345

**Example:**

This example shows a call from a **standard landline**, where the ``cpc=ordinary`` parameter identifies the calling party category.

.. code-block:: text

   From: <sip:14039351222@46.19.209.14;cpc=ordinary>;tag=12345

----

Additional Resources
======================

.. card:: **Create a SIP trunk**
    :link: user_panel_sipin_trunk
    :link-type: ref

    Create and configure SIP trunks for inbound calls, set transport protocols, authentication, media options, and more.

.. card:: **Service Failover and Load Balancing**
    :link: service_did_failover
    :link-type: ref

    Understand how to configure trunk groups for failover and load balancing.


.. _service_did_failover:

===================================
Service Failover and Load Balancing
===================================

DIDWW provides mechanisms for **failover and load balancing** between its system and customer equipment. These mechanisms include **DNS SRV** for SIP-based failover and **Trunk Groups** for managing multiple SIP trunks efficiently.

----

.. raw:: html

   <br>

DNS SRV
=======

The `DNS SRV <https://en.wikipedia.org/wiki/SRV_record>`_ mechanism is fully supported by the DIDWW system. Using DNS SRV, calls can be directed to a customer-defined DNS SRV record, which specifies multiple destinations and their respective priorities for failover.

How It Works
------------

For **UDP SIP transport**, the system resolves the following record:

    .. code-block:: console

        _sip._udp.<customer.domain>

For **TCP SIP transport**, the system resolves the following record:

    .. code-block:: console

        _sip._tcp.<customer.domain>

For **TLS SIP transport**, the system resolves the following record:

    .. code-block:: console

        _sip._tls.<customer.domain>

In all cases, **<customer.domain>** corresponds to the trunk :ref:`host <user_panel_sip_trunk_host>` value.

Enabling DNS SRV for SIP Trunks
-------------------------------

To enable DNS SRV for SIP trunks, leave the :ref:`port <user_panel_sip_trunk_port>` field **empty**.

    .. note::
            The DNS SRV mechanism operates at the **SIP transaction layer**. If a failover occurs, a **new Call Detail Record (CDR)** is generated for each attempt.

----

.. raw:: html

   <br>

Trunk Groups
============

Trunk Groups allow customers to bundle multiple SIP trunks, distributing traffic for DID numbers across multiple gateways. This feature provides flexible configuration options for failover and load balancing.

Configuration Options
---------------------

You can configure the following parameters to manage Trunk Groups effectively:

    - **Priority:** Set the order in which trunks in the group are tried. Trunks with lower values are tried first.
    - **Weight:** Control call distribution between trunks that have the same priority. Trunks with higher values are selected more often.
    - **Ringing Timeout:** Set the maximum time to wait for a response from a trunk.
    - **Re-routing Disconnect Codes:** Select the disconnect codes that trigger routing to another trunk in the group.
    - **Capacity Limit:** Limit the number of simultaneous calls per trunk.

Call Detail Records (CDRs)
--------------------------

For each call termination attempt within a Trunk Group, DIDWW generates a separate **Call Detail Record (CDR)**. Each CDR represents an individual attempt to route the call to the destination network.

The key attributes related to call attempts while using call events **CDR Streaming** include:

.. list-table:: CDR Streaming Call Attempt Attributes
   :header-rows: 1
   :widths: 8 5 50 5

   * - **Attribute**
     - **Type**
     - **Description**
     - **Example**
   * - **routing_attempt**
     - Integer
     - Specifies the sequential attempt number for routing the call. The first attempt is recorded as ``1``, with each subsequent attempt incrementing this value.
     - ``1``
   * - **is_last_cdr**
     - Boolean
     - Indicates whether this CDR corresponds to the final attempt in the routing process. If set to ``true``, no further attempts were made.
     - ``true``

By utilizing **DNS SRV** records and **Trunk Groups**, DIDWW enables advanced failover and load-balancing strategies for inbound DID numbers. In scenarios where a call cannot be routed successfully on the first attempt, the system can attempt alternative destinations based on predefined routing logic.

Additional information
-------------------------

.. div:: vertical-list

   .. card:: **Number List Load Balancing**
      :link: user_panel_voice_in_numberlist_examples_lb
      :link-type: ref

      Learn how to use Number Lists for call load balancing purposes.

   .. card:: **Inbound CDR Logs**
      :link: inbound_cdr_logs
      :link-type: ref

      For User Interface Call Logs, visit the documentation page.

   .. card:: **CDR Streaming Attributes**
      :link: voice_in_cdr_streaming_attributes
      :link-type: ref

      For more details about CDR Streaming CDR attributes, visit the documentation page.

.. This CSS modifies the appearance of code blocks and admonitions in Sphinx documentation.
.. Removes default borders for a cleaner look.
.. Changes background color to a soft blue (`#F3F7FC`) for better readability.
.. Ensures code blocks have a max width (`60rem`) for layout consistency.
.. Uses monospaced fonts for preformatted text.
.. Adjusts line height for better text clarity.
.. Adds rounded corners (`border-radius: 10px`) for a modern UI.
.. Customizes string color (`.s2` class) for syntax highlighting.
.. Limits the width of admonition boxes (e.g., notes) to align with the layout.

.. raw:: html

    <style>
    .rst-content div[class^=highlight],
    .rst-content pre.literal-block {
        border: 0;
        background: 0;
        background-color: #F3F7FC !important;
        overflow-x: auto;
        color: #2c2c2c;
        margin: 1px 0 24px;
        max-width: 28rem !important;
        box-sizing: content-box;
        border-radius: 10px;
    }

        pre {
            line-height: 125%;
        }

        .rst-content div[class^="highlight"] pre {
            font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", Courier, monospace;
            font-size: 14px;
            background-color: #F3F7FC !important;
            border-radius: 10px;
            color: rgb(44, 44, 44);
            line-height: 1.4;
            border: 0px;
        }

        .rst-content div[class^="highlight"] pre {
            background-color: #F3F7FC !important;
        }

        .highlight .s2 {
            color: rgb(64, 112, 160);
        }

    </style>


FAX Services
============

DIDWW supports multiple protocols for fax communication, including the **T.38** and **G.711 VoIP** fax communication standards.

    - **G.711u**: Utilizes uncompressed audio for transmitting fax data, suitable for environments without native T.38 support.
    - **T.38**: Optimized for fax transmissions over IP networks, providing enhanced reliability and error correction.

Availability
------------

FAX services are available in the majority of countries and regions. For specific availability in your desired area, please refer to the detailed `FAX Service Coverage <https://www.didww.com/services/fax>`_ page.

Contact Information
-------------------

For further details or assistance, please reach out to the DIDWW Technical Support Team:

    - **Email**: `support@didww.com <mailto:support@didww.com>`_

.. _user_panel_call_redirection_outbound:

==================================================
Inbound Call Redirection Methods
==================================================

Inbound calls can be redirected to an external phone number (PSTN) through your account's **Outbound Trunks**. Advanced routing is achieved by responding to an incoming call with either a **30x Redirect** SIP response or an in-dialog **REFER** request.

----

.. raw:: html

    <br>

.. _user_panel_call_redirection_outbound_prerequisites:

Before You Begin
================

    - At least one :ref:`Outbound Trunk <outbound_trunk_create_trunk>` is required, with **Authentication method** set to **Credentials & IP-Based**, and DIDWW :ref:`SIP/RTP IP addresses allowed <service_did_sip>`.
    - An :ref:`Inbound SIP Trunk <user_panel_sipin_trunk>` is required, with **Max 30x Redirects** or **Max Transfers** set to a value greater than 0 in the :ref:`Signalling tab <user_panel_sipin_trunk_general_advanced_signaling_settings_timeout>`.
    - Authorization is required on the :ref:`Inbound SIP Trunk <user_panel_sipin_trunk_authentication>`, using the same **Auth User** and **Auth Password** configured on the chosen :ref:`Outbound Trunk <view_outbound_trunk_credentials>`.
    - The SIP destination URI is required in the format ``sip:NEW_PSTN_NUMBER@<outbound_endpoint>`` and included in the **Contact** header for 30x responses or the **Refer-To** header for REFER requests.

.. note::
   - The full list of outbound endpoints is available at :ref:`Signaling Endpoints <voice-out-signaling-endpoints>`.
   - ``NEW_PSTN_NUMBER`` is the E.164 phone number, and ``<outbound_endpoint>`` is a DIDWW outbound endpoint (e.g., ``out.didww.com``).

----

.. raw:: html

    <br>

.. _call_redirection_302:

30x Redirect Method
===================

This method redirects an inbound call to a new destination **without answering it**.

    1. Your system replies to the DIDWW INVITE with a SIP ``302 Moved Temporarily`` (or another 3xx response), including the new destination in the ``Contact`` header.
    2. DIDWW then starts a new outbound call to that SIP URI using your Outbound Trunk, authenticated with the credentials set on your Inbound Trunk.

Examples
--------

.. dropdown:: 302 SIP Response
   :icon: file-code
   :animate: fade-in

   Example of a valid ``302 Moved Temporarily`` response::

      SIP/2.0 302 Moved Temporarily
      Via: SIP/2.0/UDP 192.0.2.5:5060;branch=z9hG4bK-393929
      From: <sip:CALLER_NUMBER@46.19.209.14>;tag=123456
      To: <sip:DID_NUMBER@example.com>;tag=abcdef
      Call-ID: 01-01-35531111-68BE960300095714-69CF836B
      CSeq: 1 INVITE
      Contact: <sip:NEW_PSTN_NUMBER@out.didww.com>
      Content-Length: 0

   For more details, see :rfc:`3261#section-21.3`.

.. dropdown:: Call Flow Diagram
   :icon: workflow
   :animate: fade-in

   .. mermaid::

      %%{init: { "theme": "base", "themeVariables": { "actorBkg": "#e6f7ff", "actorBorder": "#1890ff", "noteBkgColor": "#fff7e6", "noteBorderColor": "#fa8c16" }}}%%
      sequenceDiagram
        participant caller as Caller
        participant voice_in as DIDWW Inbound Trunk
        participant pbx as Your System
        participant voice_out as DIDWW Outbound Trunk

        caller->>voice_in: INVITE
        voice_in->>pbx: INVITE to your system<br/>sip:DID_NUMBER@example.com
        pbx-->>voice_in: 302 Redirect<br/>Contact: sip:NEW_PSTN_NUMBER@out.didww.com

        Note over voice_in: Redirect processing<br/>checks MAX_30x_REDIRECTS value
        voice_in->>voice_out: INVITE to your Outbound Trunk<br/>sip:NEW_PSTN_NUMBER@out.didww.com
        voice_out-->>voice_in: 401 Unauthorized + Auth Challenge

        Note over voice_in: Applies AUTH_USER and AUTH_PASSWORD from your Inbound Trunk

        voice_in->>voice_out: INVITE with Auth Header<br/>sip:NEW_PSTN_NUMBER@out.didww.com
        voice_out-->>voice_in: 200 OK
        Note over voice_in, voice_out: Call is established via Outbound Trunk

.. dropdown:: Use Cases
   :icon: light-bulb
   :animate: fade-in

   This method is ideal when a routing decision can be made immediately, without answering the call first.

        - Forward calls after hours to a service or mobile phone
        - Instantly route VIP callers to a direct line
        - Redirect desk calls to a mobile phone with follow-me rules

----

.. raw:: html

    <br>

.. _call_redirection_refer:

REFER Transfer Method
=====================

This method transfers an inbound call to a new destination **after it has been answered**.

    1. Your system first answers the inbound call, creating an active SIP dialog.
    2. When a transfer is needed, your system sends an in-dialog SIP ``REFER`` request with the new destination in the ``Refer-To`` header.
    3. DIDWW validates the request against the ``MAX_TRANSFERS`` setting and replies with ``200 OK``.
    4. Your system then sends a ``BYE`` to close the original call leg. DIDWW initiates a new outbound call via your Outbound Trunk, authenticated with the credentials from your Inbound Trunk.

Examples
--------

.. dropdown:: SIP REFER Request
   :icon: file-code
   :animate: fade-in

   Example of a valid in-dialog REFER request::

      REFER sip:CALLER_NUMBER@46.19.209.14 SIP/2.0
      Via: SIP/2.0/UDP 192.0.2.5:5060;branch=z9hG4bK-443322
      Max-Forwards: 70
      From: <sip:USERPART@example.com>;tag=abcdef
      To: <sip:CALLER_NUMBER@46.19.209.14>;tag=123456
      Call-ID: 01-01-35531111-68BE960300095714-69CF836C
      CSeq: 2 REFER
      Refer-To: <sip:NEW_PSTN_NUMBER@out.didww.com>
      Referred-By: <sip:DID_NUMBER@example.com>
      Contact: <sip:DID_NUMBER@192.0.2.5:5060>
      Content-Length: 0

   For more details, see :rfc:`3515`.

.. dropdown:: Call Flow Diagram
   :icon: workflow
   :animate: fade-in

   .. figure:: https://doc.didww.com/_images/siprefer-diagram.png
        :alt: Porting Request Flow
        :class: align-left no-shadow

   .. for some reason this mermaid do not show arrows when opened first, so it was moved to screenshot, if need to change something change below and re-do screenshot and update
   .. .. mermaid::

      %%{init: { "theme": "base", "themeVariables": { "actorBkg": "#e6f7ff", "actorBorder": "#1890ff", "noteBkgColor": "#fff7e6", "noteBorderColor": "#fa8c16" }}}%%
      sequenceDiagram
        participant caller as Caller
        participant voice_in as DIDWW Inbound Trunk
        participant pbx as Your System
        participant voice_out as DIDWW Outbound Trunk

        caller->>voice_in: INVITE
        voice_in->>pbx: INVITE to your system<br/>sip:DID_NUMBER@example.com
        pbx-->>voice_in: 200 OK

        Note over voice_in,pbx: Established SIP Dialog A
        pbx->>voice_in: REFER<br/>Refer-To: sip:NEW_PSTN_NUMBER@out.didww.com
        Note over voice_in: Checks MAX_TRANSFERS value
        voice_in-->>pbx: 202 Accepted

        Note over voice_in: Transfer processing
        voice_in->>voice_out: INVITE to Outbound Trunk<br/>sip:NEW_PSTN_NUMBER@out.didww.com
        voice_out-->>voice_in: 401 Unauthorized + Auth Challenge

        Note over voice_in: Applies AUTH_USER and AUTH_PASSWORD from your Inbound Trunk
        voice_in->>voice_out: INVITE with Authorization Header
        voice_out-->>voice_in: 200 OK
        Note over voice_in,voice_out: Established SIP Dialog B

.. dropdown:: Use Cases
   :icon: light-bulb
   :animate: fade-in

   This method is useful when the call must first be answered before deciding where to route it:

       - Transfer calls after IVR menu selection (e.g., "Press 1 for Sales")
       - Redirect from an AI voicebot to a live agent after intent detection
       - Forward calls from an agent’s softphone to an external specialist on the PSTN

----

Additional Resources
==========================================

.. card:: **Configure Call Transfers**
   :link: call_transfers_use_cases
   :link-type: ref

   Step-by-step guide on configuring inbound and outbound SIP trunks in DIDWW
   to enable call transfers using SIP 30x Redirect or SIP REFER signaling.

.. toctree::
  :maxdepth: 1
  :hidden:

  Configure Call Transfers <call-transfers.rst>

.. raw:: html

    <br>


.. _service_did_stir_shaken:

===========
STIR/SHAKEN
===========

**STIR** (Secure Telephony Identity Revisited) and **SHAKEN** (Secure Handling of Asserted Information Using tokens) are technology standards developed to prevent spoofing of calling numbers and ensure the integrity of Caller ID information.

How STIR/SHAKEN Works
---------------------

The STIR/SHAKEN framework enables the originating operator to include the original Caller ID, destination number, and attestation level (trust level) in a SIP call. This data is added to the `Identity` header as a cryptographic signature in the form of a JSON Web Token (`JWT <https://en.wikipedia.org/wiki/JSON_Web_Token>`_).

Transit operators can validate this signature and detect whether the Caller ID has been altered during transit by comparing it to the trusted data in the `Identity` header. The use of cryptographic algorithms ensures the immutability of the header, making it possible to identify spoofed Caller IDs and inform the recipient.

**Regulatory Context**

The TRACED Act (Telephone Robocall Abuse Criminal Enforcement and Deterrence Act), signed into U.S. law in December 2019, requires all U.S. phone companies to implement STIR/SHAKEN:

    - **Large carriers**: Implementation deadline of June 30, 2021.
    - **Smaller and rural carriers**: Implementation deadline of June 30, 2022.

STIR/SHAKEN Handling Modes for Voice IN Service
-----------------------------------------------

DIDWW provides two options for handling STIR/SHAKEN data in Voice IN trunks:

    1. **Transit Identity Header**

       The `Identity` header is passed as-is to the customer. Customers are responsible for validation.

    2. **P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID**

       DIDWW parses and validates the `Identity` header received from the call originator. Validation results are provided to the customer via the following headers:

       - `P-Stir-Verstat`
       - `P-Attestation-Indicator`
       - `P-Origination-ID`

STIR/SHAKEN settings can be configured through the DIDWW User Panel at :ref:`SIP Trunk configurations <up_stir_shaken>`.

.. warning::
   The `Identity` header contains private data. By default, the Transit Identity Header mode is disabled. Contact our sales team at sales@didww.com for more information.

P-Stir-Verstat Header
---------------------

The `P-Stir-Verstat` header, inserted by DIDWW, indicates the verification status of the STIR/SHAKEN data. Possible values are:

    - **TN-Validation-Passed**:
      Validation was successful. The signature is valid, the certificate chain is trusted, and the Caller ID matches the data in the SIP signaling (no changes occurred during transit).

    - **TN-Validation-Failed**:
      Validation failed due to an invalid signature, an untrusted certificate, or discrepancies in the numbering information during transit.

    - **No-TN-Validation**:
      Validation could not be performed because the signature was missing or malformed.

P-Attestation-Indicator
-----------------------

The `P-Attestation-Indicator` header represents the attestation level from the `Identity` header. This header is added when a valid `Identity` signature is received. Possible values are:

    - **A**: The originating service provider has authenticated the calling party and authorized them to use the calling number.
    - **B**: The originating service provider has authenticated the customer but cannot verify their authorization to use the calling number.
    - **C**: The originating service provider has authenticated the source of the call but not the calling party.

P-Origination-ID
----------------

The `P-Origination-ID` header represents the STIR/SHAKEN `origid` value. This allows tracing of calls across networks and locating Call Detail Records (CDRs) in transit systems.

Example
-------

A sample SIP INVITE message with STIR/SHAKEN validation results:

.. code-block:: console

    INVITE sip:16031234567@example.com:5060 SIP/2.0
    Via: SIP/2.0/UDP example.com:5060
    From: "John" <sip:10234567890@1.2.3.4:5060>;tag=123456789
    To: "Smith" <sip:10234567891@5.6.7.8:5060>
    Call-ID: 1-12345@1.2.3.4
    CSeq: 1 INVITE
    Max-Forwards: 70
    P-Stir-Verstat: TN-Validation-Passed
    P-Attestation-Indicator: A
    P-Origination-ID: 59256b5e-9ab8-41be-9746-d7a797647603

References
----------

.. card:: RFC 8224
    :link: https://datatracker.ietf.org/doc/html/rfc8224

    Defines the use of SIP Identity tokens to authenticate and verify Caller IDs.

.. card:: RFC 8225
    :link: https://datatracker.ietf.org/doc/html/rfc8225

    Describes how to create and validate tokens that cryptographically verify Caller IDs.

.. card:: RFC 8226
    :link: https://datatracker.ietf.org/doc/html/rfc8226

    Covers the use of certificates to establish authority over telephone numbers.

.. card:: RFC 7340
    :link: https://datatracker.ietf.org/doc/html/rfc7340

    Explains challenges related to unauthorized robocalling and illegitimate Caller ID spoofing.


====================================
Inbound Toll-Free DID Dialing Format
====================================

This article indicates which dialing format should be used to dial a Toll-Free type DID number of specific country.

.. xlsx-table::
   :file: tf_dialing_scheme.xlsx
   :header-rows: 1

.. _tf_dial_note:

'*' - The DID number would use one or other specified formats only according to interconnection the number is operating at. For concrete dialing format for such number, you may contact support@didww.com.


==============================================================
Universal International Freephone Number (UIFN) Dialing Format
==============================================================

This article indicates which dialing format should be used to dial an UIFN type DID number from specific country.

+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Country                                          | Dialing Format                                                                      |
+==================================================+=====================================================================================+
| Argentina                                        | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Australia                                        | 0011-800-XXXX-XXXX                                                                  |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Austria                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Belgium                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Brazil                                           | 0021-800-XXXX-XXXX                                                                  |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Bulgaria                                         | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Canada                                           | 011-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| China                                            | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Colombia                                         | 005-800 -XXXX-XXXX / 00414-800-XXXX-XXXX / 00444-800-XXXX-XXXX / 009-800-XXXX-XXXX  |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Costa Rica                                       | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Croatia                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Cyprus                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Czech Republic                                   | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Denmark                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Estonia                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Finland                                          | 999-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| France                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| French Guiana                                    | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Germany                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Greece                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Guadeloupe                                       | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Hong Kong                                        | 006-800-XXXX-XXXX / 1800-XXXX-XXXX                                                  |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Hungary                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Iceland                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Israel                                           | 00-800-XXXX-XXXX / 012-800-XXXX-XXXX / 013-800-XXXX-XXXX / 014-800-XXXX-XXXX        |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Italy                                            | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Japan                                            | 010-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Latvia                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Lithuania                                        | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Luxembourg                                       | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Macao                                            | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Macedonia                                        | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Malaysia                                         | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Malta                                            | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Martinique                                       | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Mayotte                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Moldova                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Monaco                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Netherlands                                      | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| New Zealand                                      | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Norway                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Peru                                             | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Philippines                                      | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Poland                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Portugal                                         | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Reunion                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Romania                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Saint Pierre And Miquelon                        | Not Specified                                                                       |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Singapore                                        | 001-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Slovakia                                         | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Slovenia                                         | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| South Africa                                     | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| South Korea                                      | 002-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Spain                                            | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Sweden                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Switzerland                                      | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Taiwan                                           | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Thailand                                         | 001-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| United Kingdom                                   | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| United States                                    | 011-800-XXXX-XXXX                                                                   |
+--------------------------------------------------+-------------------------------------------------------------------------------------+
| Uruguay                                          | 00-800-XXXX-XXXX                                                                    |
+--------------------------------------------------+-------------------------------------------------------------------------------------+



=============================
Analytics and troubleshooting
=============================

Inspect individual outbound calls, review outbound trunk performance, and
analyze aggregated outbound usage with the tools below. Detailed analytics
documentation is maintained centrally in Logs & Analytics.

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`list-unordered` **Outbound call logs**
      :link: outbound_cdr_logs
      :link-type: ref

      Find calls and review SIP responses, duration, media, and charges.

   .. grid-item-card:: :octicon:`graph` **Outbound voice statistics**
      :link: userpanel_statistics_voice_out
      :link-type: ref

      Analyze aggregated outbound traffic and performance.

   .. grid-item-card:: :octicon:`file` **Outbound voice reports**
      :link: userpanel_reports_voice_out
      :link-type: ref

      Create and download outbound voice reports.


===========================
Authentication and security
===========================

Outbound SIP trunks are exposed to public networks and can be targeted by
automated scans, credential attacks, and toll fraud. DIDWW combines
authentication, address restrictions, service limits, and monitoring controls
to reduce these risks.

How outbound trunk authentication works
========================================

Authentication verifies which system sent a request. It is separate from
authorization rules such as :ref:`Allowed CLI(s)
<outbound_trunk_cli_settings>` and :ref:`Destination dialing settings
<dialing_settings>`, which control what an authenticated trunk can do.

DIDWW applies different authentication checks depending on the trunk's
configured method:

.. list-table::
   :header-rows: 1
   :widths: 25 45 30

   * - Method
     - Authentication checks
     - Availability
   * - **Credentials & IP-Based**
     - Combines source IP validation with a :ref:`SIP Digest challenge
       <services_voice_out_auth_realm>` for the strongest supported
       authentication protection.
     - Default method, available through self-service configuration.
   * - **IP-Only**
     - Validates the source IP address without a SIP Digest challenge.
     - Not available through self-service. Contact `DIDWW Technical Support
       <mailto:support@didww.com>`_.
   * - **Twilio Account SID**
     - Authenticates the trunk using its Twilio Account SID.
     - Available for the :doc:`Twilio integration
       <../../integrations/twilio/index>`.
   * - **phone.systems™**
     - Authenticates calls originating from a phone.systems™ Cloud PBX
       instance.
     - The system trunk is created automatically.

If a request fails the checks required by its trunk's method, DIDWW rejects
the call. See :ref:`Authentication settings
<outbound_trunk_create_authentication>` for the corresponding User Panel
fields and `Authentication flow`_ for the Credentials & IP-Based SIP Digest
exchange.

For detailed requirements and availability, see
:ref:`Authentication method values <outbound_trunk_auth_method_values>` in
the Outbound trunk reference.

.. _outbound_trunk_authentication_priority:

Authentication priority
------------------------

When an account contains outbound trunks with overlapping Allowed SIP IP
ranges, a single request can match more than one trunk. This can occur, for
example, when one matching trunk uses IP-Only authentication and another uses
Credentials & IP-Based authentication.

The applicable trunk is selected using two priority rules:

1. **Authentication method.** IP-Only trunks are checked before
   Credentials & IP-Based trunks.
2. **IP address specificity.** Within the same authentication method, the
   trunk with the narrowest matching Allowed SIP IP range is checked first.
   For example, ``/32`` is more specific than ``/24``.

The following example shows an ``INVITE`` from ``203.0.113.5``. This address
matches both ``203.0.113.5/32`` and ``203.0.113.0/24``, so all four trunks
are candidates:

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "primaryColor": "#e0f2fe",
       "primaryBorderColor": "#38bdf8",
       "primaryTextColor": "#1f2d3d",
       "secondaryColor": "#ccfbf1",
       "secondaryBorderColor": "#2dd4bf",
       "secondaryTextColor": "#1f2d3d",
       "tertiaryColor": "#fef3c7",
       "tertiaryBorderColor": "#facc15",
       "tertiaryTextColor": "#1f2d3d",
       "lineColor": "#0066cc",
       "textColor": "#1f2d3d",
       "nodeTextColor": "#1f2d3d",
       "titleColor": "#1f2d3d",
       "clusterBkg": "#f8fafc",
       "clusterBorder": "#cbd5e1",
       "edgeLabelBackground": "#ffffff"
     }
   }}%%

   flowchart LR
       subgraph SRC ["Incoming request"]
           REQ["INVITE from 203.0.113.5"]
       end

       subgraph TRUNKS ["Matching trunks"]
           T1["Trunk 1 - 203.0.113.5/32<br/>IP-Only"]
           T2["Trunk 2 - 203.0.113.0/24<br/>IP-Only"]
           T3["Trunk 3 - 203.0.113.5/32<br/>Credentials & IP-Based"]
           T4["Trunk 4 - 203.0.113.0/24<br/>Credentials & IP-Based"]
       end

       subgraph PRIORITY ["Authentication check order"]
           P1["1st"]
           P2["2nd"]
           P3["3rd"]
           P4["4th"]
       end

       subgraph RESULT ["Result"]
           A1["Trunk 1 selected<br/>INVITE sent downstream"]
       end

       classDef request fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
       classDef trunk fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px
       classDef priority fill:#fef3c7,stroke:#facc15,color:#1f2d3d,stroke-width:1.5px
       classDef result fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px

       class REQ request
       class T1,T2,T3,T4 trunk
       class P1,P2,P3,P4 priority
       class A1 result

       REQ --> T1
       REQ --> T2
       REQ --> T3
       REQ --> T4

       T1 --> P1
       T2 --> P2
       T3 --> P3
       T4 --> P4

       P1 --> A1

       linkStyle default stroke:#0066cc,stroke-width:1.5px

The resulting check order is:

1. **Trunk 1** — IP-Only with ``203.0.113.5/32``.
2. **Trunk 2** — IP-Only with ``203.0.113.0/24``.
3. **Trunk 3** — Credentials & IP-Based with ``203.0.113.5/32``.
4. **Trunk 4** — Credentials & IP-Based with ``203.0.113.0/24``.

Authentication method takes precedence over IP address specificity. This is
why Trunk 2, an IP-Only trunk with a ``/24`` range, is checked before
Trunk 3, a Credentials & IP-Based trunk with the narrower ``/32`` range.

In this example, Trunk 1 is selected and its IP-Only authentication
requirements are applied. Because the source IP address matches and no SIP
Digest challenge is required, the ``INVITE`` is sent downstream.

Once a trunk is selected, that trunk's authentication requirements are
applied. If authentication fails, the request is rejected rather than passed
to a lower-priority trunk.

SIP Digest authentication
==========================

SIP Digest authentication verifies the trunk's username and password before
DIDWW accepts a request. It is used together with IP-based authentication
for **Credentials & IP-Based** trunks, and skipped entirely for **IP-Only**
trunks.

Trunks have unique usernames and passwords, so credentials generated for
one trunk do not work on another. Your PBX, SBC, or SIP platform must
present them in the SIP ``Authorization`` header when DIDWW challenges a
request, using the fixed realm :ref:`out.didww.com
<services_voice_out_auth_realm>`. The full digest exchange, including the
SIP headers involved, is shown in `Authentication flow`_ below.

If a request has no credentials, incorrect credentials, or credentials for
a different trunk, DIDWW does not accept the call. :ref:`Credential
lifecycle <outbound_trunk_credential_lifecycle>` explains how credentials
are generated, viewed, and replaced.

.. _outbound_trunk_authentication_flow:

Authentication flow
===================

For **Credentials & IP-Based** trunks, the first ``INVITE`` is challenged.
The call is accepted after the credentials are validated:

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",
       "signalColor": "#0066cc",
       "signalTextColor": "#1f2d3d",
       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#facc15",
       "noteTextColor": "#1f2d3d",
       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d",
       "loopTextColor": "#1f2d3d"
     }
   }}%%
   sequenceDiagram
       participant SYS as Customer SIP gateway
       participant SERVICE as Outbound SIP service

       SYS->>SERVICE: INVITE (no Authorization header)
       SERVICE-->>SYS: 401 Unauthorized (WWW-Authenticate, nonce)
       SYS->>SERVICE: ACK
       SYS->>SERVICE: INVITE with Authorization header
       SERVICE-->>SYS: 100 Trying, call proceeds

.. dropdown:: Full SIP message exchange
   :icon: workflow
   :animate: fade-in

   This example shows the SIP INVITE authentication flow from a customer
   gateway with IP address ``192.0.2.10`` to destination number
   ``12025550199`` with Caller ID ``12025550100``, for a **Credentials &
   IP-Based** trunk.

   During the first step, the UAC sends an INVITE without an
   ``Authorization`` header::

       192.0.2.10.5060 > 46.19.209.44.5060: SIP, length: 992
           INVITE sip:12025550199@out.didww.com SIP/2.0
           Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK48496580;rport
           Max-Forwards: 70
           From: <sip:12025550100@sbc.example.com>;tag=as1fc3fe35
           To: <sip:12025550199@out.didww.com>
           Contact: <sip:12025550100@192.0.2.10:5060>
           Call-ID: 479b59102ffeda0c04eed76d17304eb5@sbc.example.com
           CSeq: 102 INVITE
           User-Agent: customer-switch v1.22
           Date: Wed, 03 Mar 2021 17:53:43 GMT
           Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH, MESSAGE
           Supported: replaces, timer
           Content-Type: application/sdp
           Content-Length: 325

           v=0
           o=root 2120298149 2120298149 IN IP4 192.0.2.10
           s=customer-switch 1.22
           c=IN IP4 192.0.2.10
           t=0 0
           m=audio 12348 RTP/AVP 18 0 8 101
           a=rtpmap:18 G729/8000
           a=fmtp:18 annexb=no
           a=rtpmap:0 PCMU/8000
           a=rtpmap:8 PCMA/8000
           a=rtpmap:101 telephone-event/8000
           a=fmtp:101 0-16
           a=ptime:20
           a=maxptime:150
           a=sendrecv

       46.19.209.44.5060 > 192.0.2.10.5060: SIP, length: 334
           SIP/2.0 100 Trying
           Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK48496580;rport=5060;received=192.0.2.10
           From: <sip:12025550100@sbc.example.com>;tag=as1fc3fe35
           To: <sip:12025550199@out.didww.com>
           Call-ID: 479b59102ffeda0c04eed76d17304eb5@sbc.example.com
           CSeq: 102 INVITE
           Server: Y balancing node
           Content-Length: 0

       46.19.209.44.5060 > 192.0.2.10.5060: SIP, length: 609
           SIP/2.0 401 Unauthorized
           Record-Route: <sip:46.19.209.8;r2=on;lr;ftag=as1fc3fe35>
           Record-Route: <sip:46.19.209.44;r2=on;lr;ftag=as1fc3fe35>
           Via: SIP/2.0/UDP 192.0.2.10:5060;received=192.0.2.10;branch=z9hG4bK48496580;rport=5060
           From: <sip:12025550100@sbc.example.com>;tag=as1fc3fe35
           To: <sip:12025550199@out.didww.com>;tag=10-67E5E9A8-603FCD270008B2AB-ED917700
           Call-ID: 479b59102ffeda0c04eed76d17304eb5@sbc.example.com
           CSeq: 102 INVITE
           WWW-Authenticate: Digest realm="out.didww.com", qop="auth", nonce="603FCD4151d08b2d92526f23f65208788a5425a1"
           Server: DIDWW Y SBC node
           Content-Length: 0

       192.0.2.10.5060 > 46.19.209.44.5060: SIP, length: 441
           ACK sip:12025550199@out.didww.com SIP/2.0
           Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK48496580;rport
           Max-Forwards: 70
           From: <sip:12025550100@sbc.example.com>;tag=as1fc3fe35
           To: <sip:12025550199@out.didww.com>;tag=10-67E5E9A8-603FCD270008B2AB-ED917700
           Contact: <sip:12025550100@192.0.2.10:5060>
           Call-ID: 479b59102ffeda0c04eed76d17304eb5@sbc.example.com
           CSeq: 102 ACK
           User-Agent: customer-switch v1.22
           Content-Length: 0

   The outbound SIP service responds to the initial INVITE with
   ``401 Unauthorized`` and returns a **nonce** value,
   ``603FCD4151d08b2d92526f23f65208788a5425a1``. The UAC uses this value to
   calculate the **response** in the ``Authorization`` header of the next
   request::

       192.0.2.10.5060 > 46.19.209.44.5060: SIP, length: 1251
           INVITE sip:12025550199@out.didww.com SIP/2.0
           Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK34d0ea96;rport
           Max-Forwards: 70
           From: <sip:12025550100@sbc.example.com>;tag=as1fc3fe35
           To: <sip:12025550199@out.didww.com>
           Contact: <sip:12025550100@192.0.2.10:5060>
           Call-ID: 479b59102ffeda0c04eed76d17304eb5@sbc.example.com
           CSeq: 103 INVITE
           User-Agent: customer-switch v1.22
           Authorization: Digest username="WwAPO4asrLsk5Mhv", realm="out.didww.com", algorithm=MD5, uri="sip:12025550199@out.didww.com", nonce="603FCD4151d08b2d92526f23f65208788a5425a1", response="78381cc4a3258cc5418888988ad68552567", qop=auth, cnonce="58c9df37", nc=00000001
           Date: Wed, 03 Mar 2021 17:53:43 GMT
           Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH, MESSAGE
           Supported: replaces, timer
           Content-Type: application/sdp
           Content-Length: 325

           v=0
           o=root 2120298149 2120298150 IN IP4 192.0.2.10
           s=customer-switch 1.22
           c=IN IP4 192.0.2.10
           t=0 0
           m=audio 12348 RTP/AVP 18 0 8 101
           a=rtpmap:18 G729/8000
           a=fmtp:18 annexb=no
           a=rtpmap:0 PCMU/8000
           a=rtpmap:8 PCMA/8000
           a=rtpmap:101 telephone-event/8000
           a=fmtp:101 0-16
           a=ptime:20
           a=maxptime:150
           a=sendrecv

       46.19.209.44.5060 > 192.0.2.10.5060: SIP, length: 334
           SIP/2.0 100 Trying
           Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK34d0ea96;rport=5060;received=192.0.2.10
           From: <sip:12025550100@sbc.example.com>;tag=as1fc3fe35
           To: <sip:12025550199@out.didww.com>
           Call-ID: 479b59102ffeda0c04eed76d17304eb5@sbc.example.com
           CSeq: 103 INVITE
           Server: Y balancing node
           Content-Length: 0

   The outbound SIP service checks the ``username`` and ``response`` values of
   the ``Authorization`` header against the trunk's stored credentials and
   authenticates the INVITE once they match.

.. note::

   **IP-Only** trunks do not use SIP Digest authentication, so the challenge
   and authenticated ``INVITE`` retry are skipped. Authentication succeeds
   when the source IP address matches an allowed SIP IP address. The request
   then proceeds to the remaining trunk checks.

See :doc:`Call flow examples <routing-dialing/call-flow-examples>` for
step-by-step SIP message exchanges covering authentication, call
establishment, and termination for both authentication methods.

Additional checks after authentication
--------------------------------------

Successful authentication verifies the request source, but the call must still
pass these authorization and operational controls:

.. list-table::
   :header-rows: 1
   :widths: 25 35 40

   * - Control
     - What it checks
     - Outcome
   * - :ref:`On CLI mismatch <outbound_trunk_cli_settings>`
     - Whether the Caller ID in the SIP ``From`` header matches a number
       allowed by the trunk.
     - **Send Original CLI** forwards a non-matching Caller ID unchanged.
       **Reject Call** stops the call.
   * - :ref:`Destination dialing settings <dialing_settings>`
     - Whether the called country and number prefix are permitted.
     - **Allow All** blocks only the listed prefixes. **Reject All** permits
       only the listed prefixes.
   * - :ref:`Capacity limit
       <outbound_trunk_limits_and_notification>`
     - The number of simultaneous calls.
     - A new call cannot proceed when the configured capacity has been
       reached.
   * - :ref:`24 hour limit (USD)
       <outbound_trunk_limits_and_notification>`
     - The accumulated charges during the rolling 24-hour period.
     - Reaching the limit disables the trunk, blocks new calls, and
       disconnects active calls shortly afterward.
   * - :ref:`Status <outbound_trunk_status_values>`
     - Whether the trunk is enabled.
     - **Enabled** allows calls that pass the other checks. **Disabled**
       blocks new outbound calls. Use :doc:`Enable or disable an outbound
       trunk <how-to-guides/enable-disable-outbound-trunk>` to change its
       status without deleting its configuration.

Together, these controls provide protection beyond authentication. They
restrict what an authenticated trunk is allowed to do, help prevent calls
using unapproved Caller IDs or destinations, limit traffic and spending, and
stop new calls when necessary.

.. _outbound_trunk_credential_lifecycle:

Credential lifecycle
======================

Only **Credentials & IP-Based** trunks have SIP digest credentials. When
you create one, DIDWW automatically generates a unique SIP digest username
and password. View or reveal them using
:doc:`how-to-guides/view-outbound-trunk-credentials`, or replace the
password using :doc:`how-to-guides/regenerate-outbound-trunk-credentials`.

Regenerating replaces the password. The username does not change. Once
replaced, the previous password no longer authenticates new requests, so
update every system that uses the trunk with the new password at the same
time you regenerate it.

Signaling and media encryption
================================

Authentication and encryption are configured separately. The selected
authentication method verifies the source of a request, but it does not
encrypt SIP messages or call audio.

TLS signaling encryption
------------------------

To encrypt SIP signaling, configure your system to connect using TLS on port
``5061``. SIP over UDP or TCP on port ``5060`` is not encrypted.

TLS protects SIP messages exchanged between the outbound SIP service and your
equipment. It does not encrypt RTP media or automatically enable media
encryption. Port and transport details are covered in
:ref:`Network and transport protocols <voice_out_network_transport>`.

Media encryption modes
----------------------

To encrypt call audio, select an option under **Media encryption mode** when
creating or editing the outbound trunk. **Disabled** is selected by default.
Your PBX or SBC must support and use the mode selected for the trunk.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Option
     - Behavior
   * - **Disabled**
     - Uses unencrypted RTP for call audio. TLS can still be used separately
       to encrypt SIP signaling.
   * - **SRTP SDES**
     - Encrypts RTP media and carries the encryption key in the SDP body. Use
       TLS to protect the SIP signaling that contains the key.
   * - **SRTP DTLS**
     - Encrypts RTP media and negotiates keys directly over the media path
       using DTLS. TLS must be configured separately if SIP signaling also
       needs to be encrypted.
   * - **ZRTP**
     - Encrypts RTP media and negotiates keys directly between the media
       endpoints instead of carrying them in SIP signaling. TLS is not
       required for ZRTP key negotiation, but it is still needed when SIP
       signaling must also be encrypted.

Enabling media encryption does not automatically enable TLS signaling.

See :ref:`Media encryption mode values
<outbound_trunk_media_encryption_values>` for reference information and
:ref:`Outbound SIP encryption <voice_out_sip_encryption>` for the supported
mechanisms.

Encryption applies only to the connection between the outbound SIP service
and your equipment. It does not provide end-to-end encryption across every
call leg.

Outbound trunk security best practices
======================================

Use these recommendations to protect trunk credentials, prevent unauthorized
calls, and reduce unexpected charges.

.. important::

   Before carrying production traffic, restrict SIP and RTP source addresses,
   limit permitted destinations, and configure appropriate capacity and
   spending limits.

.. dropdown:: Restrict signaling and media access
   :animate: fade-in

   - Configure :ref:`Allowed SIP IP addresses
     <outbound_trunk_create_authentication>` and :ref:`Allowed RTP IP
     addresses <outbound_trunk_create_authentication>` with only the addresses
     used by your equipment. Avoid allowing ``0.0.0.0/0``.
   - Keep PBXs, SBCs, firewalls, and routers updated with supported security
     fixes.

.. dropdown:: Limit calling and financial exposure
   :animate: fade-in

   - Permit only the destinations required for normal traffic, and review the
     restrictions regularly.
   - Set capacity and rolling 24-hour spending limits appropriate for expected
     traffic.
   - Enable the :ref:`Voice OUT Trunk usage limit notification
     <outbound_trunk_limits_and_notification>` to receive an email when usage
     reaches 80% of the 24-hour limit, no more than once every 12 hours.

.. dropdown:: Protect credentials and administrative access
   :animate: fade-in

   - Restrict administrative access to staff who need it.
   - Store trunk credentials in an approved secret-management system. Never
     place credentials in documentation, support tickets, chat messages, or
     screenshots.
   - Do not reuse credentials across unrelated systems or trunks.
   - Remove credential and administrative access when staff or vendors no
     longer need it.

.. dropdown:: Monitor and respond to suspicious activity
   :animate: fade-in

   - Monitor :ref:`outbound call logs <outbound_cdr_logs>` for unfamiliar
     destinations, unusual call volumes, and unexpected charges.
   - Regenerate the trunk password immediately after any suspected exposure.
   - Maintain an internal response process for suspected unauthorized calling
     or credential compromise.

See :doc:`outbound-trunk-reference` for all configurable security fields and
available values.


.. _outbound_caller_id_cnam:

======================
Caller ID and CNAM OUT
======================

Caller ID and CNAM OUT control the calling number and caller name presented
on outbound calls. Configure which Caller IDs an outbound trunk may use,
choose how non-matching numbers are handled, and use the appropriate CNAM
OUT delivery method.

How outbound Caller ID works
==============================

Caller ID, also called CLI (calling line identification), is the calling
number that the originating SIP endpoint asks to present for an outbound
call. The outbound trunk does not generate a Caller ID or automatically
select one from **Allowed CLI(s)**. Your PBX, SBC, softphone, or other SIP
endpoint must supply the number in every SIP ``INVITE``.

The calling number is placed in the user part of the SIP ``From`` header. For
example::

   From: <sip:12025550100@caller.example>;tag=example

In this example, ``12025550100`` is the requested Caller ID.
``caller.example`` is the SIP URI domain and is not part of the calling
number. Send the number in :ref:`E.164 format <outbound_dialing>`.

Before calls are sent, the trunk's :ref:`CLI Settings
<outbound_trunk_cli_settings>` define which DIDWW numbers are treated as
permitted Caller IDs. These settings validate the number supplied by the
originating endpoint; they do not insert or replace it.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "primaryColor": "#e0f2fe",
       "primaryBorderColor": "#38bdf8",
       "primaryTextColor": "#1f2d3d",
       "secondaryColor": "#ccfbf1",
       "secondaryBorderColor": "#2dd4bf",
       "secondaryTextColor": "#1f2d3d",
       "tertiaryColor": "#fef3c7",
       "tertiaryBorderColor": "#facc15",
       "tertiaryTextColor": "#1f2d3d",
       "lineColor": "#0066cc",
       "textColor": "#1f2d3d",
       "nodeTextColor": "#1f2d3d",
       "edgeLabelBackground": "#ffffff"
     }
   }}%%

   flowchart LR
       ORIGIN["Originating SIP endpoint<br/>Send INVITE with Caller ID"]
       AUTH["Match and authenticate trunk"]
       READ["Read Caller ID<br/>from From header"]
       CHECK{"Caller ID matches<br/>permitted CLI?"}
       POLICY{"On CLI mismatch"}
       ROUTE["Select outbound route"]
       SEND["Send call downstream"]
       REJECT["Reject call"]

       ORIGIN --> AUTH --> READ --> CHECK
       CHECK -->|Match| ROUTE
       CHECK -->|No match| POLICY
       POLICY -->|Send Original CLI| ROUTE
       POLICY -->|Reject Call| REJECT
       ROUTE --> SEND

       classDef endpoint fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
       classDef process fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px
       classDef decision fill:#fef3c7,stroke:#facc15,color:#1f2d3d,stroke-width:1.5px
       classDef rejected fill:#fee2e2,stroke:#f87171,color:#1f2d3d,stroke-width:1.5px

       class ORIGIN endpoint
       class AUTH,READ,ROUTE,SEND process
       class CHECK,POLICY decision
       class REJECT rejected

       linkStyle default stroke:#0066cc,stroke-width:1.5px

For each call, Caller ID is processed as follows:

1. **Send the Caller ID.** The originating SIP endpoint places the requested
   calling number in the SIP ``From`` header and sends the ``INVITE``.

2. **Match and authenticate the trunk.** The SIP request is matched to an
   outbound trunk, and the originating system is authenticated. This confirms
   which system sent the request but does not validate the Caller ID. See
   :doc:`Authentication and security <authentication-security>`.

3. **Read the requested Caller ID.** The calling number is taken from the
   SIP ``From`` header of the authenticated request.

4. **Apply the CLI Settings.** The number is compared with the Caller IDs
   permitted by the matched trunk. If it matches, Caller ID validation
   succeeds. If it does not match, **On CLI mismatch** either forwards the
   original number or rejects the call. The trunk does not substitute another
   Caller ID.

5. **Select the route and send the call downstream.** If the call is not
   rejected, the destination, Caller ID, and available coverage determine the
   outbound route. A :ref:`local route <outbound_dialing_local_routes>` may
   be used when the destination and an eligible DIDWW Caller ID belong to the
   same country and in-country coverage is available. Otherwise, an available
   origin-based or international route may be used.

CNAM OUT and :doc:`STIR/SHAKEN <stir-shaken-outbound>` provide different
information. CNAM OUT provides the caller name, while STIR/SHAKEN carries a
signed identity assertion. Neither one supplies or replaces the Caller ID
number.

.. note::

   Passing Caller ID validation does not guarantee that the number will be
   displayed to the called party. The destination operator or an intermediate
   network may modify, suppress, or decline to display it according to its
   policies and applicable regulations.

Allowed outbound CLIs
^^^^^^^^^^^^^^^^^^^^^

The **Allow any DID(s) for Voice OUT** toggle determines which DIDWW numbers
are treated as permitted CLIs:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Toggle state
     - Behavior
   * - **Enabled**
     - All supported DIDWW numbers in your account are treated as permitted
       CLIs. Individual selection is not required.
   * - **Disabled**
     - Only numbers added to **Allowed CLI(s)** are treated as permitted.
       Select them from **Available CLI(s)**, which lists DIDWW numbers that
       support :ref:`local routes <outbound_dialing_local_routes>`. DIDs
       without local-route support are not listed.

These settings define which numbers match the permitted CLI set. A
non-matching number may still be forwarded when **On CLI mismatch** is set to
**Send Original CLI**.

For field values, defaults, and dependencies, see :ref:`CLI Settings
<outbound_trunk_cli_settings>` in the Outbound trunk reference.

CLI mismatch behavior
^^^^^^^^^^^^^^^^^^^^^

A CLI mismatch occurs when the calling number in the SIP ``From`` header does
not match the numbers permitted by the trunk's CLI Settings. This includes a
third-party number or a DIDWW number that was not added to **Allowed CLI(s)**
when **Allow any DID(s) for Voice OUT** is disabled.

The trunk's **On CLI mismatch** setting determines the outcome:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Setting
     - Outcome
   * - **Send Original CLI**
     - Forwards the original ``From`` header value downstream without
       modification. Display by the destination network is not guaranteed.
   * - **Reject Call**
     - Rejects the call when the calling number does not match the permitted
       CLI set.

CLI matching uses the calling number in the user part of the SIP ``From``
URI. It does not use the quoted display name, which is processed separately
as CNAM OUT.

.. important::

   **Send Original CLI** allows a non-matching number to be sent downstream.
   Use it only when presenting a third-party Caller ID intentionally and when
   you are authorized to use that number. To restrict every call to the
   permitted DIDWW Caller IDs, select **Reject Call**.

----

CNAM OUT
==========

CNAM OUT provides caller name information for outbound calls. Caller ID
identifies the calling number, while CNAM OUT provides a name that may be
displayed alongside it. CNAM OUT does not create, validate, or replace the
Caller ID number.

DIDWW supports two CNAM OUT delivery methods: CNAM OUT registration for
supported US DIDWW numbers, and a per-call SIP ``From`` display name for
Canadian and other non-US caller IDs. The applicable method depends on the
Caller ID and whether the name is registered in advance or supplied in each
call.

How CNAM OUT works
==================

Select the supported method for the Caller ID, then follow its setup and
delivery process:

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "primaryColor": "#e0f2fe",
       "primaryBorderColor": "#38bdf8",
       "primaryTextColor": "#1f2d3d",
       "secondaryColor": "#ccfbf1",
       "secondaryBorderColor": "#2dd4bf",
       "secondaryTextColor": "#1f2d3d",
       "tertiaryColor": "#fef3c7",
       "tertiaryBorderColor": "#facc15",
       "tertiaryTextColor": "#1f2d3d",
       "lineColor": "#0066cc",
       "textColor": "#1f2d3d",
       "nodeTextColor": "#1f2d3d",
       "edgeLabelBackground": "#ffffff"
     }
   }}%%

   flowchart LR
       START["Caller name for an outbound call"]
       METHOD{"Which CNAM OUT<br/>method applies?"}

       REGISTER["Supported US DIDWW number<br/>Register name and Identity in My Numbers"]
       ACTIVE["Registration is reviewed<br/>CNAM OUT status becomes Active"]
       DB_CALL["Send call using the DID<br/>as Caller ID"]
       LOOKUP["Destination operator<br/>query the registered CNAM"]

       HEADER["Non-US or third-party Caller ID<br/>Add CNAM to SIP From for each INVITE"]
       RELAY["Relay caller name when<br/>available and supported"]

       DISPLAY["Destination display<br/>the caller name"]

       START --> METHOD
       METHOD -->|CNAM registration| REGISTER
       REGISTER --> ACTIVE
       ACTIVE --> DB_CALL
       DB_CALL --> LOOKUP
       LOOKUP --> DISPLAY

       METHOD -->|SIP From header| HEADER
       HEADER --> RELAY
       RELAY --> DISPLAY

       classDef endpoint fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
       classDef process fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px
       classDef decision fill:#fef3c7,stroke:#facc15,color:#1f2d3d,stroke-width:1.5px
       classDef result fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px

       class START endpoint
       class METHOD,LOOKUP decision
       class REGISTER,ACTIVE,DB_CALL,HEADER,RELAY process
       class DISPLAY result

       linkStyle default stroke:#0066cc,stroke-width:1.5px

Registered CNAM OUT
^^^^^^^^^^^^^^^^^^^

CNAM OUT registration is available for DIDWW US numbers that support the
CNAM OUT feature. It is configured on the DID number in **Phone Numbers > My
Numbers**, rather than on the outbound trunk.

Use :doc:`Manage CNAM OUT
<../../phone-numbers/my-numbers/how-to-guides/configure-cnam-out>` to submit a
caller name of up to 15 characters and select the required Identity. The
request is reviewed, usually within 48–72 hours. The registered value becomes
available for downstream lookup when the DID's :ref:`CNAM OUT status
<my_numbers_cnam_out_statuses>` is **Active**.

When an outbound call presents the DID as its Caller ID, the
destination operator may use that DID number to query registered CNAM. If the
operator performs the lookup and retrieves the registered value, it can
display the caller name to the called party.

.. _user_panel_cnam_from_header:

SIP From header CNAM OUT
^^^^^^^^^^^^^^^^^^^^^^^^

For Canadian and other non-US caller IDs, place the caller name in the
display-name portion of the SIP ``From`` header of every ``INVITE``. This
method is also useful when a per-call value is required or when a non-US
third-party Caller ID cannot use the database-registration method.

DIDWW does not have access to a Canadian CNAM database equivalent to the
CNAM database used for US numbers, so this method does not use the US
database-registration workflow. Send the ``INVITE`` to a :ref:`DIDWW outbound
signaling endpoint <voice-out-signaling-endpoints>`. DIDWW relays the caller
name to downstream carriers when available and supported.

Place the CNAM value as a quoted display name before the SIP URI::

   From: "Example Name" <sip:12025550100@caller.example>;tag=example

In this example:

- ``Example Name`` is the caller name relayed for this call.
- ``12025550100`` is the Caller ID in E.164 format.
- ``caller.example`` is the SIP URI domain and is not part of the caller name
  or Caller ID.

.. note::

   The caller name must not exceed 15 characters. Avoid special characters
   that intermediate SIP systems may alter or remove.

.. important::

   Neither CNAM OUT method guarantees that the caller name will be displayed.
   With database registration, the destination operator must perform a lookup.
   With the SIP-header method, intermediate and destination networks must
   preserve and support the display-name value.

Related resources
====================

- :doc:`routing-dialing/outbound-dialing` — Format destination numbers and
  understand local-route selection.
- :ref:`Caller Name Delivery (CNAM) <user_panel_cnam>` — Compare CNAM IN and
  CNAM OUT.


.. _user_panel_voice_out_get_access:

===============================
Get access to outbound trunks
===============================

DIDWW Outbound Trunks provide local and international voice termination for
operators and businesses, ensuring high-quality and reliable call routing.

Outbound trunks are not enabled by default. To activate them on your account
and start placing outbound calls, you must request access and fill in a short
Outbound Voice Trunk Application Form — an approval step that confirms your
eligibility, including a Business Account with Company Name and VAT/TAX ID.

Before you begin
================

An active DIDWW account is required. `Sign in to DIDWW
<https://my.didww.com/users/sign_in>`_ or `Create DIDWW account
<https://my.didww.com/users/sign_up#/users/sign_up>`_.

Service availability and eligibility
=====================================

Outbound Trunks access is subject to an eligibility and application review.
It is not enabled automatically when you sign up. As part of the
application, you select an anticipated usage type (Wholesale or Business)
and the regions you intend to call. Some regions require additional
registration information before DIDWW can approve traffic to them. You can
leave a region disabled if you do not need it. Requirements can differ
between Wholesale and Business usage, as shown in the application fields
below.

Step 1: Open Outbound Trunks
============================

1. On the DIDWW User Panel Menu, click **Voice**.
2. Click **Outbound Trunks**.

.. figure:: https://doc.didww.com/_images/access_fig1.png
   :figclass: align-center
   :alt: Outbound Trunks menu in the DIDWW User Panel

   **Fig. 1.** Open Outbound Trunks

Step 2: Request access
======================

Click **Get Access**.

.. note::

   - For a **Personal Account** without a **Company Name** or **VAT/TAX
     ID**, complete **Step 1: Account Details** and upgrade to a
     **Business Account**.
   - For a **Business Account** without a **Company Website** or
     **VAT/TAX ID**, add the missing details in **Step 1: Account
     Details**.

.. figure:: https://doc.didww.com/_images/access_fig2.png
   :figclass: align-center
   :alt: Get Access button on the Outbound Trunks page

   **Fig. 2.** Start the access request

.. _user_panel_voice_out_get_access_step3:

Step 3: Complete the application
================================

Provide the required **General Information** and select the appropriate
**Anticipated Usage**:

- **Wholesale**: Your organization resells DIDWW termination routes to
  downstream vendors or customers.
- **Business**: Your organization uses DIDWW termination for its own business
  communications.

.. figure:: https://doc.didww.com/_images/access_fig3.png
   :figclass: align-center
   :alt: Outbound Voice Trunk Application form

   **Fig. 3.** Complete the application

The form fields change based on the selected **Anticipated Usage**. The table
below explains what to enter in each field and whether it applies to both
application types or only to **Wholesale**.

.. list-table::
   :header-rows: 1
   :widths: 32 48 20

   * - **Field**
     - **Description**
     - **Applies to**
   * - **Principal Activities of the Company** (*Required*)
     - Describe your company's main business activities.
     - Wholesale and Business
   * - **Service Usage Description** (*Required*)
     - Describe how the outbound service will be used.
     - Wholesale and Business
   * - **Target Regions** (*Required*)
     - Select the regions to which calls will be sent.
     - Wholesale and Business
   * - **Estimated Monthly Volume (min)** (*Required*)
     - Enter the expected monthly call volume in minutes.
     - Wholesale and Business
   * - **Average Call Duration (ACD) (sec)** (*Required for Wholesale*)
     - Enter the estimated average call duration in seconds.
     - Wholesale only
   * - **Answer-Seizure Ratio (ASR%)** (*Required for Wholesale*)
     - Enter the expected percentage of attempted calls that are answered.
     - Wholesale only
   * - **Calls Per Second (CPS)** (*Required for Wholesale*)
     - Enter the expected number of call attempts per second.
     - Wholesale only

.. _user_panel_voice_out_get_access_step4:

Step 4: Provide regional information when required
==================================================

Some selected target regions require additional information:

- **North America**: If you selected **Anticipated Usage** as **Wholesale**
  and plan to use your outbound trunk for destinations in the **United
  States**, you must provide your FCC Registration Number (FRN). This step
  is not required if you selected **Anticipated Usage** as **Business**.
- **Europe**: If you plan to use your outbound trunk for destinations in the
  **United Kingdom**, additional information is required.
- **Asia & Asia Pacific**: If you plan to use your outbound trunk for
  destinations in **Singapore** or **Hong Kong**, additional information is
  required.

.. note::

   Toggle off a target region if you do not want to submit its additional
   information.

.. figure:: https://doc.didww.com/_images/access_fig4.png
   :figclass: align-center
   :alt: Additional application requirements for selected target regions

   **Fig. 4.** Provide regional information

Step 5: Submit the application
==============================

Click **Submit** to send your request. You will receive an email
notification within **48 business hours** confirming service activation or
requesting additional information.

Once the application is approved, the **Outbound
Trunks** page allows you to create a trunk. If access is not available
after receiving an approval notification, contact `DIDWW Customer
Care <mailto:customer.care@didww.com>`_ for more details.

.. figure:: https://doc.didww.com/_images/access_fig5.png
   :figclass: align-center
   :alt: Submit button on the Outbound Voice Trunk Application

   **Fig. 5.** Submit the application

Next steps
==========

.. grid:: 1 2 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create an outbound trunk**
      :link: how-to-guides/create-outbound-trunk
      :link-type: doc

      Configure your first outbound trunk now that access is approved.

   .. grid-item-card:: :octicon:`number` **Outbound dialing**
      :link: routing-dialing/outbound-dialing
      :link-type: doc

      Review number formats, local routes, and short-number dialing.


.. _outbound_trunk_create_trunk:

=========================
Create an outbound trunk
=========================

Create an outbound SIP trunk to route voice traffic to external destinations
through DIDWW. Outbound service must be approved for your account.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- Access to **DIDWW Outbound Trunks** is required. :doc:`../get-access` if
  you have not requested it yet.

Step 1: Open the creation form
==============================

1. In the DIDWW User Panel, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Create New menu on the Outbound Trunks page

   **Fig. 1.** Create an outbound trunk

Step 2: Configure general and authentication settings
=====================================================

1. Under **General**, enter a **Friendly name**.
2. Select the **Authentication method**.
3. Complete the fields for the selected authentication method:

   - For **Credentials & IP-Based**, enter at least one **Allowed SIP IP
     address**.
   - For **Twilio Account SID**, enter the **Account SID**.

.. note::

   To use **IP-Only** authentication method, contact
   `support@didww.com <mailto:support@didww.com>`_.

Additional field definitions, available values, and constraints are
listed in :ref:`General settings <outbound_trunk_create_general>` and
:ref:`Authentication settings <outbound_trunk_create_authentication>`.

.. figure:: https://doc.didww.com/_images/fig3.webp
   :figclass: align-center
   :alt: Authentication settings on the Create Outbound Trunk page

   **Fig. 2.** Configure authentication

Step 3: Configure media
=======================

1. Expand **Media**.
2. Configure your preferred media settings.

Field definitions, available values, and constraints are listed in
:ref:`Media settings <outbound_trunk_create_media>`.

.. figure:: https://doc.didww.com/_images/media_settings.webp
   :figclass: align-center
   :alt: Media settings for an outbound trunk

   **Fig. 3.** Configure media

Step 4: Configure termination
=============================

Expand **Termination**, then configure the trunk limits, allowed Caller IDs,
and destination dialing restrictions.

Limits and notifications
------------------------

Configure the rolling 24-hour limit, capacity limit, and usage limit
notification.

Field definitions, available values, and constraints are listed in
:ref:`Limits and notifications <outbound_trunk_limits_and_notification>`.

.. figure:: https://doc.didww.com/_images/termination-limits.webp
   :figclass: align-center
   :alt: Limits and notifications for an outbound trunk

   **Fig. 4.** Configure limits and notifications

CLI settings
------------

Allow any DID(s) to be used via the trunk or configure which Caller IDs the trunk can use.

Field definitions, available values, and constraints are listed in
:ref:`CLI settings <outbound_trunk_cli_settings>`.

.. figure:: https://doc.didww.com/_images/termination-cli-settings.webp
   :figclass: align-center
   :alt: CLI settings for an outbound trunk

   **Fig. 5.** Configure CLI settings

Destination dialing settings
----------------------------

Configure the destinations that the trunk can call.

Field definitions, available values, and constraints are listed in
:ref:`Destination dialing settings <outbound_trunk_dialing_mode_values>`.

.. figure:: https://doc.didww.com/_images/termination-destination-settings.webp
   :figclass: align-center
   :alt: Destination dialing settings for an outbound trunk

   **Fig. 6.** Configure destination dialing settings

Step 5: Configure emergency calling (optional)
==============================================

If the trunk will be used for emergency calls, expand **Emergency Calling**
and configure the emergency calling settings.

Emergency calling requires an eligible DID with an activated emergency
service. If the service is not active yet,
:doc:`../../emergency-calling/create-emergency-calling-service`. The
complete trunk-side setup is covered in
:doc:`../../emergency-calling/configure-emergency-calling-for-outbound-trunks`.
Field definitions, available values, and constraints are listed in
:ref:`Emergency calling settings <outbound_trunk_create_emergency>`.

.. figure:: https://doc.didww.com/_images/emergency-calling-settings.webp
   :figclass: align-center
   :alt: Emergency Calling settings for an outbound trunk

   **Fig. 7.** Configure emergency calling

Step 6: Create the trunk
========================

1. Review the final trunk configuration.
2. Click **Create**.

The new trunk appears on the **Outbound Trunks** page.

.. figure:: https://doc.didww.com/_images/create-outbound-trunk.webp
   :figclass: align-center
   :alt: Create button on the Create Outbound Trunk page

   **Fig. 8.** Create the outbound trunk

Next steps
==========

- If the trunk has **Disabled** status, :doc:`enable-disable-outbound-trunk`
  before sending calls. Status behavior is listed in :ref:`Status values
  <outbound_trunk_status_values>`.
- For a trunk that uses **Credentials & IP-Based** authentication, DIDWW
  generates SIP credentials after the trunk is created. To view them,
  :doc:`view-outbound-trunk-credentials`, then configure the credentials in
  your voice equipment.


.. _delete_outbound_trunks:

=======================
Delete outbound trunks
=======================

Deleting a trunk removes its configuration and prevents further calls
through it.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_.
- An existing outbound trunk that you no longer need.

.. warning::

   Deleting a trunk is permanent and cannot be undone. Make sure the trunk
   is no longer needed before you continue.

Delete a single trunk
=====================

1. In the DIDWW User Panel, go to **Voice > Outbound Trunks**.
2. Locate the trunk and click the actions button.
3. Click **Delete**.
4. In the confirmation dialog, click **Delete**.

.. figure:: https://doc.didww.com/_images/actions_delete.png
   :figclass: align-center
   :alt: Delete action for an outbound trunk

   **Fig. 1.** Delete one trunk

Delete multiple trunks
======================

1. Select the trunks on the **Outbound Trunks** page.
2. Click **Batch Actions > Delete**.
3. In the confirmation dialog, click **Delete**.

.. figure:: https://doc.didww.com/_images/delete_batch_actions.png
   :figclass: align-center
   :alt: Delete action in the Batch Actions menu

   **Fig. 2.** Delete several trunks


.. _edit_outbound_trunks:

=======================
Edit an outbound trunk
=======================

Update the configuration of an existing outbound trunk in the DIDWW User
Panel.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_.
- An existing outbound trunk is required. :doc:`create-outbound-trunk` if you do
  not have one yet.

Step 1: Open the outbound trunk edit form
=========================================

1. In the DIDWW User Panel, go to **Voice > Outbound Trunks**.
2. Locate the trunk and click the actions button.
3. Click **Edit**.

.. figure:: https://doc.didww.com/_images/edit-outbound-trunk-action.webp
   :figclass: align-center
   :alt: Edit option in the actions menu for an outbound trunk

   **Fig. 1.** Open the outbound trunk edit form

Step 2: Update the trunk settings
==================================

Update any of the trunk's settings under **General**, **Authentication**,
**Media**, **Termination**, and **Emergency Calling**. Field definitions,
available values, and constraints are listed in
:doc:`../outbound-trunk-reference`.

.. figure:: https://doc.didww.com/_images/edit-outbound-trunk-settings.webp
   :figclass: align-center
   :alt: General and authentication settings on the Edit Outbound Trunk form

   **Fig. 2.** Update the trunk settings

Step 3: Save the changes
========================

1. Review the updated configuration.
2. Click **Submit**.

.. figure:: https://doc.didww.com/_images/edit-outbound-trunk-submit.webp
   :figclass: align-center
   :alt: Submit button on the Edit Outbound Trunk form

   **Fig. 3.** Save the outbound trunk changes


.. _outbound_trunk_toggle_status:

===================================
Enable or disable an outbound trunk
===================================

Use the **Status** toggle to stop or resume outbound traffic without
deleting the trunk.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_.
- An existing outbound trunk is required. :doc:`create-outbound-trunk` if
  you do not have one yet.

Step 1: Locate the trunk
=========================

In the DIDWW User Panel, go to **Voice > Outbound Trunks** and locate the
trunk.

.. figure:: https://doc.didww.com/_images/enable-disable-outbound-trunk-toggle1.webp
   :figclass: align-center
   :alt: Status toggle for an outbound trunk

   **Fig. 1.** Locate the trunk

Step 2: Enable or disable the trunk
=====================================

Use the **Status** toggle to enable or disable the trunk. The action takes effect immediately.

.. important:: Disabling blocks all outbound calls through the trunk.

:ref:`Status values <outbound_trunk_status_values>` in the Outbound trunk
reference explain what each status means, including automatic disabling
when the rolling 24-hour limit is reached.

.. figure:: https://doc.didww.com/_images/enable-disable-outbound-trunk-toggle2.webp
   :figclass: align-center
   :alt: Disable Outbound Trunk confirmation dialog

   **Fig. 2.** Confirm disabling the trunk



.. _outbound_trunk_create:

==============
How-to guides
==============

Use these guides to create and manage outbound SIP trunks in the DIDWW User
Panel.

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create an outbound trunk**
      :link: create-outbound-trunk
      :link-type: doc

      Create a trunk and configure authentication, media, routing, Caller ID,
      and service limits.

   .. grid-item-card:: :octicon:`key` **View outbound trunk credentials**
      :link: view-outbound-trunk-credentials
      :link-type: doc

      Copy the SIP digest credentials for a trunk.

   .. grid-item-card:: :octicon:`sync` **Regenerate outbound trunk credentials**
      :link: regenerate-outbound-trunk-credentials
      :link-type: doc

      Replace the SIP digest password for a trunk.

   .. grid-item-card:: :octicon:`pencil` **Edit an outbound trunk**
      :link: edit-outbound-trunk
      :link-type: doc

      Change an existing trunk configuration.

   .. grid-item-card:: :octicon:`sliders` **Enable or disable an outbound trunk**
      :link: enable-disable-outbound-trunk
      :link-type: doc

      Stop or resume outbound traffic without deleting the trunk.

   .. grid-item-card:: :octicon:`trash` **Delete outbound trunks**
      :link: delete-outbound-trunk
      :link-type: doc

      Delete one trunk or several trunks with a batch action.

.. toctree::
   :hidden:

   create-outbound-trunk
   view-outbound-trunk-credentials
   regenerate-outbound-trunk-credentials
   edit-outbound-trunk
   enable-disable-outbound-trunk
   delete-outbound-trunk


.. _view_outbound_trunk_credentials:

=================================
View outbound trunk credentials
=================================

View the SIP digest credentials and DIDWW signaling endpoints for a trunk
that uses **Credentials & IP-Based** authentication.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_.
- An existing outbound trunk using **Credentials & IP-Based** authentication
  is required. :doc:`create-outbound-trunk` or :doc:`edit-outbound-trunk`
  if you need to create or switch to this method.

Step 1: Open the SIP Credentials window
========================================

1. In the DIDWW User Panel, go to **Voice > Outbound Trunks**.
2. Locate the trunk and click the key icon in the **Credentials** column.

.. figure:: https://doc.didww.com/_images/outbound-trunk-credentials-open.webp
   :figclass: align-center
   :alt: Credentials tooltip on the Outbound Trunks page

   **Fig. 1.** Open the SIP Credentials window

Step 2: Copy the credentials
=============================

Copy the **Username** and **Password** values. Click the eye icon to reveal the password.

.. warning::

   Treat the password as a secret. If it is exposed,
   :doc:`regenerate-outbound-trunk-credentials`.

Field definitions are listed in :ref:`Credentials window fields
<outbound_trunk_credentials_fields>` in the Outbound trunk reference, and
endpoint selection and the fixed digest realm are covered in
:doc:`../outbound-sip-information`.

.. figure:: https://doc.didww.com/_images/view-outbound-trunk-credentials-copy.webp
   :figclass: align-center
   :alt: Username and password fields in the SIP Credentials window

   **Fig. 2.** Copy the credentials



.. _regenerate_outbound_trunk_credentials:

========================================
Regenerate outbound trunk credentials
========================================

Replace the SIP digest password for a trunk that uses **Credentials &
IP-Based** authentication.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_.
- An existing outbound trunk using **Credentials & IP-Based** authentication
  is required. :doc:`create-outbound-trunk` or :doc:`edit-outbound-trunk`
  if you need to create or switch to this method.

Step 1: Open the SIP Credentials window
========================================

1. In the DIDWW User Panel, go to **Voice > Outbound Trunks**.
2. Locate the trunk and click the key icon in the **Credentials** column.

.. figure:: https://doc.didww.com/_images/outbound-trunk-credentials-open.webp
   :figclass: align-center
   :alt: Credentials tooltip on the Outbound Trunks page

   **Fig. 1.** Open the SIP Credentials window

Step 2: Regenerate the password
=================================

Click the regenerate icon next to the password field to generate a new
password immediately.

.. warning::

   Regenerating replaces the password immediately. The previous password no
   longer authenticates requests. The username does not change. Update
   every system that uses the trunk with the new password at the same time
   you regenerate it, as described in :ref:`Credential lifecycle
   <outbound_trunk_credential_lifecycle>`.

Field definitions are listed in :ref:`Credentials window fields
<outbound_trunk_credentials_fields>` in the Outbound trunk reference.

.. figure:: https://doc.didww.com/_images/regenerate-outbound-trunk-credentials-regenerate.webp
   :figclass: align-center
   :alt: Regenerate icon in the SIP Credentials window

   **Fig. 2.** Regenerate the password


.. _user_panel_voice_out:
.. _termination-services-card:

================
Outbound trunks
================

An outbound SIP trunk connects your customer system to DIDWW termination
routes so you can place calls to local and international destinations. Each
trunk controls authentication, media, Caller ID, allowed destinations,
capacity, and spending.

.. important::

   Outbound trunks are not enabled automatically.
   :doc:`Request access <get-access>` before creating a trunk or placing
   outbound calls.

Key features
============

- Control simultaneous call capacity and rolling 24-hour spending limits.
- Choose from supported authentication methods and restrict signaling and
  media by IP address where applicable.
- Configure Caller ID numbers and allow or block destination prefixes.
- Use SIP over UDP, TCP, or TLS, with optional encrypted media.
- Place calls through local or global routes and use emergency calling in
  supported countries.
- Review per-trunk call records, statistics, and reports.
- Use redundant network infrastructure and customer-side failover options.

How outbound calls work
=======================

Your customer system sends a SIP ``INVITE`` to DIDWW. DIDWW identifies and
authenticates the outbound trunk according to its configured authentication
method, applies Caller ID and dialing rules, and routes the call to the
destination network for delivery to the called party.

.. mermaid::
   :alt: Outbound call flow through DIDWW to a called party.

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",
       "signalColor": "#0f766e",
       "signalTextColor": "#1f2d3d",
       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#14b8a6",
       "labelTextColor": "#1f2d3d",
       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#f59e0b",
       "noteTextColor": "#1f2d3d",
       "sequenceNumberColor": "#ffffff"
     }
   }}%%

   sequenceDiagram
      autonumber
      participant system as Customer System
      participant trunk as DIDWW
      participant network as Destination network
      participant callee as Called party

      system->>trunk: SIP INVITE
      Note over trunk: Authenticate the trunk<br/>Apply Caller ID and dialing rules
      trunk->>network: Route call
      network->>callee: Deliver call

See :doc:`Authentication and security <authentication-security>` for
authentication methods. See :doc:`Call-flow examples
<routing-dialing/call-flow-examples>` for complete Credentials & IP-Based and
IP-Only SIP exchanges.

.. dropdown:: Reliability and failover details

   Outbound call delivery uses several layers of redundancy across the DIDWW
   network and your customer system's connection:

   - DIDWW provides :ref:`network redundancy
     <voice-out-network-redundancy>` across multiple Points of Presence
     (PoPs), termination carriers, load balancers, and session border
     controllers (SBCs).
   - DIDWW maintains resilient connectivity through multi-homed IP transit and
     :ref:`direct interconnections <network_interconnection>` at major Internet
     Exchanges.
   - Use :ref:`DNS SRV <voice-out-dns-srv>` or
     :ref:`BGP Anycast <voice-out-bgp-anycast>` for customer-side failover, or
     :doc:`create multiple outbound trunks
     <how-to-guides/create-outbound-trunk>` to distribute traffic.

   For signaling, network architecture, and failover details, see
   :doc:`Outbound SIP information <outbound-sip-information>`.

Get started
===========

Choose the path that matches your account:

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`key` **Get access to outbound trunks**
      :link: get-access
      :link-type: doc

      Start here if outbound trunks are not enabled on your account.

   .. grid-item-card:: :octicon:`plus` **Create an outbound trunk**
      :link: how-to-guides/create-outbound-trunk
      :link-type: doc

      Create your first trunk after outbound trunk access is enabled.

Configure, manage, and monitor outbound calling
===============================================

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`checklist` **How-to guides**
      :link: how-to-guides/index
      :link-type: doc

      Edit, enable, disable, or delete trunks, and manage trunk credentials.

   .. grid-item-card:: :octicon:`shield-lock` **Authentication and security**
      :link: authentication-security
      :link-type: doc

      Understand authentication methods and controls that reduce unauthorized
      use and toll fraud.

   .. grid-item-card:: :octicon:`git-branch` **Routing and dialing**
      :link: routing-dialing/index
      :link-type: doc

      Configure number formats, local routes, call forwarding, and destination
      restrictions.

   .. grid-item-card:: :octicon:`person` **Caller ID and CNAM OUT**
      :link: caller-id-cnam-out
      :link-type: doc

      Configure the calling number and Caller Name Delivery (CNAM OUT).

   .. grid-item-card:: :octicon:`graph` **Analytics and troubleshooting**
      :link: analytics-troubleshooting
      :link-type: doc

      Review outbound call logs, statistics, and reports, and isolate common
      configuration problems.

Trust and compliance
====================

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`verified` **STIR/SHAKEN for outbound trunks**
      :link: stir-shaken-outbound
      :link-type: doc

      Understand DIDWW attestation and customer-generated Identity header
      relay.

   .. grid-item-card:: :octicon:`law` **Robocall mitigation and call labeling**
      :link: robocall-mitigation/index
      :link-type: doc

      Understand call labeling and applicable US robocall compliance
      requirements.

Technical references
====================

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`server` **Outbound SIP information**
      :link: outbound-sip-information
      :link-type: doc

      Find signaling endpoints, transports, media networks, codecs,
      encryption, registration, and SIP header details.

   .. grid-item-card:: :octicon:`list-unordered` **Outbound trunk reference**
      :link: outbound-trunk-reference
      :link-type: doc

      Find definitions, values, and status behavior for every field on the
      Outbound Trunks page and in the trunk creation and edit forms.

Related resources
==================

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`server` **Emergency calling**
      :link: ../emergency-calling/index
      :link-type: doc

      Register an eligible DID for emergency calling and activate the service
      required for outbound emergency calls.

   .. grid-item-card:: :octicon:`arrow-switch` **Inbound trunks**
      :link: ../inbound-trunks/index
      :link-type: doc

      Create and manage inbound voice trunks for call routing.

   .. grid-item-card:: :octicon:`device-mobile` **My numbers**
      :link: ../../phone-numbers/my-numbers/index
      :link-type: doc

      Manage the DID numbers assigned to your account and their trunks.

   .. grid-item-card:: :octicon:`download` **Download pricelists**
      :link: services_coverage_pricing_access_pricelists
      :link-type: ref

      Download public or account-specific SIP trunking pricelists.

.. toctree::
   :hidden:

   get-access
   how-to-guides/index
   authentication-security
   routing-dialing/index
   caller-id-cnam-out
   stir-shaken-outbound
   robocall-mitigation/index
   analytics-troubleshooting
   outbound-sip-information
   outbound-trunk-reference


.. _outbound-dialing-card:

===================
Routing and dialing
===================

Use these pages to format destination and Caller ID numbers, understand local
route selection, configure Diversion-based call forwarding, and compare SIP
call flows for supported authentication methods.

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`number` **Outbound dialing**
      :link: outbound-dialing
      :link-type: doc

      Format destination and Caller ID numbers and understand local-route
      selection and availability.

   .. grid-item-card:: :octicon:`arrow-switch` **Call forwarding**
      :link: call-forwarding
      :link-type: doc

      Configure Diversion-based call forwarding and review supported
      countries.

   .. grid-item-card:: :octicon:`workflow` **Call flow examples**
      :link: call-flow-examples
      :link-type: doc

      Compare the SIP message exchanges for Credentials & IP-Based and IP-Only
      trunks.

.. toctree::
   :hidden:

   outbound-dialing
   call-forwarding
   call-flow-examples


.. _outbound_dialing:

================
Outbound dialing
================

Outbound calls use E.164 number formatting for destination numbers and Caller
IDs. The called destination, presented Caller ID, and available coverage
determine how each call is routed.

A call can use an in-country local route when the destination and an eligible
DIDWW local DID used as Caller ID belong to the same country and local coverage
is available. Calls that do not meet these conditions use another available
route. Some destinations may also use origin-based pricing, where the rate is
determined from the country represented by the Caller ID.

Number format
=============

Calls to the :ref:`DIDWW Outbound gateway <voice-out-signaling-endpoints>`
should be sent in the E.164 dialing format: country code + area code +
subscriber number. Any leading prefixes such as ``00`` or ``+`` will be
automatically removed before being passed to the PSTN. The same rule applies
for Caller ID. For example::

   To: Bob <sip:12025550199@out.didww.com>
   From: Alice <sip:12025550100@caller.example>

The numbers in this example are from the NANPA range reserved for fictional
use.

Caller ID formatting, presentation, and CNAM behavior are covered in
:doc:`../caller-id-cnam-out`.

.. note::

   To block calls to unwanted destinations, update the :ref:`Destination
   dialing settings <dialing_settings>` on your outbound trunk.

How route selection works
==========================

Route selection is automatic and is based on the destination, presented Caller
ID, and available coverage:

- **Local route:** Used when the destination and an eligible DIDWW local DID
  presented as Caller ID belong to the same country, and an in-country route
  is available.
- **Origin-based route:** Used for affected destinations where the rate is
  determined from the country represented by the Caller ID. This is separate
  from local routing. See :ref:`Origin-based pricing
  <origin_based_pricing>`.
- **International route:** Used when the local-route conditions are not met or
  local coverage is unavailable, and origin-based pricing does not apply.

.. _outbound_dialing_local_routes:

Local routes
============

Local routes, also referred to as in-country routes, enable calling
destinations that may be unreachable when routed via international networks,
such as toll-free, shared-cost, or emergency numbers.

When an eligible DIDWW local DID from the destination country is used as Caller
ID and a corresponding in-country route is available, the call is
automatically routed via the local route. Using local routes is generally more
cost-effective compared to international routing, as local termination rates
typically apply.

Local routes are available in the following countries:

.. csv-table::
   :file: country_list_local_routes.csv
   :header-rows: 0
   :align: left
   :widths: auto

.. [1] For dialing Argentinian mobile numbers, the digit ``9`` must be added
       after the country code. For example, ``54 9 XXX XXX XXXX``.

.. note::

   The listed countries require DIDWW DIDs to be used as Caller ID for local
   dialing. For more information and country-specific restrictions, contact
   the DIDWW Sales department at `sales@didww.com <mailto:sales@didww.com>`_.

Related resources
==================

- :doc:`../caller-id-cnam-out` — Configure Caller ID formatting and CNAM
  behavior.
- :doc:`call-flow-examples` — Follow Credentials & IP-Based and IP-Only
  outbound SIP calls.
- :doc:`../outbound-trunk-reference` — Look up destination dialing
  settings and values.
- :doc:`../outbound-sip-information` — Find SIP endpoints and transport
  details.


.. _call_forwarding:

===============
Call forwarding
===============

Automatically redirect incoming calls from your DID number to another
destination using local in-country routing. Forwarded calls are delivered
through your configured outbound trunk, with diversion routing enabled to
preserve the original caller and DID information, ensuring callers can still
reach you even when your primary device or platform is unavailable.

Concrete telephone numbers in this page use the NANPA range reserved for
fictional use.

Call forwarding through this service is supported only for
:ref:`local routes <outbound_dialing_local_routes>`.

How diversion routing works
===========================

Diversion routing is a SIP-based mechanism used to redirect inbound calls to
another destination by including the SIP ``Diversion`` header in the
signaling. The PBX or SBC includes this header, defined in
`RFC 5806 <https://datatracker.ietf.org/doc/html/rfc5806>`_, when it forwards
the call. The header carries the originally called DID and diversion reason.
DIDWW validates that the DID belongs to the account and uses the corresponding
local route.

Requirements
------------

- Equipment that supports the SIP ``Diversion`` header.
- A DID with the **Local CLI** feature, available through :ref:`How to buy
  numbers <user_panel_purchase>`.
- An active outbound trunk. :ref:`Create an outbound trunk
  <outbound_trunk_create_trunk>` if you do not have one yet.
- Diversion service enabled on the outbound trunk.

.. important::

   To enable diversion routing on your outbound trunk, request activation of
   the diversion service by contacting `DIDWW Customer Support
   <mailto:support@didww.com>`_.

Call flow
---------

1. An inbound call arrives on the DID.
2. DIDWW sends the inbound call to the PBX or SBC.
3. When forwarding the call, the PBX or SBC sends it through a
   diversion-enabled outbound trunk and adds or preserves a ``Diversion``
   header containing the originally called DID. For example::

      Diversion: <sip:+12025550199@sip.didww.com>;reason=unconditional

4. DIDWW validates that the DID in the header belongs to the account.
5. DIDWW routes the call through the local in-country termination partner.

.. note::

   Forwarded calls should be sent only through an outbound trunk with the
   diversion service enabled.

.. dropdown:: Call Flow Diagram
   :icon: workflow
   :animate: fade-in

   .. mermaid::

      sequenceDiagram
          autonumber
          participant C as Caller
          participant DIn as DIDWW inbound trunk
          participant PBX as PBX or SBC
          participant DOut as DIDWW outbound trunk
          participant P as PSTN destination

          C->>DIn: INVITE to DID (+12025550199)
          DIn->>PBX: Deliver inbound call
          PBX->>DOut: INVITE to forwarded number with Diversion header
          DOut->>DOut: Validate DID in Diversion header
          DOut->>P: Route call
          P-->>DOut: 200 OK
          DOut-->>PBX: 200 OK
          PBX-->>DIn: 200 OK
          DIn-->>C: 200 OK
          Note over C,P: Call connected and media follows the negotiated path

.. dropdown:: Use Cases
   :icon: light-bulb
   :animate: fade-in

   - **Unconditional Forwarding (CFU)** – Forward all calls immediately to
     another destination (e.g., voicemail or mobile), preserving the original
     DID and diversion reason.
   - **Call Forward on Busy (CFB)** – Redirect callers to another endpoint
     when the primary device is busy.
   - **Call Forward on No-Answer (CFNA)** – Divert calls after a timeout period
     while keeping the original caller ID and DID.
   - **Call Forward on Unavailable (CFUNV)** – Route calls to backup numbers
     when the endpoint is offline or unreachable.
   - **Automatic Call Distribution (ACD)** – Divert calls to queues or
     after-hours destinations while retaining the full diversion chain.
   - **Voicemail** – Deliver calls to voicemail systems with the correct
     diversion reason and original called number.
   - **Call Tracking** – Preserve campaign/source identifiers by maintaining
     the original DID in the Diversion header.

Supported countries for diversion routing
==========================================

.. csv-table::
   :widths: auto

   Argentina, Australia, Austria, Belgium, Bosnia and Herzegovina
   Brazil, Bulgaria, Canada, Czech Republic, Chile
   Croatia, Denmark, Finland, France, Georgia
   Germany [1]_, Greece, Iceland, Ireland, Israel
   Italy [2]_, Lithuania, Luxembourg, Malta, Mexico
   Netherlands, New Zealand, Nigeria, Norway, Panama
   Peru, Poland [2]_, Portugal [3]_, Puerto Rico, Serbia
   Slovakia, South Africa, Spain, Sweden [1]_, Switzerland [1]_
   Thailand [1]_, United Kingdom, United States

.. [1] Additional prerequisites apply for Germany, Sweden, Switzerland, and
       Thailand. Contact `DIDWW Customer Support
       <mailto:support@didww.com>`_ for details.
.. [2] Only local DID numbers are supported.
.. [3] Only National DID group **351-30** supports diversion.

Related resources
==================

- :doc:`outbound-dialing` — Understand local route requirements and
  destination formatting.
- :doc:`../caller-id-cnam-out` — Configure Caller ID formatting and CNAM
  behavior.
- :doc:`../outbound-sip-information` — Find SIP endpoints and transport
  details.


.. _outbound_call_flow_examples:

==================
Call flow examples
==================

Successful outbound call setup differs according to the trunk's authentication
method. **Credentials & IP-Based** trunks validate the source IP address and
use a SIP Digest challenge before call routing continues. **IP-Only** trunks
identify and authenticate the trunk from the source IP address without a
Digest challenge.

Each diagram follows the signaling sequence from the originating SIP endpoint,
through the DIDWW outbound trunk, to the destination network. Expand a numbered
stage below a diagram to view representative SIP request and response lines.

.. note::

   The diagrams and SIP messages are simplified examples. The IP addresses,
   telephone numbers, credentials, and Digest values are illustrative only.
   Each example includes only the message lines needed to explain the flow and
   omits unrelated headers and SDP bodies. For the complete SIP Digest exchange
   and authentication rules, see
   :ref:`Authentication flow <outbound_trunk_authentication_flow>`.

Credentials & IP-Based trunk
============================

The originating SIP endpoint first sends an ``INVITE`` without credentials.
DIDWW challenges the request, and the endpoint acknowledges the challenge
before retrying the ``INVITE`` with an ``Authorization`` header. After DIDWW
accepts the request, call setup continues.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",
       "signalColor": "#0066cc",
       "signalTextColor": "#1f2d3d",
       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#facc15",
       "noteTextColor": "#1f2d3d",
       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d",
       "loopTextColor": "#1f2d3d",
       "sequenceNumberColor": "#ffffff"
     }
   }}%%
   sequenceDiagram
       autonumber
       participant ORIGIN as Originating SIP endpoint
       participant DIDWW as DIDWW outbound trunk
       participant PSTN as Destination network (PSTN)

       ORIGIN->>DIDWW: INVITE without Authorization
       DIDWW-->>ORIGIN: 100 Trying
       DIDWW-->>ORIGIN: 401 Unauthorized with WWW-Authenticate
       ORIGIN->>DIDWW: ACK
       ORIGIN->>DIDWW: INVITE with Authorization
       DIDWW-->>ORIGIN: 100 Trying
       DIDWW->>PSTN: Route call
       PSTN-->>DIDWW: 18x provisional response
       DIDWW-->>ORIGIN: 18x provisional response
       PSTN-->>DIDWW: 200 OK
       DIDWW-->>ORIGIN: 200 OK with SDP
       ORIGIN->>DIDWW: ACK
       Note over ORIGIN,DIDWW: RTP media follows the negotiated path
       ORIGIN->>DIDWW: BYE
       DIDWW->>PSTN: BYE
       PSTN-->>DIDWW: 200 OK
       DIDWW-->>ORIGIN: 200 OK

Expand a stage to view its representative SIP messages.

.. dropdown:: 1. Initial INVITE
   :icon: file-code
   :animate: fade-in

   The originating SIP endpoint sends the first ``INVITE`` without an
   ``Authorization`` header::

      INVITE sip:12025550199@out.didww.com SIP/2.0
      Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK-example-1;rport
      From: <sip:12025550100@sbc.example.com>;tag=example-from-tag
      To: <sip:12025550199@out.didww.com>
      Call-ID: example-call-id@sbc.example.com
      CSeq: 102 INVITE
      Contact: <sip:12025550100@192.0.2.10:5060>
      Content-Type: application/sdp

   DIDWW checks the source IP address against the trunk's **Allowed SIP IP
   addresses** before continuing with SIP Digest authentication.

.. dropdown:: 2. Authentication challenge and ACK
   :icon: file-code
   :animate: fade-in

   DIDWW responds with ``401 Unauthorized`` and provides the realm, nonce,
   and quality-of-protection value in ``WWW-Authenticate``. DIDWW may first
   send ``100 Trying`` while it processes the initial ``INVITE``::

      SIP/2.0 401 Unauthorized
      From: <sip:12025550100@sbc.example.com>;tag=example-from-tag
      To: <sip:12025550199@out.didww.com>;tag=example-to-tag
      Call-ID: example-call-id@sbc.example.com
      CSeq: 102 INVITE
      WWW-Authenticate: Digest realm="out.didww.com", qop="auth",
       nonce="example-nonce"
      Content-Length: 0

   The originating SIP endpoint acknowledges the final response to the first
   transaction::

      ACK sip:12025550199@out.didww.com SIP/2.0
      Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK-example-1;rport
      From: <sip:12025550100@sbc.example.com>;tag=example-from-tag
      To: <sip:12025550199@out.didww.com>;tag=example-to-tag
      Call-ID: example-call-id@sbc.example.com
      CSeq: 102 ACK
      Content-Length: 0

.. dropdown:: 3. Authenticated INVITE
   :icon: file-code
   :animate: fade-in

   The originating SIP endpoint calculates the digest response using the
   trunk's SIP username and password, then sends a new ``INVITE`` with an
   ``Authorization`` header. The new transaction uses a new branch value and
   increments the ``CSeq`` number::

      INVITE sip:12025550199@out.didww.com SIP/2.0
      Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK-example-2;rport
      From: <sip:12025550100@sbc.example.com>;tag=example-from-tag
      To: <sip:12025550199@out.didww.com>
      Call-ID: example-call-id@sbc.example.com
      CSeq: 103 INVITE
      Contact: <sip:12025550100@192.0.2.10:5060>
      Authorization: Digest username="example-username", realm="out.didww.com",
       nonce="example-nonce", uri="sip:12025550199@out.didww.com",
       response="00000000000000000000000000000000", qop=auth,
       cnonce="example-cnonce", nc=00000001
      Content-Type: application/sdp

   The Digest values above are syntactically valid placeholders, not working
   credentials. The originating SIP endpoint must calculate the actual
   response from the challenge and the trunk's credentials.

.. dropdown:: 4. Call establishment
   :icon: file-code
   :animate: fade-in

   After DIDWW validates the source IP address and digest credentials, it
   accepts the transaction and routes the call. The provisional and final
   responses use the same ``Call-ID`` and ``CSeq`` as the authenticated
   ``INVITE``::

      SIP/2.0 100 Trying
      Call-ID: example-call-id@sbc.example.com
      CSeq: 103 INVITE

      SIP/2.0 180 Ringing
      Call-ID: example-call-id@sbc.example.com
      CSeq: 103 INVITE

      SIP/2.0 200 OK
      Call-ID: example-call-id@sbc.example.com
      CSeq: 103 INVITE
      Content-Type: application/sdp

   The originating SIP endpoint confirms the established dialog with an
   ``ACK``. RTP media then follows the path negotiated in the SDP offer and
   answer::

      ACK sip:12025550199@out.didww.com SIP/2.0
      Call-ID: example-call-id@sbc.example.com
      CSeq: 103 ACK

   After ``100 Trying``, the originating SIP endpoint waits for another
   provisional or final response. Depending on the destination network, it
   may receive ``180 Ringing``, ``183 Session Progress``, another
   provisional response, or a final response without an additional
   provisional response.

.. dropdown:: 5. Call termination
   :icon: file-code
   :animate: fade-in

   Either endpoint can end the call by sending ``BYE``. The receiving
   endpoint confirms the request with ``200 OK``::

      BYE sip:12025550199@out.didww.com SIP/2.0
      Call-ID: example-call-id@sbc.example.com
      CSeq: 104 BYE

      SIP/2.0 200 OK
      Call-ID: example-call-id@sbc.example.com
      CSeq: 104 BYE

IP-Only trunk
=============

For an **IP-Only** trunk, DIDWW identifies and authenticates the trunk from
the source IP address. The originating SIP endpoint sends the initial
``INVITE`` without an ``Authorization`` header, and DIDWW does not issue a
SIP Digest challenge.

.. note::

   IP-Only authentication is not available for self-service selection. To
   request it, contact `DIDWW Customer Support <mailto:support@didww.com>`_.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",
       "signalColor": "#0066cc",
       "signalTextColor": "#1f2d3d",
       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#facc15",
       "noteTextColor": "#1f2d3d",
       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d",
       "loopTextColor": "#1f2d3d",
       "sequenceNumberColor": "#ffffff"
     }
   }}%%
   sequenceDiagram
       autonumber
       participant ORIGIN as Originating SIP endpoint
       participant DIDWW as DIDWW outbound trunk
       participant PSTN as Destination network (PSTN)

       ORIGIN->>DIDWW: INVITE without Authorization
       DIDWW->>DIDWW: Match the source IP to an IP-Only trunk
       DIDWW-->>ORIGIN: 100 Trying
       DIDWW->>PSTN: Route call
       PSTN-->>DIDWW: 18x provisional response
       DIDWW-->>ORIGIN: 18x provisional response
       PSTN-->>DIDWW: 200 OK
       DIDWW-->>ORIGIN: 200 OK with SDP
       ORIGIN->>DIDWW: ACK
       Note over ORIGIN,DIDWW: RTP media follows the negotiated path
       ORIGIN->>DIDWW: BYE
       DIDWW->>PSTN: BYE
       PSTN-->>DIDWW: 200 OK
       DIDWW-->>ORIGIN: 200 OK

Expand a stage to view its representative SIP messages.

.. dropdown:: 1. Initial INVITE
   :icon: file-code
   :animate: fade-in

   The originating SIP endpoint sends an ``INVITE`` from an IP address
   configured for the trunk. No ``Authorization`` header is required::

      INVITE sip:12025550198@out.didww.com SIP/2.0
      Via: SIP/2.0/UDP 192.0.2.20:5060;branch=z9hG4bK-ip-only;rport
      From: <sip:12025550101@sbc.example.com>;tag=ip-only-from-tag
      To: <sip:12025550198@out.didww.com>
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 201 INVITE
      Contact: <sip:12025550101@192.0.2.20:5060>
      Content-Type: application/sdp

.. dropdown:: 2. Source-IP validation and call establishment
   :icon: file-code
   :animate: fade-in

   After DIDWW matches ``192.0.2.20`` to the IP-Only trunk, it accepts the
   transaction without a ``401 Unauthorized`` response or authenticated
   ``INVITE`` retry. Call setup then continues with the normal provisional
   and final responses::

      SIP/2.0 100 Trying
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 201 INVITE

      SIP/2.0 180 Ringing
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 201 INVITE

      SIP/2.0 200 OK
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 201 INVITE
      Content-Type: application/sdp

   The originating SIP endpoint confirms the established dialog with an
   ``ACK``. RTP media then follows the path negotiated in the SDP offer and
   answer::

      ACK sip:12025550198@out.didww.com SIP/2.0
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 201 ACK

   After ``100 Trying``, the originating SIP endpoint waits for another
   provisional or final response. It does not send another request until a
   response requires one, such as the ``ACK`` sent after ``200 OK``.

.. dropdown:: 3. Call termination
   :icon: file-code
   :animate: fade-in

   Call termination is the same for both authentication methods. Either
   endpoint can send ``BYE``, and the receiving endpoint confirms it with
   ``200 OK``::

      BYE sip:12025550198@out.didww.com SIP/2.0
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 202 BYE

      SIP/2.0 200 OK
      Call-ID: ip-only-call-id@sbc.example.com
      CSeq: 202 BYE

Related resources
=================

- :doc:`../authentication-security` — Understand authentication methods,
  source-IP matching, and SIP Digest requirements.
- :doc:`../outbound-sip-information` — Find signaling endpoints, transports,
  and media requirements.
- `RFC 3261 <https://datatracker.ietf.org/doc/html/rfc3261>`_ — Defines SIP
  transactions, dialogs, requests, and responses.


.. _service_termination_stir_shaken:

===============================
STIR/SHAKEN for outbound trunks
===============================

STIR/SHAKEN allows terminating providers to verify the originating
provider's signed assertion about the caller and calling number. DIDWW
signs outbound calls by default and can instead relay a SIP ``Identity``
header that your system has already signed.

Purpose of STIR/SHAKEN
-----------------------

STIR (Secure Telephone Identity Revisited) and SHAKEN (Signature-based
Handling of Asserted information using toKENs) work together to address
caller ID spoofing, where a call presents a calling number the sender is
not authorized to use.

A signing provider attaches a cryptographically signed identity
assertion, called a PASSporT, to the SIP ``Identity`` header of an
outbound call. Intermediate networks are expected to relay this header.
A terminating provider verifies the signature and can show the result
to the called party or use it in call-labeling and analytics systems.

Attestation reflects what the signing provider knew and could verify
about the caller and the calling number at the moment the call
originated. It is not a guarantee that the call is legitimate, wanted, or
free from spam labeling downstream. STIR/SHAKEN also does not
authenticate your SIP trunk and does not encrypt signaling or media. Both
of those are handled separately, as described in
:doc:`authentication-security`.

Supported modes
---------------

DIDWW supports two outbound modes: signing calls itself by default, or
relaying a SIP ``Identity`` header that you have already signed.

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Mode
     - Signing party
     - Identity header behavior
     - Customer action
   * - Default DIDWW attestation
     - DIDWW
     - Any customer-provided header is not preserved
     - None
   * - Customer Identity header relay
     - Customer
     - Relayed unchanged
     - Request activation, generate a valid header

Default DIDWW attestation
^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, DIDWW applies STIR/SHAKEN attestation to outbound calls sent
through an outbound trunk:

- DIDWW generates the signed identity assertion for the call. Any SIP
  ``Identity`` header received from the customer is not preserved.
- The attestation level is assigned according to DIDWW policy and
  applicable regulatory requirements.

No additional configuration or action is required from the customer.

Customer Identity header relay
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you sign your own outbound calls, DIDWW can relay your SIP
``Identity`` header unchanged instead of generating its own:

- You are responsible for generating and providing a valid SIP
  ``Identity`` header.
- DIDWW does not generate or modify the SIP ``Identity`` header in this
  mode.
- The original SIP ``Identity`` header you provide is relayed unchanged.

To enable ``Identity`` header relay for your outbound trunks, contact
`DIDWW Sales <mailto:sales@didww.com>`_ or `DIDWW Customer Care
<mailto:customer.care@didww.com>`_ with a request to relay your identity
header for outbound calls.

.. note::
   - This configuration is applied per trunk. We recommend using a
     separate trunk for customer-signed traffic.
   - Activation is subject to technical and compliance review.

Attestation
-----------

STIR/SHAKEN defines three attestation levels. Each describes what the
signing provider could verify about the call at origination, not the
likelihood that the call is legitimate:

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Level
     - Signer verified the caller
     - Signer verified the number
     - Typical meaning
   * - A — Full attestation
     - Yes
     - Yes
     - The signing provider has a direct relationship with the caller and
       confirms the caller is authorized to use the calling number.
   * - B — Partial attestation
     - Yes
     - No
     - The signing provider has a direct relationship with the caller but
       cannot confirm authorization to use the calling number.
   * - C — Gateway attestation
     - No
     - No
     - The signing provider knows only where the call entered its
       network, such as an international gateway, and cannot verify the
       caller or the number.

A lower attestation level does not by itself indicate fraud, and a
higher level does not guarantee call completion, display, answer rate,
or exemption from spam-likely labeling. DIDWW determines the attestation
level used in the default mode according to its policy and applicable
regulatory requirements. If you use Identity header relay, you are
responsible for asserting only an attestation level you are authorized
to use.

Limitations
-----------

- Downstream verification and any caller-verification indicator shown to
  the called party depend on the terminating carrier and the receiving
  device or application, not on DIDWW.
- The SIP ``Identity`` header can be lost or replaced if a call transits
  a network segment that does not support STIR/SHAKEN.
- Call forwarding, retargeting, number portability, and international
  interconnection can all affect whether a signed identity survives to
  the terminating network.
- STIR/SHAKEN is separate from Caller ID presentation, CNAM OUT, and
  robocall reputation databases, described in
  :doc:`caller-id-cnam-out` and the
  :doc:`robocall-mitigation/index` section.

.. important::
   Successful signing or relay does not guarantee how a downstream
   provider labels or displays the call.

Related standards
-----------------

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`file` **RFC 8224**
      :link: https://datatracker.ietf.org/doc/html/rfc8224
      :link-type: url

      Defines how SIP Identity tokens are used to authenticate and verify calling numbers.

   .. grid-item-card:: :octicon:`file` **RFC 8225**
      :link: https://datatracker.ietf.org/doc/html/rfc8225
      :link-type: url

      Explains how to create and validate cryptographic tokens for Caller ID verification.

   .. grid-item-card:: :octicon:`file` **RFC 8226**
      :link: https://datatracker.ietf.org/doc/html/rfc8226
      :link-type: url

      Covers the use of certificates to establish authority over telephone numbers.

   .. grid-item-card:: :octicon:`file` **RFC 7340**
      :link: https://datatracker.ietf.org/doc/html/rfc7340
      :link-type: url

      Outlines challenges leading to unauthorized robocalling and Caller ID spoofing.

Related resources
-----------------

- :doc:`caller-id-cnam-out` — Configure Caller ID formatting and CNAM
  behavior.
- :doc:`authentication-security` — Understand trunk authentication and
  encryption, which are separate from signed caller identity.
- :doc:`outbound-sip-information` — Find SIP endpoints, transports, and
  protocol parameters.
- :doc:`routing-dialing/index` — Configure destination dialing and
  review call flow examples.
- :doc:`robocall-mitigation/index` — Review robocall compliance and
  call-labeling topics.


.. _services_voice_out:

========================
Outbound SIP information
========================

Use this reference to configure SIP signaling, authentication, media, and
connectivity monitoring for DIDWW outbound trunks.

.. _voice_out_network_transport:

Signaling endpoints
--------------------

Calls can be sent to any of our load balancers. Each load balancer operates
as a redundant cluster with multiple nodes using the same IP address.

Use the hostname rather than the raw IP address if your equipment
supports :ref:`DNS SRV <voice-out-dns-srv>`.

.. _voice-out-signaling-endpoints:

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Location
     - DNS A/AAAA record
     - LB IPv4 address
     - LB IPv6 address
   * - New York
     - nyc.us.out.didww.com
     - 46.19.209.44
     - 2a01:ad00:1:1::44
   * - Los Angeles
     - lac.us.out.didww.com
     - 46.19.212.54
     - 2a01:ad00:4:2::54
   * - Miami
     - mia.us.out.didww.com
     - 46.19.213.54
     - 2a01:ad00:5:2::54
   * - Frankfurt
     - fra.eu.out.didww.com
     - 46.19.210.19
     - 2a01:ad00:2:1::19
   * - Amsterdam
     - ams.eu.out.didww.com
     - 185.238.173.44
     - 2a01:ad00:8:1::44
   * - Singapore
     - sg.out.didww.com
     - 46.19.214.54
     - 2a01:ad00:6:2::54
   * - Hong Kong
     - hk.out.didww.com
     - 46.19.215.44
     - 2a01:ad00:7:1::44

Supported network and transport protocols
-------------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Transport protocol
     - Port
   * - UDP
     - ``5060``
   * - TCP
     - ``5060``
   * - TLS
     - ``5061``

TLS encrypts SIP signaling, as described in `Supported encryption`_.

Both IPv4 and IPv6 network protocols are supported for SIP signaling and media communication.

.. _services_voice_out_auth_realm:

Digest authentication realm
---------------------------

DIDWW uses a fixed realm value for Digest authentication:

.. code-block:: text

   out.didww.com

This value applies to all signaling endpoints.

.. note::
   This setting applies only to Digest authentication. Ensure your SIP
   equipment uses ``out.didww.com`` when responding to authentication
   challenges.

.. _voice-out-dns-srv:

DNS SRV
-------

`DNS SRV <https://www.rfc-editor.org/rfc/rfc2782>`_ is a failover
mechanism that reroutes calls to a backup data center if the primary one
becomes unreachable. We recommend enabling DNS SRV if your equipment
supports it, since it improves redundancy for call routing without
requiring manual failover.

The following table lists the target hostname for each DNS SRV record,
its priority, weight, resolved addresses, and role.

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 20 20 15 10

   * - DNS SRV record
     - Priority
     - Weight
     - LB IPv4 address
     - LB IPv6 address
     - LB location
     - Role
   * - nyc.us.out.didww.com
     - 10
     - 10
     - 46.19.209.44
     - 2a01:ad00:1:1::44
     - New York
     - Primary
   * -
     - 20
     - 10
     - 46.19.213.54
     - 2a01:ad00:5:2::54
     - Miami
     - Backup
   * - lac.us.out.didww.com
     - 10
     - 10
     - 46.19.212.54
     - 2a01:ad00:4:2::54
     - Los Angeles
     - Primary
   * -
     - 20
     - 10
     - 46.19.213.54
     - 2a01:ad00:5:2::54
     - Miami
     - Backup
   * - mia.us.out.didww.com
     - 10
     - 10
     - 46.19.213.54
     - 2a01:ad00:5:2::54
     - Miami
     - Primary
   * -
     - 20
     - 10
     - 46.19.209.44
     - 2a01:ad00:1:1::44
     - New York
     - Backup
   * - fra.eu.out.didww.com
     - 10
     - 10
     - 46.19.210.19
     - 2a01:ad00:2:1::19
     - Frankfurt
     - Primary
   * -
     - 20
     - 10
     - 185.238.173.44
     - 2a01:ad00:8:1::44
     - Amsterdam
     - Backup
   * - ams.eu.out.didww.com
     - 10
     - 10
     - 185.238.173.44
     - 2a01:ad00:8:1::44
     - Amsterdam
     - Primary
   * -
     - 20
     - 10
     - 46.19.210.19
     - 2a01:ad00:2:1::19
     - Frankfurt
     - Backup
   * - sg.out.didww.com
     - 10
     - 10
     - 46.19.214.54
     - 2a01:ad00:6:2::54
     - Singapore
     - Primary
   * -
     - 20
     - 10
     - 46.19.215.44
     - 2a01:ad00:7:1::44
     - Hong Kong
     - Backup
   * - hk.out.didww.com
     - 10
     - 10
     - 46.19.215.44
     - 2a01:ad00:7:1::44
     - Hong Kong
     - Primary
   * -
     - 20
     - 10
     - 46.19.214.54
     - 2a01:ad00:6:2::54
     - Singapore
     - Backup

.. _voice-out-bgp-anycast:

BGP Anycast
-----------

DIDWW provides a `BGP Anycast <https://www.rfc-editor.org/rfc/rfc4786>`_
signaling endpoint at ``any.out.didww.com`` (``185.238.172.4``). The
anycast prefix ``185.238.172.0/24`` is announced from all DIDWW
:ref:`Points of Presence <presence>`, and BGP automatically routes each
request to the nearest announcing PoP based on your network's routing
path.

.. note::
   - The BGP-selected path is not guaranteed to provide the best latency or call quality. Test the anycast endpoint in your environment before using it in production.
   - UDP is the recommended transport for ``any.out.didww.com``.

.. _voice-out-network-redundancy:

Network redundancy
-------------------

DIDWW operates multiple Points of Presence, and each PoP is interconnected
with more than one termination carrier. If a PoP or a carrier interconnect
becomes unreachable, outbound traffic is diverted to a healthy PoP or
carrier without requiring changes on your side:

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "primaryColor": "#e0f2fe",
       "primaryBorderColor": "#38bdf8",
       "primaryTextColor": "#1f2d3d",
       "secondaryColor": "#ccfbf1",
       "secondaryBorderColor": "#2dd4bf",
       "secondaryTextColor": "#1f2d3d",
       "tertiaryColor": "#fef3c7",
       "tertiaryBorderColor": "#facc15",
       "tertiaryTextColor": "#1f2d3d",
       "lineColor": "#0066cc",
       "textColor": "#1f2d3d",
       "nodeTextColor": "#1f2d3d",
       "titleColor": "#1f2d3d",
       "clusterBkg": "#f8fafc",
       "clusterBorder": "#cbd5e1",
       "edgeLabelBackground": "#ffffff"
     }
   }}%%

   flowchart LR
       subgraph endpoints["Your equipment"]
           E1["Endpoint A"]
           E2["Endpoint B"]
       end
       subgraph pops["DIDWW PoPs"]
           FRA["Frankfurt"]
           SG["Singapore"]
           LAX["Los Angeles"]
       end
       subgraph carriers["Termination carriers"]
           C1["Carrier A"]
           C2["Carrier B"]
       end
       E1 ==>|"Primary"| FRA
       E1 -.->|"Failover"| SG
       E1 -.->|"Failover"| LAX
       E2 ==>|"Primary"| SG
       E2 -.->|"Failover"| FRA
       E2 -.->|"Failover"| LAX
       FRA --> C1
       FRA --> C2
       SG --> C1
       SG --> C2
       LAX --> C1
       LAX --> C2

       classDef endpoint fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
       classDef popNode fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px
       classDef carrier fill:#fef3c7,stroke:#facc15,color:#1f2d3d,stroke-width:1.5px

       class E1,E2 endpoint
       class FRA,SG,LAX popNode
       class C1,C2 carrier

       style endpoints fill:#f8fafc,stroke:#cbd5e1,color:#1f2d3d
       style pops fill:#f8fafc,stroke:#cbd5e1,color:#1f2d3d
       style carriers fill:#f8fafc,stroke:#cbd5e1,color:#1f2d3d

       linkStyle default stroke:#0066cc

Within a PoP, calls first reach a redundant pair of load balancers, which
distribute traffic across multiple Session Border Controller (SBC) nodes. A
failed load balancer or SBC node is removed from rotation while the
remaining nodes continue to handle calls:

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "fontSize": "14px",
       "primaryColor": "#e0f2fe",
       "primaryBorderColor": "#38bdf8",
       "primaryTextColor": "#1f2d3d",
       "secondaryColor": "#ccfbf1",
       "secondaryBorderColor": "#2dd4bf",
       "secondaryTextColor": "#1f2d3d",
       "tertiaryColor": "#fef3c7",
       "tertiaryBorderColor": "#facc15",
       "tertiaryTextColor": "#1f2d3d",
       "lineColor": "#0066cc",
       "textColor": "#1f2d3d",
       "nodeTextColor": "#1f2d3d",
       "titleColor": "#1f2d3d",
       "clusterBkg": "#f8fafc",
       "clusterBorder": "#cbd5e1",
       "edgeLabelBackground": "#ffffff"
     }
   }}%%

   flowchart LR
       EP["Your endpoint"]
       subgraph pop["DIDWW PoP"]
           LB1["Load balancer 1"]
           LB2["Load balancer 2"]
           SBC1["SBC node 1"]
           SBC2["SBC node 2"]
           SBC3["SBC node 3"]
           LB1 --> SBC1
           LB1 --> SBC2
           LB1 --> SBC3
           LB2 --> SBC1
           LB2 --> SBC2
           LB2 --> SBC3
       end
       PSTN["PSTN"]
       EP --> LB1
       EP --> LB2
       SBC1 --> PSTN
       SBC2 --> PSTN
       SBC3 --> PSTN

       classDef endpoint fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
       classDef balancer fill:#fef3c7,stroke:#facc15,color:#1f2d3d,stroke-width:1.5px
       classDef sbc fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px
       classDef result fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px

       class EP endpoint
       class LB1,LB2 balancer
       class SBC1,SBC2,SBC3 sbc
       class PSTN result

       style pop fill:#f8fafc,stroke:#cbd5e1,color:#1f2d3d

       linkStyle default stroke:#0066cc,stroke-width:1.5px

To take advantage of this redundancy, enable :ref:`DNS SRV
<voice-out-dns-srv>` or use the :ref:`BGP Anycast <voice-out-bgp-anycast>`
endpoint, and allow all signaling and RTP addresses listed under
`Signaling endpoints`_ on your firewall or SBC.

.. _voice_out_rtp_information:

RTP and RTCP information
--------------------------

IP subnets for RTP traffic:

   - ``46.19.208.0/21``
   - ``185.238.172.0/22``

RTP and RTCP port range:

   - RTP port range: ``16383–32767``
   - RTCP (Real-time Transport Control Protocol) uses the RTP port + 1 for sending and receiving.

Supported codecs
----------------

The following audio codecs are supported:

- G.711 (A-law / µ-law)
- G.729
- G.723.1
- GSM
- telephone-event (DTMF)

.. _voice_out_sip_encryption:

Supported encryption
----------------------

DIDWW supports TLS for secure SIP signaling transport and `SRTP
<https://www.rfc-editor.org/rfc/rfc3711>`_ for media encryption.

Supported SRTP key negotiation mechanisms:

- `SDES <https://www.rfc-editor.org/rfc/rfc4568>`_
- `DTLS <https://www.rfc-editor.org/rfc/rfc5764>`_
- `ZRTP <https://www.rfc-editor.org/rfc/rfc6189>`_

Configure the required mechanism in the trunk's :ref:`Media encryption
mode <outbound_trunk_media_encryption_values>` setting.

.. note::
   Encryption applies only to the DIDWW ↔ Customer call leg. Encryption
   is not maintained end-to-end, and any other call legs outside this
   connection are not encrypted.

.. _service_termination_sip_details_p_charge_info:

P-Charge-Info header
--------------------

The ``P-Charge-Info`` header lets customers append additional technical
and billing-related information to Call Detail Records (CDRs). DIDWW's
implementation follows the `P-Charge-Info Internet-Draft
<https://datatracker.ietf.org/doc/html/draft-york-p-charge-info-08>`_,
which expired without becoming an RFC. It remains the only published
specification for this header.

- The ``P-Charge-Info`` value is stored in the CDR for future reference.
- This data can be used for billing purposes and integrated with the
  :ref:`CDR Streaming Tool <termination_call_events>`.
- The header value format is optional, allowing flexibility in
  implementation.

.. note::

   If your system cannot insert the standard ``P-Charge-Info`` SIP header but
   supports custom SIP headers, use the ``X-Charge-Info`` header instead.
   DIDWW will process the header value and include it in the call's CDR data.

SIP registration mechanism
--------------------------

SIP registration is supported for outbound trunks, but it is not required
for placing outbound calls. It is available for additional compatibility
with customer equipment.

Even when SIP registration is used, outbound
calls are routed according to the configured outbound trunk settings and
the signaling endpoint selected by the customer equipment.

The same :ref:`DIDWW Signaling Endpoints <voice-out-signaling-endpoints>`
act as SIP registrars.

.. note::
   A single outbound trunk can have a maximum of 10 active registrations.
   Additional registration attempts beyond this limit are rejected with
   ``500 Server Internal Error``.

SIP OPTIONS
-----------

SIP OPTIONS requests are supported for connectivity monitoring. They
provide a lightweight way to check availability and reachability without
placing a call. We recommend using SIP OPTIONS to monitor connectivity
with DIDWW.

The same :ref:`DIDWW Signaling Endpoints <voice-out-signaling-endpoints>`
respond automatically to incoming OPTIONS requests.

Related resources
-------------------

- :doc:`authentication-security` — Understand the authentication and
  security model.
- :doc:`outbound-trunk-reference` — Look up trunk list fields, statuses,
  and configuration settings.
- :doc:`how-to-guides/view-outbound-trunk-credentials` — Look up or
  regenerate trunk credentials.


========================
Outbound trunk reference
========================

Outbound trunk reference explains the fields, values, and states shown on
the Outbound Trunks page and in the trunk creation and edit forms.

.. _outbound_trunk_reference_main_fields:

Main fields
===========

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Field
     - Access
     - Description
   * - Name
     - Editable
     - The trunk's friendly name, shown in this list, matched by the
       search field, and set under :ref:`General trunk settings
       <outbound_trunk_create_general>`.
   * - Allowed SIP IPs
     - Editable, Credentials & IP-Based only
     - The trunk's allowed signaling SIP IP addresses, configured under
       :ref:`Authentication <outbound_trunk_create_authentication>`. Blank
       for authentication methods that do not use IP allowlisting, for
       example Twilio Account SID.
   * - 24 Hour Limit (USD)
     - Editable
     - Current spending against the configured maximum for the rolling
       24-hour period, shown as **spent/limit** (for example, ``$0/3000``)
       with a status indicator, configured under :ref:`Limits and
       notifications <outbound_trunk_limits_and_notification>`.
   * - :ref:`Status <outbound_trunk_status_values>`
     - Editable
     - Enables or disables outbound traffic through the trunk.
   * - :ref:`Encryption <outbound_trunk_media_encryption_values>`
     - Editable
     - The trunk's media encryption mode.
   * - Capacity Limit
     - Editable
     - Maximum number of simultaneous calls through the trunk, or
       **Unlimited** when no limit is set, configured under :ref:`Limits
       and notifications <outbound_trunk_limits_and_notification>`.
   * - :ref:`Authentication <outbound_trunk_auth_method_values>`
     - Editable
     - The authentication method configured for the trunk.
   * - :ref:`Credentials <outbound_trunk_credentials_fields>`
     - Read-only, Credentials & IP-Based only
     - Opens the trunk's Credentials pop-up window.

.. _outbound_trunk_credentials_fields:

Credentials window fields
-------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Field
     - Description
   * - Auth type
     - The authentication method used for the trunk, listed in
       :ref:`Authentication method values
       <outbound_trunk_auth_method_values>`.
   * - Username
     - The auto-generated SIP digest username. Read-only. It cannot be
       edited.
   * - Password
     - The generated SIP digest password. Can be revealed or regenerated
       from the window. Regenerating immediately invalidates the previous
       password, as described in :ref:`Credential lifecycle
       <outbound_trunk_credential_lifecycle>`.
   * - Host(s)
     - The regional DIDWW :ref:`signaling endpoints
       <voice-out-signaling-endpoints>` available to the trunk, or the
       :ref:`BGP Anycast <voice-out-bgp-anycast>` and :ref:`DNS SRV
       <voice-out-dns-srv>` connection options described in
       :doc:`outbound-sip-information`.
   * - Allowed SIP IPs
     - The trunk's configured :ref:`Allowed SIP IP addresses
       <outbound_trunk_create_authentication>`.
   * - Allowed Voice OUT CLI(s)
     - The trunk's configured :ref:`Allowed CLI(s) <outbound_trunk_cli_settings>`
       for ordinary outbound calls.
   * - Emergency calling CLI(s)
     - The trunk's configured :ref:`Emergency calling CLI(s)
       <outbound_trunk_create_emergency>`.

.. _outbound_trunk_status_values:

Status values
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Value
     - Description
   * - Enabled
     - The trunk accepts outbound calls that pass its authentication,
       Caller ID, destination, capacity, and spending controls.
   * - Disabled
     - The trunk blocks new outbound calls. A trunk is also disabled
       automatically when its rolling 24-hour limit is reached. Active
       calls are disconnected shortly afterward. Re-enable the trunk
       manually after reviewing its usage.

Trunk settings
==============

The following sections define the fields available when creating or
editing an outbound trunk, grouped to match the Create Outbound Trunk and
Edit Outbound Trunk forms.

.. _outbound_trunk_create_general:

General
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Field
     - Access
     - Description
   * - Friendly name
     - Editable
     - Name used to identify the trunk in the DIDWW User Panel and in the
       Outbound Trunks list.

Authentication
--------------

Authentication controls which systems can send calls through the trunk, with
the security model and recommendations covered in
:doc:`authentication-security`. If your account has multiple trunks,
:ref:`Authentication priority <outbound_trunk_authentication_priority>`
explains how DIDWW matches a request to a trunk.

.. _outbound_trunk_create_authentication:

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Field
     - Access
     - Description
   * - :ref:`Authentication method <outbound_trunk_auth_method_values>`
     - Editable
     - The method DIDWW uses to authenticate outbound calls sent through the
       trunk. Determines which of the fields below apply: Tech Prefix and
       the Allowed IP address fields apply only to Credentials & IP-Based,
       and Account SID applies only to Twilio Account SID.
   * - Tech Prefix
     - Editable, Credentials & IP-Based only
     - Optional code added **before** the dialed number to help identify and route calls through your trunk.

       .. admonition:: Specification
          :class: note

          - Maximum length: 8 characters.
          - Allowed symbols: digits (0–9) and the **#** symbol only.
          - The **DST** field in the :ref:`Call Logs <outbound_cdr_logs>` shows the full dialed destination, including the tech prefix.

       .. admonition:: Example
          :class: tip

          If you set the tech prefix to **123#**, it must be added before the dialed number.
          For example:

           - Dialed number: ``123#442079460000``
           - Shown in CDR: ``123#442079460000``
           - Routed destination: ``442079460000``

          Emergency calls must also include the prefix, e.g. ``123#112``.
   * - Allowed SIP IP addresses
     - Editable, Credentials & IP-Based only
     - Public IP addresses or subnets from which SIP requests are accepted.
       At least one SIP address is required.

       .. note::
          - The maximum number of allowed SIP IPs and subnets is **60**.
          - By default, a trunk cannot be created without adding at least one Allowed SIP IP address. To allow any IP address (not recommended for security reasons), you can add ``0.0.0.0/0``.

   * - Allowed RTP IP addresses
     - Editable, Credentials & IP-Based only
     - Your RTP addresses from which audio packets will be relayed to DIDWW.

       .. note::
          - The maximum number of allowed RTP IPs and subnets is **60**.

   * - Account SID
     - Editable, Twilio Account SID only
     - 34-character identifier of the Twilio account, in the format ``AC``
       followed by 32 hexadecimal characters. Found in the Twilio Console.
       Used with the :doc:`../../integrations/twilio/index` integration.
   * - :ref:`Credentials <outbound_trunk_credentials_fields>`
     - Read-only, Credentials & IP-Based only
     - Authentication and connection details generated for the trunk.
       :doc:`how-to-guides/view-outbound-trunk-credentials`.

.. _outbound_trunk_auth_method_values:

Authentication method values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Value
     - Description
   * - Credentials & IP-Based
     - The default method. DIDWW validates SIP digest credentials and the
       source IP address.
   * - IP-Only
     - Validates only the source IP address, without digest authentication.
       Not available for self-service selection. Contact `DIDWW Technical
       Support <mailto:support@didww.com>`_ to request it, as described in
       :doc:`authentication-security`.
   * - Twilio Account SID
     - Authenticates the trunk using a Twilio Account SID, for the
       :doc:`../../integrations/twilio/index` integration.
   * - phone.systems™
     - Authenticates the trunk for calls originated from a phone.systems™
       Cloud PBX instance. This is a system trunk: DIDWW creates it
       automatically when you purchase a :ref:`phone.systems™
       <service_phone_systems2>` plan, and it is not created manually from
       the Outbound Trunks page.

Media
-----

.. _outbound_trunk_create_media:

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Field
     - Access
     - Description
   * - Force Symmetric RTP
     - Editable
     - Sends RTP to the source IP address and port of the audio DIDWW
       actually receives, instead of the address negotiated in the SDP
       offer/answer (also known as COMEDIA mode). Helps when your equipment
       is behind NAT and its advertised media address is not directly
       reachable.
   * - RTP Ping
     - Editable
     - Sends an empty RTP packet after the call is established to trigger RTP
       transmission from the remote endpoint.
   * - RTP Timeout
     - Editable
     - Disconnects a call when no RTP packets arrive for the configured
       time, in seconds. Must be between 30 and 600 seconds.
   * - :ref:`Media encryption mode <outbound_trunk_media_encryption_values>`
     - Editable
     - Controls whether and how RTP media is encrypted.

.. _outbound_trunk_media_encryption_values:

Media encryption mode values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Value
     - Description
   * - Disabled
     - Does not encrypt media.
   * - SRTP SDES
     - Uses Secure RTP with SDP Security Descriptions key negotiation. The
       encryption key travels inside the SDP body, so it is only as
       protected as the signaling transport.
   * - SRTP DTLS
     - Uses Secure RTP with Datagram Transport Layer Security key
       negotiation, negotiated directly over the media path rather than in
       SDP.
   * - ZRTP
     - Uses Secure RTP with ZRTP key negotiation, agreed directly between
       endpoints without relying on the signaling transport for key
       protection.

Termination
-----------

.. _outbound_trunk_create_termination:

.. _outbound_trunk_limits_and_notification:

Limits and notifications
^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Field
     - Access
     - Description
   * - 24 hour limit (USD)
     - Editable
     - Maximum charge allowed for the trunk during a rolling 24-hour period.
       When reached, the trunk is disabled, new calls are blocked, and
       active calls are disconnected shortly afterward. The final charge
       can slightly exceed the limit.

       .. note::
          The default 24-hour limit is $3000. The minimum limit is $50, and the maximum limit is $10000.

   * - Capacity limit
     - Editable
     - Specifies the maximum number of simultaneous calls allowed per
       trunk. Leave empty for unlimited capacity, shown as **Unlimited**
       in the trunk list.
   * - Voice OUT Trunk usage limit notification
     - Editable
     - Sends an email when usage reaches 80% of the 24-hour limit. A
       notification is sent no more than once every 12 hours.

.. _outbound_trunk_cli_settings:

CLI Settings
^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Setting**
     - **Description**

   * - On CLI Mismatch
     - A CLI mismatch happens when numbers from other providers are used as the CLI, or when the CLI does not match any numbers acquired via DIDWW.

       - **Send Original CLI** – Passes the "From" header value from your system downstream without modification.
       - **Reject Call** – Rejects the call if the "From" header value does not match any DID numbers allowed in the **CLI Settings** list.

   * - Allow any DID(s) as CLI for Voice OUT
     - When this toggle is **enabled**, all supported numbers are automatically allowed as CLI by default.

   * - Allow specific DIDs as CLI for Voice OUT
     - When this toggle is **disabled**, only numbers added to the Allowed CLI(s) list can be used as CLI. Numbers are
       added from Available CLI(s), which can be filtered by CLI,
       Description, Country, and Region. Lists DIDWW numbers that support
       outbound trunk calls with :ref:`local routes
       <outbound_dialing_local_routes>`. DIDs that support only global
       outbound routes are not listed.

.. note::
   The **Available CLI(s)** list displays only DID numbers that support the Voice OUT feature with :ref:`local termination <outbound_dialing>`. DIDs with the Voice OUT global routes feature are not included in this list.

.. _dialing_settings:
.. _outbound_trunk_dialing_mode_values:

Destination Dialing Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Setting**
     - **Description**

   * - Allow All
     - This method **allows** calls to all destinations, **except** those specified in the listed prefixes.

       .. admonition:: Example

          The configuration below allows calls to all destinations except:

           - London, UK (4420)
           - Ireland (353)
           - New York, US (1212)

   * - Reject All
     - This method **rejects** calls to all destinations, **except** those specified in the listed prefixes.

       .. admonition:: Example

          The configuration below rejects calls to all destinations except:

           - Bogota, Colombia (571)
           - Lancaster, US (1740)
           - Mobile, Denmark (4592)

Use the shortest prefix that precisely describes the required destination
range. Number formatting is covered in
:doc:`routing-dialing/outbound-dialing`.

Emergency Calling
------------------

.. _outbound_trunk_create_emergency:

Emergency calling requires a DID that supports emergency service and has an
active emergency calling service.

The complete trunk-side setup is covered in
:doc:`../emergency-calling/configure-emergency-calling-for-outbound-trunks`.

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Field
     - Access
     - Description
   * - Allow all available DID(s) for emergency calling
     - Editable
     - When this toggle is enabled, all eligible numbers are automatically
       allowed as Caller ID for emergency calls by default.
   * - Emergency calling CLI(s)
     - Editable
     - When the toggle above is disabled, only numbers added to the
       Emergency calling CLI(s) list can be used as Caller ID for
       emergency calls. Numbers are added from Available CLI(s), which can
       be filtered by CLI, Description, Country, and Region. Lists DIDWW
       numbers that are registered for emergency calling. DIDs that are
       not registered for emergency are not listed.

.. note::
   The **Available CLI(s)** list displays only DID numbers that are
   registered for emergency calling. DIDs that are not registered for
   emergency are not included in this list.

Related resources
=================

- :doc:`how-to-guides/index` — Create and manage outbound trunks.
- :doc:`authentication-security` — Understand authentication, encryption,
  and security controls.

=======================================
Robocall mitigation and call labeling
=======================================

These pages cover call labeling and regulatory registration. Carriers and
call-analytics providers may label or block calls based on call reputation.
Separately, the US Federal Communications Commission's Robocall Mitigation
Database registration requirements may apply to providers based on their role
in the call path.

.. grid:: 1 2 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`report` **Spam/Scam Likely due to robocalls**
      :link: spam-scam-likely
      :link-type: doc

      Understand why legitimate calls may be labeled or blocked and what to do
      if this happens.

   .. grid-item-card:: :octicon:`law` **Robocall Mitigation Database**
      :link: robocall-mitigation-database
      :link-type: doc

      Understand FCC registration requirements and why DIDWW may request an
      RMD filing.

.. toctree::
   :hidden:

   spam-scam-likely
   robocall-mitigation-database


.. _spam_scam_likely:

===================================
Spam/Scam Likely due to robocalls
===================================

Carriers and call-analytics providers may label suspicious calls or block them
due to the high volume of robocalls. In the US, common labels include **Scam
Likely**, **Fraud Risk**, **Spam Risk**, and **Potential Spam**.

Why calls receive labels
------------------------

Labels are generally assigned by the terminating carrier or its call-analytics
provider, not by DIDWW. Providers use different review processes, so the same
number may be labeled on one network but not another. Legitimate business
calls can also be mislabeled.

Labeling displays a warning but may still allow the call to connect. Blocking
prevents the call from reaching the called party. Both are separate from CNAM
caller-name display.

What to do if your number is mislabeled or blocked
--------------------------------------------------

If your calls are incorrectly labeled or blocked, consider taking the following
steps. These services primarily address calls to US networks.

- `TNS Call Guardian <https://reportarobocall.com/trf/>`_ — report a
  mislabeled or blocked call.
- `First Orion Free Number Registration
  <https://firstorion.com/products/free-number-registration>`_ — register
  your business name and outbound numbers.
- `Free Caller Registry <https://freecallerregistry.com/fcr/>`_ — register
  numbers used by your business with First Orion, Hiya, and TNS.
- `Call Labeling and Blocking Points of Contact
  <https://ustelecom.org/the-industry-traceback-group-itg/call-labeling-and-blocking-points-of-contact/>`_
  — find carrier and analytics-provider redress contacts.
- `T-Mobile Call Reporting <https://callreporting.t-mobile.com/>`_ — report
  calls incorrectly identified or blocked on the T-Mobile network.

These steps can help correct mislabeling and improve call delivery, but they do
not guarantee that a label will be removed.


============================
Robocall Mitigation Database
============================

The Federal Communications Commission (FCC) maintains the Robocall Mitigation
Database (RMD). Voice service providers and intermediate providers use it to
certify their STIR/SHAKEN implementation and robocall mitigation practices,
supporting efforts to prevent illegal and spoofed robocalls.

Why DIDWW may request registration
----------------------------------

If DIDWW has requested that you register with the FCC, it is because we have
determined that your use case likely aligns with that of a voice service
provider. This usually indicates that you are reselling DIDWW voice services
for use by a separate end user making outbound calls to US destinations,
rather than using the services directly for your own business.

By *reselling*, we mean that your business is not using DIDWW voice services
directly, but is providing them to another party for use.

In these cases, DIDWW acts as a downstream provider. US rules may prohibit a
downstream provider from accepting traffic directly from a provider that is
required to file but is not listed in the RMD, or whose filing has been
removed. An RMD listing alone does not guarantee that DIDWW will approve the
service or accept the traffic.

Contact `DIDWW Customer Support <mailto:support@didww.com>`_ if you need
clarification about a registration request.

Who may need to register
------------------------

FCC rules require voice service providers and intermediate providers,
including gateway providers, to file in the RMD. This can include VoIP
resellers and foreign providers that send calls with US North American
Numbering Plan numbers in the Caller ID field to US providers.

A business does not become a voice service provider merely because it uses an
outbound trunk for its own calls. Whether registration is required depends on
the service it provides and its role in the call path.

What is the FCC?
----------------

The Federal Communications Commission is an independent US government agency
responsible for regulating interstate and international communications across
various media, including radio, television, wire, satellite, and cable. It
operates in all 50 states, the District of Columbia, and US territories. As the
primary authority for communications law, regulation, and technological
innovation in the United States, the FCC is overseen by Congress.

FCC and TCPA compliance for outbound calls
------------------------------------------

Customers that send telemarketing or other automated voice traffic to the
United States are responsible for complying with the Telephone Consumer
Protection Act (TCPA), FCC rules, and other applicable federal and state
requirements. Noncompliance may result in substantial statutory damages,
regulatory penalties, and other enforcement action.

Before placing telemarketing calls:

- Verify called numbers against the `National Do Not Call Registry
  <https://telemarketing.donotcall.gov/>`_ as required for your traffic.
- Maintain and honor an internal company-specific Do Not Call (DNC) list.
- Obtain and retain the consent required for the call type and promptly honor
  revocation requests.

Consumers can submit unwanted-call complaints through the `FCC Consumer
Inquiries and Complaints Center
<https://consumercomplaints.fcc.gov/hc/en-us/articles/115002234203-Unwanted-Calls-Texts-Phone>`_.
Such complaints may contribute to enforcement action and negatively affect the
reputation of the calling number.

Reassigned Numbers Database
---------------------------

A telephone number may be reassigned after the previous subscriber disconnects
it. Consent obtained from the previous subscriber does not apply to the
number's new subscriber.

Use the `Reassigned Numbers Database (RND) <https://www.reassigned.us/>`_ to
determine whether a number has been permanently disconnected and reassigned
since the date on which consent was obtained or the customer was last known to
use that number. Query the RND before placing automated calls that rely on
previously obtained consent, including appointment reminders, account
notifications, and similar traffic. This helps avoid contacting a new
subscriber who has not opted in.

.. important::

   RND screening supplements, but does not replace, consent records, DNC
   screening, or other compliance controls. Customers are responsible for
   determining which requirements apply to their traffic.

Register with the FCC
---------------------

Obtain an FCC Registration Number (FRN) through CORES, then submit and maintain
your filing through the RMD portal. Use the FCC's current resources:

- `Commission Registration System (CORES)
  <https://www.fcc.gov/licensing-databases/commission-registration-system-fcc>`_
  for obtaining and managing an FRN.
- `CORES tutorial videos
  <https://www.fcc.gov/licensing-databases/fcc-registration-system-cores/commission-registration-system-video-tutorials>`_.
- `Robocall Mitigation Database portal
  <https://fccprod.servicenowservices.com/rmd?id=rmd_welcome>`_.
- `RMD filing instructions
  <https://www.fcc.gov/sites/default/files/rmd-instructions.pdf>`_.
- `Frequently Asked Questions for RMD filers
  <https://docs.fcc.gov/public/attachments/DA-26-72A1.pdf>`_.

If you need help navigating the registration process, consultants and outside
counsel can assist. If you find inaccurate information in the database or need
help with the registration process, contact the FCC at
`RobocallMitigationDatabase@fcc.gov
<mailto:RobocallMitigationDatabase@fcc.gov>`_.

RMD registration is separate from :doc:`STIR/SHAKEN attestation
<../stir-shaken-outbound>` and does not remove a :doc:`Spam/Scam Likely label
<spam-scam-likely>`.

This page provides general information, not legal advice. Consult qualified
counsel if you are unsure whether the filing requirements apply to your
business.


.. _messaging_service:

===
SMS
===

SMS provides the trunks and sender verification tools required to receive messages and send Person-to-Person (P2P) or Application-to-Person (A2P) traffic.

----

.. grid:: 1 1 1 4
    :gutter: 4
    :padding: 0

    .. grid-item-card:: :octicon:`mail` **SMS Trunks**
        :link: sms-trunks/index
        :link-type: doc
        :text-align: left

        Set up and manage SMS trunks for sending and receiving messages.

    .. grid-item-card:: :octicon:`megaphone` **Sender ID Verifications**
        :link: sender-id-verifications/index
        :link-type: doc
        :text-align: left

        Register sender IDs, provide business and messaging information, and track verification review.


.. _a2p_campaign_content_requirements:
.. _sender_id_verification_compliance_requirements:

.. |br| raw:: html

    <br>

===============================
A2P SMS compliance requirements
===============================

A2P SMS Compliance content requirements explain the message content, consent practices, and sending behavior required for A2P SMS using a Sender ID Verification.

This information helps users prepare compliant Sender ID Verification submissions and understand why a Sender ID Verification may be rejected, suspended, or returned for changes during verification.

Approval depends on the accuracy of the submitted business and messaging information, the Sender ID, the consent flow, the sample content, and the way messages are sent.

Messages must comply with applicable laws, regulations, and messaging industry requirements in the destination country.

----

.. raw:: html

   <br>

.. _a2p_campaign_requirements:

Sender ID Verification requirements
-----------------------------------

DIDWW Sender ID Verifications must clearly identify the sender, use accurate messaging information, and follow valid consent and opt-out practices.

The submitted description, sample messages, opt-in flow, and actual message traffic must describe the same use case.

Use a recognizable domain
~~~~~~~~~~~~~~~~~~~~~~~~~

If an A2P message includes a link, the link should use a recognizable domain associated with the business or service identified in the verification.

Avoid generic, unrelated, suspicious, or frequently changing domains. A consistent business domain helps users recognize the sender and understand where the link will take them.

Use clear and natural language
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Messages should be written in clear, natural language.

Avoid unusual spellings, excessive symbols, misleading formatting, or wording that may make messages look like spam.

Messages should not use intentionally distorted words, random characters, or obfuscated text to bypass filtering or hide the real meaning of the message.

Collect direct consent
~~~~~~~~~~~~~~~~~~~~~~

User consent must be collected directly for the specific messaging campaign described in the verification.

Do not use consent obtained from another company, another messaging campaign, purchased lists, rented lists, shared databases, or third-party lead sources.

Consent must apply only to the specific brand, messaging campaign, and message purpose disclosed to the user during opt-in.

Set message frequency expectations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Users should be informed about the expected message frequency before or during opt-in, especially for recurring campaigns.

Example:

.. code-block:: text

   You may receive up to 5 messages per month.

Identify the business
~~~~~~~~~~~~~~~~~~~~~

Messages should clearly identify the business, brand, or service that is contacting the user.

Users should not have to guess who sent the message or why they received it.

Example:

.. code-block:: text

   Example Brand: Your appointment is confirmed for 10:00 AM. Reply STOP to unsubscribe. Reply HELP for further assistance.

Include STOP and HELP instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A2P messages should include clear opt-out and help instructions where applicable.

For recurring messaging campaigns, opt-out instructions should be provided during opt-in and repeated regularly in messages.

.. note::
   If an **Alphanumeric Sender ID** is used, recipients cannot reply directly to the message.
   In this case, the message should include an opt-out link or another clear opt-out method.

Examples:

.. code-block:: text

   Reply STOP to unsubscribe.

.. code-block:: text

   Reply HELP for help.

Keep verification information accurate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Verification information must accurately reflect the live use case.

The messaging description, sample messages, Sender ID, opt-in method, links, and actual message content must remain consistent.

A Sender ID Verification may require changes or resubmission if the submitted
information does not match the real message traffic. Associated traffic may
also be restricted.

.. note::
   DIDWW may request updates, clarification, or resubmission if the verification details do not match the actual message content or sending behavior.

----

.. raw:: html

   <br>

.. _a2p_prohibited_messaging_practices:

Prohibited messaging practices
------------------------------

The following sending practices are not allowed for A2P traffic registered through DIDWW Sender ID Verifications.

Shared, sold, or rented consent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

User consent must not be bought, sold, rented, shared, or transferred.

Consent must be collected directly for the specific campaign and must not be reused across unrelated brands, services, or campaigns.

Grey routes
~~~~~~~~~~~

A2P messages must not be sent through unauthorized or unsupported routes.

A grey route is a sending path, method, or setup that is not authorized for A2P or non-consumer messaging.

Snowshoe sending
~~~~~~~~~~~~~~~~

Snowshoe sending is not allowed.

Snowshoe sending means spreading similar or identical message traffic across multiple sender IDs, phone numbers, or routes to dilute reputation metrics, bypass filtering, or avoid spam controls.

Filter evasion
~~~~~~~~~~~~~~

Messaging campaigns must not use techniques designed to avoid spam controls, filtering systems, or compliance checks.

This includes automatically replacing blocked sender IDs, numbers, domains, or routes with new ones for the purpose of continuing the same non-compliant traffic.

Dynamic routing to avoid filtering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Message routing must not be changed dynamically for the purpose of bypassing blocking, filtering, or other compliance controls.

Routing changes should not be used to hide the source, avoid detection, or continue traffic that has already been identified as suspicious or non-compliant.

Shared sender IDs or numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Shared sender IDs or numbers must not be used in a way that allows multiple unrelated brands, services, or content providers to send different content from the same sender.

Each Sender ID Verification must clearly identify the business responsible for the messages.

URL cycling and public URL shorteners
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Messaging campaigns must not rotate multiple domains, shortened links, or URLs to evade filtering or dilute reputation tracking.

Public URL shorteners should not be used in A2P messages.

Where links are required, use a recognizable domain that belongs to or clearly represents the business or service identified in the verification.

URL redirects and forwarding
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Messages must not contain links that use multiple redirects or obscure the final destination.

Users should be able to understand where a link will take them.

Links that redirect through several domains or hide the final landing page may
prevent approval, cause messages to be filtered, or result in messaging
restrictions.

Number cycling
~~~~~~~~~~~~~~

Number cycling is not allowed.

Number cycling means replacing sender IDs or numbers after deliverability decreases, complaints increase, or filtering begins, while continuing the same or similar campaign traffic.

Number cycling suggests poor consent practices, unwanted messaging, or an attempt to avoid filtering.

----

.. raw:: html

   <br>

.. _a2p_prohibited_campaign_content:

Prohibited message content
---------------------------

A2P messages must not contain unlawful, misleading, harmful, abusive, or inappropriate content.

The following content is not allowed:

* Spam or unsolicited messages.
* Fraudulent, deceptive, or misleading messages.
* Phishing messages.
* Scam messages.
* Content that promotes, depicts, or endorses violence.
* Inappropriate content.
* Profanity, hate speech, harassment, abusive language, or discriminatory content.
* Illegal drugs, illegal substances, or illegal prescriptions.
* Any content that is illegal in the destination country or otherwise violates applicable laws, regulations, or messaging requirements.

.. note::
   Sender ID Verifications may be returned for changes or closed if their
   traffic includes or promotes prohibited content. Associated traffic may
   also be blocked.

   DIDWW may also restrict new verification submissions, request corrective action, or limit provisioning if prohibited content is detected.

.. important::
   A2P message content must be appropriate for the intended audience and must comply with applicable laws and messaging requirements in the destination country.

----

.. raw:: html

   <br>

.. _a2p_disallowed_campaign_categories:

Disallowed messaging categories
-------------------------------

The following A2P messaging categories are not supported:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Category
     - Disallowed content
   * - High-risk financial services
     - Payday loans, non-direct lending, and debt collection.
   * - Debt forgiveness
     - Debt consolidation, debt reduction, and credit repair programs.
   * - Illegal substances
     - Cannabis, illegal prescriptions, and other illegal substances.
   * - Work and investment opportunities
     - Work-from-home programs, job alerts from third-party recruiting firms, and high-risk investment opportunities.
   * - Gambling
     - Gambling-related campaigns, betting-related campaigns, or other gambling content.
   * - Lead generation
     - Campaigns where collected user information is shared, sold, rented, or transferred to third parties.
   * - Other illegal or non-compliant content
     - Any campaign type that is prohibited by applicable law, regulation, or messaging industry requirements.

.. note::
   Verifications for these categories may not be approved even if similar content was previously approved or accepted by another provider.

----

.. raw:: html

   <br>

.. _a2p_phishing:

Phishing
--------

Phishing is not allowed.

Phishing means sending messages that appear to come from a reputable company, service, or organization in order to trick users into revealing personal information.

Examples of sensitive information include:

* Passwords.
* Account credentials.
* Payment card details.
* Banking information.
* Verification codes.
* Personal identification details.

A2P messages must not impersonate another company, service, government body, or individual.

----

.. raw:: html

   <br>

.. _a2p_fraud_or_scam:

Fraud or scam
-------------

Fraudulent or scam messages are not allowed.

This includes messages that use wrongful or criminal deception to obtain financial or personal gain.

Such messages often involve money, payments, account access, prizes, investments, or business transactions.

Examples of prohibited fraud or scam content include:

* Fake payment requests.
* Fake account alerts.
* Fake prize or reward claims.
* Messages requesting payment under false pretenses.
* Messages designed to trick users into sharing personal or financial information.

----

.. raw:: html

   <br>

.. _a2p_deceptive_marketing:

Deceptive marketing
-------------------

Marketing messages must be truthful, clear, and not misleading.

A2P messages must not use false claims, deceptive wording, hidden conditions, or misleading calls-to-action.

If a campaign includes promotional content, the user must have provided the required level of consent before receiving those messages.

The following practices are not allowed:

* Using false or misleading claims in promotional messages.
* Hiding important terms, fees, conditions, or opt-in details.
* Using deceptive language in calls-to-action, forms, landing pages, or message content.
* Promoting products or services with claims that cannot be verified or substantiated.
* Using a misleading or unclear Sender ID.
* Making the message purpose unclear.

----

.. raw:: html

   <br>

.. _a2p_compliance_audits_and_notices:

Compliance audits and notices
-----------------------------

Sender ID Verifications and their associated traffic may be reviewed for compliance with applicable messaging requirements.

Traffic that creates consumer harm, generates complaints, or appears to violate
messaging requirements may be restricted, blocked, or require corrective
action.

A verification may require review or corrective action if:

* The traffic appears to be unwanted or harmful.
* The campaign receives excessive complaints.
* The message content does not match the registered campaign use case.
* The campaign uses prohibited sending practices.
* The campaign falls under a prohibited or disallowed content category.
* The sender cannot provide valid consent records when required.
* The campaign continues sending messages to users who opted out.

Depending on the severity of the issue, corrective actions may include traffic
blocking, verification closure, a request for root cause analysis, verification
updates, or resubmission.

Repeated violations or severe compliance issues may result in long-term or
indefinite traffic restrictions or closure of the verification.

----

.. raw:: html

   <br>

.. _a2p_age_gating:

Age gating
----------

Messaging that includes age-restricted content must comply with applicable laws and must use a valid age verification process.

Age-restricted content may include, but is not limited to:

* Sexually explicit or adult content.
* Alcohol-related content.
* Firearms-related content.
* Tobacco-related content.
* Other content restricted by age under applicable laws or regulations.

A simple **Yes** or **No** confirmation is not considered a sufficient age gate.

Where age verification is required, the opt-in process should include date of birth verification or another appropriate age verification mechanism.

.. important::
   DIDWW may reject, close, or request changes to a Sender ID Verification, or
   restrict its traffic, if the submitted use case, message content, consent
   flow, or sending behavior does not meet applicable messaging requirements.

----

.. raw:: html

   <br>

.. _a2p_consent_and_opt_out_requirements:

Consent and opt-out requirements
--------------------------------

A2P messages may be sent only to users who have agreed to receive messages from the business for the messaging use case and purpose described in the Sender ID Verification.

Messages sent under the verification must meet the following requirements:

- Users must understand what types of messages they are agreeing to receive.
- Consent must apply only to the business, brand, messaging use case, and purpose explained during opt-in.
- Consent records should be retained and provided if requested during review.
- Users must be able to opt out at any time.
- Opt-out requests must be honored promptly.
- After a user opts out, no further messages may be sent except for a final
  confirmation message.

For Sender IDs that support replies, common opt-out keywords include:

* STOP
* END
* CANCEL
* UNSUBSCRIBE
* QUIT

Example opt-out confirmation:

.. code-block:: text

   You have been unsubscribed and will no longer receive messages from Example Brand.

----

.. raw:: html

   <br>

.. _a2p_campaign_rejection_reasons:

Reasons a verification may require changes
------------------------------------------

A Sender ID Verification may require changes or may not be approved if:

* The campaign content falls under a prohibited or disallowed category.
* The campaign description does not match the submitted sample messages.
* The Sender ID is unclear or inconsistent.
* The opt-in process is missing, unclear, or not specific to the campaign.
* The opt-out message is missing or incomplete.
* The campaign uses public URL shorteners, suspicious domains, or redirect chains.
* The campaign appears to use third-party lead lists or shared consent.
* The message samples contain misleading, deceptive, or non-compliant content.
* The campaign information is incomplete, inaccurate, or inconsistent with the intended use case.
* The campaign uses prohibited sending practices, such as snowshoe sending, number cycling, grey routes, or filter evasion.

----

.. raw:: html

   <br>

.. _a2p_recommended_user_guidance:

Recommended user guidance
-------------------------

Before submitting a Sender ID Verification, make sure that:

* The campaign use case is allowed.
* The business identity and sender information are accurate.
* The message content clearly identifies the sender.
* The opt-in method is clear and specific to the messaging campaign described in the verification.
* The messaging campaign does not rely on purchased, rented, shared, or third-party consent.
* Message samples include required opt-out wording where applicable.
* Any URLs use a recognizable business domain.
* The campaign description, sample messages, and consent flow all describe the same use case.
* The planned traffic does not include prohibited content or prohibited sending practices.

Related resources
-----------------

- :doc:`how-sender-id-verification-works` - Understand how Sender IDs, verification, and SMS trunks work together.
- :doc:`how-to-guides/create-us-10dlc-verification` - Complete business and messaging information for US A2P 10DLC registration.
- :doc:`how-to-guides/resubmit-sender-id-verification` - Correct and resubmit a verification.
- :doc:`sender-id-verification-reference` - Review fields, types, and status values.


.. _how_sender_id_verification_works:

================================
How Sender ID Verification works
================================

Sender IDs identify the sender of application-to-person (A2P) SMS messages.
Before A2P SMS can be sent through DIDWW using these Sender IDs, the
business and messaging traffic must be approved through a Sender ID
Verification.

What is a Sender ID?
=====================

A Sender ID is the name or phone number shown as the sender of an
application-to-person (A2P) SMS message. It helps recipients identify the
sender. If the Sender ID supports incoming SMS messages, recipients can also
reply.

DIDWW supports four Sender ID options:

- **Alphanumeric** displays a business or brand name instead of a phone number. It is not linked to a DID number and does not support replies.
- **Long-code** uses an eligible DID number assigned to the DIDWW account.
- **Toll-Free** uses an eligible US Toll-Free DID number assigned to the DIDWW account.
- **Carrier** uses a dynamic Sender ID assigned by the destination carrier. It is not linked to a DID number in the DIDWW account.

The Sender ID type determines what recipients see, whether replies are
possible, and which country requirements apply. For a detailed comparison, see
:doc:`sender-id-verification-types/index`.

Why do Sender IDs require verification?
=======================================

Regulations and downstream carriers can require businesses and Sender IDs to be
registered before A2P messages are delivered. Verification establishes who is
sending the messages, where the traffic will be sent, and whether the intended
messaging use is supported.

Depending on the Sender ID type and country, a verification can associate the
following information:

- The business identity and address.
- The Sender ID or eligible DID numbers.
- The countries where the Sender ID will be used.
- The messaging use case and campaign description.
- The recipient consent and opt-out process.
- Sample messages and supporting documents.

The submitted information must describe the same business and traffic that
will use the Sender ID. For messaging and consent requirements, see
:doc:`compliance-content-requirements`. For type-specific fields, see
:doc:`sender-id-verification-reference`.

How does Sender ID verification work?
=====================================

A Sender ID Verification contains the business and messaging details required
to approve a Sender ID for use in specific countries. For Carrier
verifications, approval applies to the messaging traffic rather than a specific
Sender ID because the destination carrier assigns the Sender ID dynamically.

The submitted information is reviewed by DIDWW. Once approved, the Sender IDs
covered by the verification can be used for the approved business, countries,
and messaging purpose. To send messages, associate the verification with an
:doc:`outbound SMS trunk <../sms-trunks/index>`.

The estimated review time is shown in the DIDWW User Panel before submission.
Actual approval time can vary depending on the Sender ID type, country
requirements, and whether additional information is requested.

Verification lifecycle
======================

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR
      classDef decision stroke:#fb923c,fill:#fef3c7,stroke-width:2px
      classDef action stroke:#22c55e,fill:#dcfce7,stroke-width:2px
      classDef outcome stroke:#ef4444,fill:#fee2e2,stroke-width:2px
      classDef input stroke:#38bdf8,fill:#e0f2fe,stroke-width:2px

      new["New"]:::input
      review["In Process"]:::decision
      active["Active"]:::action
      changes["Changes Required"]:::outcome
      closure["Pending Closure"]:::decision
      closed["Closed"]:::outcome

      new -->|Review started| review
      review -->|Approved| active
      review -->|Changes requested| changes
      changes -->|Review resumed| review
      active -->|Closure requested| closure
      closure -->|Closure completed| closed

A newly created verification has the **New** status. Its status changes to
**In Process** when the review starts and to **Active** after approval.

If the submitted information needs corrections or additions, the verification
moves to **Changes Required**. After you update and resubmit it, it returns to
**In Process** when the review resumes.

When you request closure of an active verification, its status changes to
**Pending Closure**. After the closure is completed, the status changes to
**Closed**.

When you request closure of an active verification, it moves to **Pending
Closure**. After the closure is completed, it becomes **Closed**.

For complete status definitions, see :ref:`sender_id_verification_statuses`.

Pricing and billing
===================

Verification pricing depends on the Sender ID type and destination country.
Charges can include:

- A **non-recurring charge (NRC)** for the one-time setup fee.
- A **monthly recurring charge (MRC)** for maintaining the verification.

The applicable NRC and initial MRC are charged after the verification is
approved and its status becomes **Active**. Subsequent MRCs are charged on the
renewal date shown in the verification details.

Before submission, the DIDWW User Panel shows the applicable setup fee,
recurring price, per-message pricing, and the amount due upon approval. Message
usage charges are separate from verification setup and recurring charges.

Always review the pricing shown in the DIDWW User Panel before submitting a
verification. For billing field descriptions, see
:ref:`sender_id_verification_fields`.

Managing Sender ID Verifications
================================

Verifications can be updated, resubmitted when changes are required, or closed
when their Sender IDs should no longer be used. For task instructions, see
:doc:`how-to-guides/index`.

Related resources
=================

- :doc:`Sender ID types <sender-id-verification-types/index>`
- :doc:`Compliance content requirements <compliance-content-requirements>`
- :doc:`Sender ID how-to guides <how-to-guides/index>`
- :doc:`Sender ID Verification reference <sender-id-verification-reference>`
- :doc:`SMS trunks <../sms-trunks/index>`


.. _cancel_sender_id_verification:

===============================
Cancel a Sender ID Verification
===============================

Cancel and close a Sender ID Verification when you no longer want to use it to send messages.

Before you begin
================

The verification must have the :ref:`Active <sender_id_verification_statuses>` status.

.. warning::

   After the verification becomes **Closed**, it can no longer be used to send
   messages. Confirm that you no longer need the verification before
   continuing.

Step 1: Open the closure dialog
===============================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Verifications** tab.
3. Find the verification and click the actions button.
4. Select **Cancel campaign**.

.. figure:: https://doc.didww.com/_images/cancel-verification-action.webp
   :figclass: align-center
   :alt: Cancel campaign action for a Sender ID Verification.
   :width: 100%

   **Fig. 1.** Open the Cancel campaign action.

Step 2: Confirm closure
=======================

1. Review the warning in the **Close Sender ID Verification** dialog.
2. Click **Confirm**.

.. figure:: https://doc.didww.com/_images/cancel-verification-confirmation.webp
   :figclass: align-center
   :alt: Close Sender ID Verification confirmation dialog.
   :width: 100%

   **Fig. 2.** Confirm the cancellation.

After confirmation, the verification moves to
:ref:`Pending Closure <sender_id_verification_statuses>`. When the closure is
complete, its status changes to
:ref:`Closed <sender_id_verification_statuses>`, and the verification can no
longer be used to send messages.

Related resources
=================

- :doc:`../how-sender-id-verification-works` - Understand the verification lifecycle.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.


.. _create_alphanumeric_sender_id_verification:

=============================================
Create an Alphanumeric Sender ID Verification
=============================================

Follow these steps to submit an Alphanumeric Sender ID for verification before using it to send A2P SMS messages.

Before you begin
================

- Review :doc:`Alphanumeric Sender IDs <../sender-id-verification-types/alphanumeric>` to confirm that this Sender ID type matches your messaging use case.
- Create a business identity and address in advance, or create them during **Step 2: Enter general details**. See :doc:`Manage identities and addresses <../../../identities/getting-started>`.
- Review :doc:`../compliance-content-requirements` before preparing sample messages or consent information.

Step 1: Open the verification form
==================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Get Started** tab.
3. Find the **Alphanumeric** Sender ID type and click **Create New**.

Alternatively, on the **Verifications** tab, open **Create New** and select the **Alphanumeric** Sender ID type.

.. figure:: https://doc.didww.com/_images/alphanumeric-create-new.webp
   :figclass: align-center
   :alt: Alphanumeric card with the Create New button.
   :width: 100%

   **Fig. 1.** Open the Alphanumeric verification form.

Step 2: Enter general details
=============================

1. Enter a **Friendly name**.
2. Select the **Target countries**.
3. Enter the **Sender ID**.
4. Review the **Pricing** and **Identity Requirements** shown for the selected countries.
5. Select an existing business **Identity** and **Address**, or create them during this step.
6. Click **Next**.

.. important::

   **Target countries** are organized into predefined groups. Selecting any
   country in a group selects the entire group, and a verification can target
   only one group. Countries in a selected group cannot be added or removed
   individually, and groups cannot be combined in the same verification.
   Pricing and Identity Requirements apply once to the whole group, not per
   country.

For field descriptions, see :ref:`Alphanumeric verification setup fields <alphanumeric_verification_reference>`.

.. figure:: https://doc.didww.com/_images/alphanumeric-general.webp
   :figclass: align-center
   :alt: General step for an Alphanumeric Sender ID Verification.
   :width: 100%

   **Fig. 2.** General.

Step 3: Enter verification details
==================================

1. Enter the **Legal Company Name** and **Website**.
2. Select the **Use case type**.
3. Enter the **Campaign description**.
4. In **How will consumers opt in?**, explain how recipients agree to receive the messages.
5. Enter two representative messages in **Sample content message #1** and **Sample content message #2**.
6. Click **Next**.

For field descriptions, see :ref:`Alphanumeric verification details fields <alphanumeric_verification_reference_business_information>`.

.. figure:: https://doc.didww.com/_images/alphanumeric-business-information.webp
   :figclass: align-center
   :alt: Verification details step for an Alphanumeric Sender ID Verification.
   :width: 100%

   **Fig. 3.** Verification details.

Step 4: Review summary and submit
=================================

1. Review the **Verification Details** and **Identity Details**.
2. Review the estimated verification time and charges under **Summary**.
3. Click **Submit**.

After submission, the verification is added to the **Verifications** tab on
the **Sender ID Verifications** page. When you open this page, the **Get
Started** tab is displayed by default. Open the **Verifications** tab to find
the submitted verification and use its
:ref:`status <sender_id_verification_statuses>` to track the review.

The estimated review time is shown in the verification summary. The actual
review time may vary depending on the selected countries and whether
additional information is required.

If the status changes to **Changes Required**, see
:doc:`Resubmit a Sender ID Verification
<resubmit-sender-id-verification>`.

.. figure:: https://doc.didww.com/_images/alphanumeric-summary.webp
   :figclass: align-center
   :alt: Summary step for an Alphanumeric Sender ID Verification.
   :width: 100%

   **Fig. 4.** Summary.

Related resources
=================

- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :doc:`../../../sms/sms-trunks/index` - Create and manage SMS trunks.


.. _create_carrier_sender_id_verification:

=======================================
Create a Carrier Sender ID Verification
=======================================

Follow these steps to submit business and messaging details for destinations that use Carrier Sender IDs.

The destination carrier selects the Sender ID that recipients see according to its network requirements.

Before you begin
================

- Review :doc:`Carrier Sender IDs <../sender-id-verification-types/carrier>` to confirm that this Sender ID type matches your messaging use case.
- Create a business identity and address before you begin, or create them during **Step 2: Enter general details**. See :doc:`Manage identities and addresses <../../../identities/getting-started>`.
- Review :doc:`../compliance-content-requirements` before preparing sample messages or consent information.

Step 1: Open the verification form
==================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Get Started** tab.
3. Find the **Carrier** Sender ID type and click **Create New**.

Alternatively, on the **Verifications** tab, open **Create New** and select the **Carrier** Sender ID type.

.. figure:: https://doc.didww.com/_images/carrier-create-new.webp
   :figclass: align-center
   :alt: Carrier card with the Create New button.
   :width: 100%

   **Fig. 1.** Open the Carrier verification form.

Step 2: Enter general details
=============================

1. Enter a **Friendly name**.
2. Select the **Target countries**.
3. Review the **Pricing** and **Identity Requirements** for the selected countries.
4. Select an existing business **Identity** and **Address**, or create them during this step.
5. Click **Next**.

.. important::

   **Target countries** are organized into predefined groups. Selecting any
   country in a group selects the entire group, and a verification can target
   only one group. Countries in a selected group cannot be added or removed
   individually, and groups cannot be combined in the same verification.
   Pricing and Identity Requirements apply once to the whole group, not per
   country.

.. note::

   You do not select, enter, or reserve a Sender ID for this verification. The
   destination carrier selects the Sender ID used to deliver each message.
   After the verification is created, DIDWW generates a Sender ID in the
   ``DDWW0xxxxx`` format for submitting traffic.

   Carrier Sender ID Verification requires a business identity. Personal identities cannot be used.

For field descriptions, see :ref:`Carrier verification setup fields <carrier_verification_reference>`.

.. figure:: https://doc.didww.com/_images/carrier-general.webp
   :figclass: align-center
   :alt: General step for a Carrier Sender ID Verification.
   :width: 100%

   **Fig. 2.** General.

Step 3: Enter verification details
==================================

1. Enter the **Legal Company Name**.
2. Enter the **Website**.
3. Select the **Use case type**.
4. Enter the **Campaign description**.
5. In **How will consumers opt in?**, explain how recipients agree to receive the messages.
6. Enter two representative messages in **Sample content message #1** and **Sample content message #2**.
7. Click **Next**.

For field descriptions, see :ref:`Carrier verification details fields <carrier_verification_reference_business_information>`.

.. figure:: https://doc.didww.com/_images/carrier-business-information.webp
   :figclass: align-center
   :alt: Verification details step for a Carrier Sender ID Verification.
   :width: 100%

   **Fig. 3.** Verification details.

Step 4: Review the summary and submit
=====================================

1. Review the **Verification Details** and **Identity Details**.
2. Review the estimated verification time and charges under **Summary**.
3. Click **Submit**.

After submission, the verification is added to the **Verifications** tab on the **Sender ID Verifications** page.
When you open this page, the **Get Started** tab is displayed by default.
Open the **Verifications** tab to find the submitted verification and use its :ref:`status <sender_id_verification_statuses>` to track the review.

The actual review time may vary depending on the selected countries and whether additional information is required.

If the status changes to **Changes Required**, see :doc:`Resubmit a Sender ID Verification <resubmit-sender-id-verification>`.

.. figure:: https://doc.didww.com/_images/carrier-summary.webp
   :figclass: align-center
   :alt: Summary step for a Carrier Sender ID Verification.
   :width: 100%

   **Fig. 4.** Summary.

Related resources
=================

- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :doc:`../../../sms/sms-trunks/index` - Create and manage SMS trunks.


.. _create_long_code_sender_id_verification:

=========================================
Create a Long-code Sender ID Verification
=========================================

Follow these steps to submit eligible Long-code DID numbers for verification before using them to send A2P SMS messages.

.. important:: This guide applies to supported destination countries other than the United States. For messaging to US recipients, see :doc:`Create a US 10DLC Verification <create-us-10dlc-verification>`.

Before you begin
================

- Review :doc:`Long-code Sender IDs <../sender-id-verification-types/long-code>` to confirm that this Sender ID type matches your messaging use case.
- Make sure your DIDWW account has an active DID number for each destination
  country. Each number must support **Outbound A2P SMS**. See
  :doc:`Buy Numbers <../../../phone-numbers/buy-numbers/index>` and
  :doc:`Supported feature filters
  <../../../phone-numbers/buy-numbers/filters-reference>`.
- Create a business identity and address before you begin, or create them
  during **Step 2: Enter general details**. See
  :doc:`Manage identities and addresses
  <../../../identities/getting-started>`.
- Review :doc:`../compliance-content-requirements` before preparing sample messages or consent information.

Step 1: Open the verification form
==================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Get Started** tab.
3. Find the **Long-code** Sender ID type and click **Create New**.

Alternatively, on the **Verifications** tab, open **Create New** and select the **Long-code** Sender ID type.

.. figure:: https://doc.didww.com/_images/long-code-create-new.webp
   :figclass: align-center
   :alt: Long-code card with the Create New button.
   :width: 100%

   **Fig. 1.** Open the Long-code verification form.

Step 2: Enter general details
=============================

1. Enter a **Friendly name**.
2. Select the **Target countries**.

    .. note:: Do not select the United States. US Long-code Sender IDs require a :doc:`US 10DLC Verification <create-us-10dlc-verification>`.

3. Review the **Pricing** and **Identity Requirements** for the selected countries.
4. Select an existing business **Identity** and **Address**, or create them during this step.
5. Click **Next**.

For field descriptions, see :ref:`Long-code verification setup fields <long_code_verification_reference>`.

.. important::

   A DID number can be linked to only one identity. If a number already uses
   an identity for DID registration, Emergency Calling, or another service,
   select the same business identity for the Sender ID Verification.

   If the number does not have an identity, you can use the business identity
   selected during this step. Personal identities cannot be used for Sender ID
   Verification.

.. figure:: https://doc.didww.com/_images/long-code-general.webp
   :figclass: align-center
   :alt: General step for a Long-code Sender ID Verification.
   :width: 100%

   **Fig. 2.** General.

Step 3: Select Sender IDs
=========================

1. Under **Available source numbers**, select the DID numbers to verify.
2. Move the numbers to **Allowed source addresses**.
3. Review the selected Sender IDs.
4. Click **Next**.

.. note::

   You can include up to 49 Sender IDs in one verification.

   Use the **DID number** and **Description** filters to narrow the list of
   available numbers. To remove all numbers from **Allowed source
   addresses**, click **Remove all**.

Only DID numbers that meet all the following requirements appear under
**Available source numbers**:

- The number is active.
- It supports **Outbound A2P SMS**.
- It is not assigned to another Sender ID Verification.
- It has no assigned identity or uses the business identity selected in
  **Step 2: Enter general details**.

Numbers linked to a different business identity or a personal identity are not
available for selection.

If no numbers appear, check whether your existing numbers meet these
requirements. To purchase a new number, see
:doc:`Buy Numbers <../../../phone-numbers/buy-numbers/index>`.

.. figure:: https://doc.didww.com/_images/long-code-sender-ids.gif
   :figclass: align-center
   :alt: Selecting eligible DID numbers as Long-code Sender IDs.
   :width: 100%

   **Fig. 3.** Select Sender IDs.

Step 4: Enter verification details
==================================

1. Enter the **Legal Company Name** and **Website**.
2. Select the **Use case type**.
3. Enter the **Campaign description**.
4. In **How will consumers opt in?**, explain how recipients agree to receive
   the messages.
5. Enter two representative messages in **Sample content message #1** and
   **Sample content message #2**.
6. Click **Next**.

For field descriptions, see :ref:`Long-code standard verification details fields <long_code_verification_reference_business_information>`.

.. figure:: https://doc.didww.com/_images/long-code-business-information.webp
   :figclass: align-center
   :alt: Verification details step for a Long-code Sender ID Verification.
   :width: 100%

   **Fig. 4.** Verification details.

Step 5: Review summary and submit
=================================

1. Review the **Verification Details**, **Identity Details**, and **Sender IDs**. Use **Copy** or **Select All** to copy the listed Sender IDs.
2. Review the estimated verification time and charges under **Summary**.
3. Click **Submit**.

After submission, the verification is added to the **Verifications** tab on
the **Sender ID Verifications** page. When you open this page, the **Get
Started** tab is displayed by default. Open the **Verifications** tab to find
the submitted verification and use its
:ref:`status <sender_id_verification_statuses>` to track the review.

The actual review time may vary depending on the selected countries and
whether additional information is required.

If the status changes to **Changes Required**, see
:doc:`Resubmit a Sender ID Verification
<resubmit-sender-id-verification>`.

.. figure:: https://doc.didww.com/_images/long-code-summary.webp
   :figclass: align-center
   :alt: Summary step for a Long-code Sender ID Verification.
   :width: 100%

   **Fig. 5.** Summary.

Related resources
=================

- :doc:`create-us-10dlc-verification` - Register Long-code Sender IDs for the United States.
- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :doc:`../../../sms/sms-trunks/index` - Create and manage SMS trunks.


.. _create_toll_free_sender_id_verification:

=========================================
Create a Toll-Free Sender ID Verification
=========================================

Follow these steps to submit US Toll-Free DID numbers for verification before using them to send A2P SMS messages.

Before you begin
================

- Review :doc:`Toll-Free Sender IDs <../sender-id-verification-types/toll-free>` to confirm that this Sender ID type matches your messaging use case.
- Make sure your DIDWW account has an active US Toll-Free DID number that
  supports **Outbound A2P SMS**. See
  :doc:`Buy Numbers <../../../phone-numbers/buy-numbers/index>` and
  :doc:`Supported feature filters
  <../../../phone-numbers/buy-numbers/filters-reference>`.
- Create a business identity and address before you begin, or create them
  during **Step 2: Enter general details**. See
  :doc:`Manage identities and addresses
  <../../../identities/getting-started>`.
- Review :doc:`Compliance content requirements <../compliance-content-requirements>` before preparing your business, campaign, consent, and sample-message information.

Step 1: Open the verification form
==================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Get Started** tab.
3. Find the **Toll-Free** Sender ID type and click **Create New**.

Alternatively, on the **Verifications** tab, open **Create New** and select the **Toll-Free** Sender ID type.

.. figure:: https://doc.didww.com/_images/toll-free-create-new.webp
   :figclass: align-center
   :alt: Toll-Free card with the Create New button.
   :width: 100%

   **Fig. 1.** Open the Toll-Free verification form.

Step 2: Enter general details
=============================

1. Enter a **Friendly name**.
2. Review the **Pricing** and **Identity Requirements**.
3. Select an existing business **Identity** and **Address**, or create them during this step.
4. Click **Next**.

.. important::

   A DID number can be linked to only one identity. If a number already uses
   an identity for DID registration or another service, select the same
   business identity for the Toll-Free Sender ID Verification.

   If the number does not have an identity, you can use the business identity
   selected during this step. Personal identities cannot be used for a
   Toll-Free Sender ID Verification.

For field descriptions, see :ref:`Toll-Free verification setup fields <toll_free_verification_reference>`.

.. figure:: https://doc.didww.com/_images/toll-free-general.webp
   :figclass: align-center
   :alt: General step for a Toll-Free Sender ID Verification.
   :width: 100%

   **Fig. 2.** General.

Step 3: Select Sender IDs
=========================

1. Under **Available source numbers**, select the eligible United States Toll-Free DID numbers to verify.
2. Move the selected numbers to **Allowed source addresses**.
3. Review the selected Sender IDs and click **Next**.

.. note::

   You can include up to 49 Sender IDs in one verification.

   Use the **DID number** and **Description** filters to narrow the list of
   available numbers. To remove all numbers from **Allowed source
   addresses**, click **Remove all**.

Only DID numbers that meet all the following requirements appear under **Available source numbers**:

- The number is an active US Toll-Free DID number.
- It supports **Outbound A2P SMS**.
- It is not assigned to another Sender ID Verification.
- It has no assigned identity or uses the business identity selected in
  **Step 2: Enter general details**.

Numbers linked to a different business identity or a personal identity are not available for selection.

If no numbers appear, check whether your existing numbers meet these requirements. To purchase a new number, see :doc:`Buy Numbers <../../../phone-numbers/buy-numbers/index>`.

.. figure:: https://doc.didww.com/_images/toll-free-sender-ids.gif
   :figclass: align-center
   :alt: Selecting eligible United States Toll-Free DID numbers as Sender IDs.
   :width: 100%

   **Fig. 3.** Select Sender IDs.

Step 4: Enter verification details
==================================

1. Enter the business registration information.
2. Enter the **Website**.
3. Indicate whether the business is a **Fortune 500 or 1000 company**.
4. Select the **Use case type**.
5. Enter the **Campaign description**.
6. Under **How will customers opt in?**, select one or more methods:
   **Through my website**, **Through my app**, **Verbal agreement**, or
   **Physical form**.
7. If you select **Through my app** or **Physical form**, upload the requested
   screenshots or scans of the opt-in form.
8. Enter the **Detailed opt-in flow description** and select the required
   opt-in confirmation checkbox.
9. Enter two representative messages in **Sample content messages #1** and **Sample content messages #2**.
10. If the messages contain URLs or phone numbers, list them in the appropriate fields.
11. Describe where customers can find the Toll-Free numbers and upload supporting screenshots when applicable.
12. Enter the expected message volume.
13. Indicate whether the messages **promote a commercial product**.
14. Select whether this traffic was previously sent using another messaging
    service. If it was sent using a short code or long number, enter the
    previous content and numbers used with that service.
15. Provide links to the privacy policy and terms and conditions.
16. Click **Next**.

For field descriptions, see :ref:`Toll-Free verification details fields <toll_free_verification_reference_business_information>`.

.. figure:: https://doc.didww.com/_images/toll-free-business-information.webp
   :figclass: align-center
   :alt: Verification details step for a Toll-Free Sender ID Verification.
   :width: 100%

   **Fig. 4.** Verification details.

Step 5: Review summary and submit
=================================

1. Review the **Verification Details**, **Identity Details**, and **Sender IDs**. Use **Copy** or **Select All** to copy the listed Sender IDs.
2. Review the estimated verification time and charges under **Summary**.
3. Click **Submit**.

After submission, the verification is added to the **Verifications** tab on the **Sender ID Verifications** page. When you open this page, the **Get Started** tab is displayed by default.
Open the **Verifications** tab to find the submitted verification and use its :ref:`status <sender_id_verification_statuses>` to track the review.

The actual review time may vary depending on whether additional information is required.

If the status changes to **Changes Required**, see :doc:`Resubmit a Sender ID Verification <resubmit-sender-id-verification>`.

.. figure:: https://doc.didww.com/_images/toll-free-summary.webp
   :figclass: align-center
   :alt: Summary step for a Toll-Free Sender ID Verification.
   :width: 100%

   **Fig. 5.** Summary.

Related resources
=================

- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :doc:`../../../sms/sms-trunks/index` - Create and manage SMS trunks.


.. _create_us_10dlc_verification:

==============================
Create a US 10DLC Verification
==============================

Follow these steps to submit US 10-digit long-code DID numbers for verification
before using them to send A2P SMS messages to US recipients.

.. important::

   This guide applies only to Long-code Sender IDs used for messaging to US
   recipients. For other supported destination countries, see
   :doc:`Create a Long-code Sender ID Verification
   <create-long-code-verification>`.

Before you begin
================

- Review :doc:`Long-code Sender IDs
  <../sender-id-verification-types/long-code>` to confirm that Long-code is the
  correct Sender ID type for your messaging use case.
- Make sure your DIDWW account has an active US 10-digit long-code DID number
  that supports **Outbound A2P SMS**. See
  :doc:`Buy Numbers <../../../phone-numbers/buy-numbers/index>` and
  :doc:`Supported feature filters
  <../../../phone-numbers/buy-numbers/filters-reference>`.
- Create a business identity and address before you begin, or create them
  during **Step 2: Enter general details**. See
  :doc:`Manage identities and addresses
  <../../../identities/getting-started>`.
- Review :doc:`Compliance content requirements
  <../compliance-content-requirements>` before preparing your business,
  campaign, consent, and sample-message information.

Step 1: Open the verification form
==================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Get Started** tab.
3. Find the **Long-code** Sender ID type and click **Create New**.

Alternatively, on the **Verifications** tab, open **Create New** and select the **Long-code** Sender ID type.

.. figure:: https://doc.didww.com/_images/long-code-create-new.webp
   :figclass: align-center
   :alt: Long-code card with the Create New button.
   :width: 100%

   **Fig. 1.** Open the Long-code verification form.

Step 2: Enter general details
=============================

1. Enter a **Friendly name**.
2. Select **United States** as the **Target country**.
3. Review the **Pricing** and **Identity Requirements**.
4. Select an existing business **Identity** and **Address**, or create them during this step.
5. Click **Next**.

.. important::

   A DID number can be linked to only one identity. If a number already uses
   an identity for DID registration, Emergency Calling, or another service,
   select the same business identity for the US 10DLC Verification.

   If the number does not have an identity, you can use the business identity
   selected during this step. Personal identities cannot be used for US 10DLC
   Verification.

For field descriptions, see :ref:`Long-code verification setup fields <long_code_verification_reference>`.

.. figure:: https://doc.didww.com/_images/us-10dlc-general.webp
   :figclass: align-center
   :alt: General step for a US 10DLC Verification.
   :width: 100%

   **Fig. 2.** General.

Step 3: Select Sender IDs
=========================

1. Under **Available source numbers**, select the US DID numbers that you want to verify.
2. Move the numbers to **Allowed source addresses**.
3. Review the selected Sender IDs.
4. Click **Next**.

.. note::

   You can include up to 49 Sender IDs in one verification.

   Use the **DID number** and **Description** filters to narrow the list of
   available numbers. To remove all numbers from **Allowed source
   addresses**, click **Remove all**.

Only DID numbers that meet all the following requirements appear under
**Available source numbers**:

- The number is an active US 10-digit long-code DID number.
- It supports **Outbound A2P SMS**.
- It is not assigned to another Sender ID Verification.
- It has no assigned identity or uses the business identity selected in
  **Step 2: Enter general details**.

Numbers linked to a different business identity or a personal identity are not
available for selection.

If no numbers appear, check whether your existing numbers meet these
requirements. To purchase a new number, see
:doc:`Buy Numbers <../../../phone-numbers/buy-numbers/index>`.

.. figure:: https://doc.didww.com/_images/us-10dlc-sender-ids.gif
   :figclass: align-center
   :alt: Selecting eligible United States DID numbers as Sender IDs.
   :width: 100%

   **Fig. 3.** Select Sender IDs.

Step 4: Enter verification details
==================================

1. Enter the legal business and brand information.
2. Select the **Use case type**.
3. Enter the **Campaign description**.
4. Under **How will customers opt in?**, select one or more methods:
   **Through my website**, **Through my app**, **Verbal agreement**, or
   **Physical form**.
5. If you select **Through my app** or **Physical form**, upload the requested
   screenshots or scans of the opt-in form.
6. Enter the **Detailed opt-in flow description** and select the required
   opt-in confirmation checkbox.
7. Enter the required opt-in, opt-out, and help keywords and messages.
8. Enter two representative messages in **Sample content messages #1** and **Sample content messages #2**.
9. If the messages contain URLs or phone numbers, list them in the appropriate fields.
10. Provide links to the privacy policy and terms and conditions.
11. Click **Next**.

For field descriptions and examples, see :ref:`United States 10DLC verification details fields <us_10dlc_verification_reference_business_information>`.

.. figure:: https://doc.didww.com/_images/us-10dlc-business-information.webp
   :figclass: align-center
   :alt: Verification details step for a US 10DLC Verification.
   :width: 100%

   **Fig. 4.** Verification details.

Step 5: Review summary and submit
=================================

1. Review the **Verification Details**, **Identity Details**, and **Sender IDs**. Use **Copy** or **Select All** to copy the listed Sender IDs.
2. Review the estimated verification time and charges under **Summary**.
3. Click **Submit**.

After submission, the verification is added to the **Verifications** tab on the **Sender ID Verifications** page. When you open this page, the **Get
Started** tab is displayed by default. Open the **Verifications** tab to find the submitted verification and use its :ref:`status <sender_id_verification_statuses>` to track the review.

The actual review time may vary depending on whether additional information is required.

If the status changes to **Changes Required**, see :doc:`Resubmit a Sender ID Verification <resubmit-sender-id-verification>`.

.. figure:: https://doc.didww.com/_images/us-10dlc-summary.webp
   :figclass: align-center
   :alt: Summary step for a US 10DLC Verification.
   :width: 100%

   **Fig. 5.** Summary.

Related resources
=================

- :doc:`create-long-code-verification` - Register Long-code Sender IDs outside the United States.
- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :doc:`../../../sms/sms-trunks/index` - Create and manage SMS trunks.


.. _edit_sender_id_verification:

=============================
Edit a Sender ID Verification
=============================

Use this guide to change a verification's friendly name or associated SMS trunk, remove supported Sender IDs, or request additional Sender IDs where available.

Step 1: Open the verification
=============================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Verifications** tab.
3. Find the verification and click the actions button.
4. Select **Edit campaign**.

.. figure:: https://doc.didww.com/_images/edit-verification-action.webp
   :figclass: align-center
   :alt: Edit campaign action for a Sender ID Verification.
   :width: 100%

   **Fig. 1.** Open the Edit campaign action.

Step 2: Update the verification
===============================

You can update the **Friendly name**, manage the associated SMS trunk, or add
or remove Sender IDs where supported. Follow the applicable tab below.

.. tab-set::
   :class: my-tabs

   .. tab-item:: General settings

      Under **General**, make any required changes:

      - To change the verification name, update the **Friendly name**.
      - To associate an outbound SMS trunk, select it under **SMS trunk**.
      - To remove the associated trunk, clear the **SMS trunk** field.

      An HTTP OUT SMS trunk is required to send an individual message directly
      from the verification in the DIDWW User Panel. For instructions, see
      :doc:`Send an SMS using a verified Sender ID
      <send-sms-using-verified-sender-id>`.

      .. figure:: https://doc.didww.com/_images/edit-verification-sms-trunk.webp
         :figclass: align-center
         :alt: SMS trunk field on the Edit Sender ID Verification page.
         :width: 100%

         **Fig. 2.** Manage the SMS trunk.

   .. tab-item:: Remove Sender IDs

      Sender IDs can be removed from **Long-code** and **Toll-Free** verifications.

      .. note::

         - To change an **Alphanumeric** Sender ID, contact `sales@didww.com <mailto:sales@didww.com>`_.
         - A Carrier Sender ID is generated by DIDWW and cannot be changed or removed. It remains available on this page as a copyable value.

      1. Under **Sender IDs**, select one or more numbers, or click **Select
         All**.
      2. To copy the selected values, click **Copy**.
      3. To remove the selected numbers, click **Remove**.

      .. figure:: https://doc.didww.com/_images/edit-verification-sender-ids.webp
         :figclass: align-center
         :alt: Sender ID selection with Remove, Copy, and selection controls.
         :width: 100%

         **Fig. 3.** Select, copy, or remove Sender IDs.

      4. In the **Remove Sender ID(s)** dialog, click **Remove**.

      .. figure:: https://doc.didww.com/_images/edit-verification-remove-sender-ids.webp
         :figclass: align-center
         :alt: Remove Sender ID confirmation dialog.
         :width: 100%

         **Fig. 4.** Confirm removal.

   .. tab-item:: Add Sender IDs

      To add Sender IDs to an existing **US 10DLC** or **Toll-Free**
      verification, contact your account manager or DIDWW Customer Support at
      `customer.care@didww.com <mailto:customer.care@didww.com>`_. Include the
      DID numbers that you want to add.

      .. note:: A verification can include up to 49 Sender IDs.

      Sender IDs cannot be added to other verification types. Create a new
      verification instead.

Step 3: Submit the changes
==========================

Review your changes and click **Submit**.

.. figure:: https://doc.didww.com/_images/edit-verification-submit.webp
   :figclass: align-center
   :alt: Submit button on the Edit Sender ID Verification page.
   :width: 100%

   **Fig. 5.** Submit the changes.

Related resources
=================

- :doc:`resubmit-sender-id-verification` - Correct a verification in Changes Required status.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :doc:`../../../sms/sms-trunks/index` - Create and manage SMS trunks.


=============
How-to guides
=============

Use these guides to create and manage Sender ID Verifications.

Create verifications
====================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Create Alphanumeric Sender ID Verification**
      :link: create-alphanumeric-verification
      :link-type: doc
      :text-align: left

      Submit a branded Alphanumeric Sender ID for verification.

   .. grid-item-card:: **Create Long-code Sender ID Verification**
      :link: create-long-code-verification
      :link-type: doc
      :text-align: left

      Submit eligible long-code DID numbers outside the United States.

   .. grid-item-card:: **Create US 10DLC Verification**
      :link: create-us-10dlc-verification
      :link-type: doc
      :text-align: left

      Submit eligible 10-digit long-code DID numbers for A2P SMS to recipients in the United States.

   .. grid-item-card:: **Create Toll-Free Sender ID Verification**
      :link: create-toll-free-verification
      :link-type: doc
      :text-align: left

      Submit eligible United States Toll-Free DID numbers for verification.

   .. grid-item-card:: **Create Carrier Sender ID Verification**
      :link: create-carrier-verification
      :link-type: doc
      :text-align: left

      Submit messaging traffic for verification where required by a supported destination.

Manage verifications
====================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Edit Sender ID Verification**
      :link: edit-sender-id-verification
      :link-type: doc
      :text-align: left

      Change the friendly name, manage the SMS trunk, or remove eligible Sender IDs.

   .. grid-item-card:: **View a Sender ID Verification**
      :link: view-sender-id-verification
      :link-type: doc
      :text-align: left

      Open a verification to review its fields, status, and available actions.

   .. grid-item-card:: **Resubmit Sender ID Verification**
      :link: resubmit-sender-id-verification
      :link-type: doc
      :text-align: left

      Correct a verification in Changes Required status and restart review.

   .. grid-item-card:: **Send SMS using verified Sender ID**
      :link: send-sms-using-verified-sender-id
      :link-type: doc
      :text-align: left

      Send an individual SMS from the User Panel using an active verification.

   .. grid-item-card:: **Cancel Sender ID Verification**
      :link: cancel-sender-id-verification
      :link-type: doc
      :text-align: left

      Request closure of a verification.

.. toctree::
   :maxdepth: 1
   :hidden:

   Create Alphanumeric Sender ID Verification <create-alphanumeric-verification.rst>
   Create Long-code Sender ID Verification <create-long-code-verification.rst>
   Create US 10DLC Verification <create-us-10dlc-verification.rst>
   Create Toll-Free Sender ID Verification <create-toll-free-verification.rst>
   Create Carrier Sender ID Verification <create-carrier-verification.rst>
   Edit Sender ID Verification <edit-sender-id-verification.rst>
   View a Sender ID Verification <view-sender-id-verification.rst>
   Resubmit Sender ID Verification <resubmit-sender-id-verification.rst>
   Send SMS using verified Sender ID <send-sms-using-verified-sender-id.rst>
   Cancel Sender ID Verification <cancel-sender-id-verification.rst>


.. _view_sender_id_verification:

=============================
View a Sender ID Verification
=============================

Open a Sender ID Verification to see its Sender IDs, along with its status and other fields and available actions.

Step 1: Locate the verification
================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Verifications** tab.
3. Find the verification and **click its name** to open it. Use the
   filters if you have many verifications.

.. figure:: https://doc.didww.com/_images/view-verification-locate.webp
   :figclass: align-center
   :alt: Verifications tab listing Sender ID Verifications.
   :width: 100%

   **Fig. 1.** Locate the verification.

Step 2: Review the verification
================================

Review the verification's fields, status, and available actions on its
details page.

For field descriptions, see :ref:`Sender ID Verification fields <sender_id_verification_fields>`.

.. figure:: https://doc.didww.com/_images/view-verification-details.webp
   :figclass: align-center
   :alt: Sender ID Verification details page.
   :width: 100%

   **Fig. 2.** The verification details page.

Related resources
=================

- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.


.. _resubmit_sender_id_verification:

=================================
Resubmit a Sender ID Verification
=================================

Use this guide to correct and resubmit a Sender ID Verification with the **Changes Required** status.

.. warning::

   Resubmit the verification within 10 days after its status changes to
   **Changes Required**. If you do not resubmit it within this period, the
   verification is automatically terminated.

Step 1: Find verifications that require changes
================================================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Verifications** tab.
3. In the **Status** filter, select **Changes required**.

.. figure:: https://doc.didww.com/_images/resubmit-filter-changes-required.webp
   :figclass: align-center
   :alt: Changes required Status filter on the Sender ID Verifications page.
   :width: 100%

   **Fig. 1.** Filter verifications by Changes required status.

Step 2: Open the verification for resubmission
==============================================

1. Find the verification and click the actions button.
2. Select **Resubmit**.

.. figure:: https://doc.didww.com/_images/resubmit-action.webp
   :figclass: align-center
   :alt: Resubmit action for a Sender ID Verification in Changes required status.
   :width: 100%

   **Fig. 2.** Open the Resubmit action.

Step 3: Make the required changes
=================================

1. Review the reasons and comments under **Required Changes**.
2. Review the pre-filled information from the previous submission.
3. Update each field identified in the review comments.
4. Provide any additional requested information.
5. Upload attachments requested by the current form, when required.

The same fields and validation rules used during creation apply during
resubmission. The former campaign PDF upload is not part of this flow.

For field descriptions, see :doc:`../sender-id-verification-reference`. For
message and consent requirements, see :doc:`../compliance-content-requirements`.

.. figure:: https://doc.didww.com/_images/resubmit-required-changes.webp
   :figclass: align-center
   :alt: Required Changes panel and corrected campaign description on the Resubmit Sender ID Verification page.
   :width: 100%

   **Fig. 3.** Review and address the required changes.

Step 4: Resubmit the verification
=================================

Review the corrected information and click **Submit**.

.. figure:: https://doc.didww.com/_images/resubmit-submit.webp
   :figclass: align-center
   :alt: Submit button on the Resubmit Sender ID Verification page.
   :width: 100%

   **Fig. 4.** Submit the corrected verification.

After successful resubmission, the status changes to **In Process** and the
review restarts. The review time may vary if additional information is
required.

Related resources
=================

- :doc:`edit-sender-id-verification` - Manage SMS trunks and Sender IDs for your verifications.
- :doc:`../how-sender-id-verification-works` - Understand verification review.
- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.


.. _send_sms_using_verified_sender_id:

====================================
Send an SMS using verified Sender ID
====================================

Use the DIDWW User Panel to send a single SMS message using a verified Sender ID.

Before you begin
================

- The Sender ID Verification must have the :ref:`Active status <sender_id_verification_statuses>`.
- An :ref:`HTTP OUT SMS trunk <user_panel_sms_out>` must be associated with the verification. To associate or change the trunk, see :doc:`Edit a Sender ID Verification <edit-sender-id-verification>`.

Step 1: Open the Send SMS form
==============================

1. In the DIDWW User Panel, go to **SMS > Sender ID Verifications**.
2. Open the **Verifications** tab.
3. Find the verification with the **Active** status and click the actions button.
4. Select **Send SMS**.

.. figure:: https://doc.didww.com/_images/send-sms-action.webp
   :figclass: align-center
   :alt: Send SMS action for an active Sender ID Verification.
   :width: 100%

   **Fig. 1.** Open the Send SMS action.

Step 2: Compose and send the message
====================================

.. tab-set::

   .. tab-item:: Alphanumeric, Long-code, and Toll-Free

      1. Select the **Source Address**.
      2. Enter the destination number in international format, including the country code.
      3. Enter the message in the **Text** field.
      4. Click **Send**.

      .. note::

         For **Alphanumeric**, **Long-code**, and **Toll-Free** verifications, only
         Sender IDs assigned to the verification are available under **Source
         Address**.

      .. figure:: https://doc.didww.com/_images/send-sms-form.webp
         :figclass: align-center
         :alt: Send SMS form for a Sender ID Verification.
         :width: 100%

         **Fig. 2.** Compose and send the SMS message.

   .. tab-item:: Carrier

      1. Enter the destination number in international format, including the country code.
      2. Enter the message in the **Text** field.
      3. Click **Send**.

      .. note:: The Carrier form does not contain **Source Address**. The destination carrier determines the Sender ID that recipients see.

      .. figure:: https://doc.didww.com/_images/send-sms-form-carrier.webp
         :figclass: align-center
         :alt: Send SMS form for a Carrier Sender ID Verification.
         :width: 100%

         **Fig. 3.** Compose and send the SMS message for a Carrier verification.

The message is submitted through the associated HTTP OUT SMS trunk. To review its status, see :doc:`Outbound SMS logs <../../../logs-analytics/sms-logs/outbound-logs>`.

To send messages through the API, see :ref:`Outbound SMS examples <sms_out_spec_sending>`.

Related resources
=================

- :doc:`../sender-id-verification-reference` - Review fields, types, and status values.
- :ref:`HTTP OUT SMS trunk <user_panel_sms_out>` - Configure an outbound HTTP trunk.
- :doc:`../compliance-content-requirements` - Review message content requirements.


.. _user_panel_sms_campaign:
.. _sender_id_verifications:

=======================
Sender ID Verifications
=======================

A Sender ID Verification confirms that a business and its messaging use case
meet the requirements for sending application-to-person (A2P) SMS with a
specific Sender ID type.

Depending on the verification type, it can cover an Alphanumeric Sender ID,
Long-code or Toll-Free DID numbers, or messages that use a dynamic Sender ID
assigned by the destination carrier.

After approval, the covered Sender IDs can be used to send messages that match
the approved business, destination countries, and messaging purpose. For a
Carrier verification, the approval applies to the messages because the
destination carrier assigns the Sender ID.

Messages must be sent through the outbound SMS trunk associated with the
verification. Requirements, review times, and charges vary by verification
type and country.

Key features
============

- Verify a business or brand name for use as an Alphanumeric Sender ID.
- Verify supported Long-code and Toll-Free DID numbers for A2P SMS.
- Verify messages that use a dynamic Sender ID assigned by the destination carrier.
- Receive replies using Long-code or Toll-Free Sender IDs where two-way messaging is supported.
- Send messages that match an active verification through an associated outbound SMS trunk.

Get started
===========

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **How Sender ID Verification works**
      :link: how-sender-id-verification-works
      :link-type: doc
      :text-align: left

      Understand Sender IDs, verification, SMS trunk relationships, lifecycle, and billing.

   .. grid-item-card:: **Sender ID types**
      :link: sender-id-verification-types/index
      :link-type: doc
      :text-align: left

      Compare Alphanumeric, Long-code, Toll-Free, and Carrier Sender IDs.

   .. grid-item-card:: **Compliance content requirements**
      :link: compliance-content-requirements
      :link-type: doc
      :text-align: left

      Prepare compliant message content, consent flows, and opt-out methods.

   .. grid-item-card:: **How-to guides**
      :link: how-to-guides/index
      :link-type: doc
      :text-align: left

      Create, edit, resubmit, use, and cancel Sender ID Verifications.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **Sender ID Verification reference**
      :link: sender-id-verification-reference
      :link-type: doc
      :text-align: left

      Look up filters, fields, verification types, status values, and use-case values.

   .. grid-item-card:: **SMS trunks**
      :link: ../sms-trunks/index
      :link-type: doc
      :text-align: left

      Create and manage trunks for inbound and outbound SMS.

   .. grid-item-card:: **My Numbers**
      :link: ../../phone-numbers/my-numbers/index
      :link-type: doc
      :text-align: left

      Review SMS-enabled DID numbers and their assigned services.

   .. grid-item-card:: **Buy numbers**
      :link: ../../phone-numbers/buy-numbers/index
      :link-type: doc
      :text-align: left

      Purchase DID numbers with the features required for your messaging setup.

   .. grid-item-card:: **Identities & Addresses**
      :link: ../../identities/index
      :link-type: doc
      :text-align: left

      Create and manage business identity and address records.

   .. grid-item-card:: **SMS Logs**
      :link: ../../logs-analytics/sms-logs/index
      :link-type: doc
      :text-align: left

      Review outbound message activity and delivery information.

.. toctree::
   :maxdepth: 1
   :hidden:

   How Sender ID Verification works <how-sender-id-verification-works.rst>
   Sender ID types <sender-id-verification-types/index.rst>
   Compliance content requirements <compliance-content-requirements.rst>
   How-to guides <how-to-guides/index.rst>
   Sender ID Verification reference <sender-id-verification-reference.rst>


.. _sender_id_verification_types:

===============
Sender ID types
===============

A Sender ID is the name or phone number displayed as the sender of an SMS
message. The Sender ID type determines what recipients see, whether they can
reply, and which requirements apply in the destination country.

The appearance of a Sender ID may vary by device and messaging application.
The following examples show how each Sender ID type may appear to recipients.

.. grid:: 1 1 2 2
   :gutter: 2
   :class-container: sender-id-type-examples

   .. grid-item::

      **Alphanumeric**

      .. image:: https://doc.didww.com/_images/alphanumeric.webp
         :alt: Example message from an Alphanumeric Sender ID.
         :width: 100%

   .. grid-item::

      **Long-code**

      .. image:: https://doc.didww.com/_images/long-code.webp
         :alt: Example message from a Long-code Sender ID.
         :width: 100%

   .. grid-item::

      **Toll-Free**

      .. image:: https://doc.didww.com/_images/toll-free.webp
         :alt: Example message from a Toll-Free Sender ID.
         :width: 100%

   .. grid-item::

      **Carrier**

      .. image:: https://doc.didww.com/_images/carrier.webp
         :alt: Example message using a Carrier Sender ID.
         :width: 100%

Sender ID type comparison
=========================

.. list-table::
   :header-rows: 1
   :widths: 18 22 30 30
   :width: 100%

   * - Type
     - Sender ID format
     - Common uses
     - Main requirements
   * - :doc:`Alphanumeric <alphanumeric>`
     - A brand name containing letters and numbers, such as ``MyBrand``.
     - * Branded one-way notifications
       * Alerts
       * Authentication messages
     - * Sender ID that matches the brand in the business identity
       * Business identity and address
       * Business and messaging information required by the destination
         countries
   * - :doc:`Long-code <long-code>`
     - A full-length phone number, such as ``12025550123``.
     - * Two-way customer communication
       * Business notifications sent from a consistent phone number
       * US A2P messaging using 10DLC registration
     - * Eligible active DID number with A2P SMS support
       * Business identity and address
       * Business and messaging information
   * - :doc:`Toll-Free <toll-free>`
     - A US Toll-Free DID number, such as ``18005550123``.
     - * Customer care
       * Service notifications
       * Business messaging using a Toll-Free number
     - * Eligible active US Toll-Free DID number with A2P SMS support
       * Business identity and address
       * Business and messaging information
   * - :doc:`Carrier <carrier>`
     - A dynamic Sender ID selected by the destination carrier according to
       local network requirements.
     - * One-way notifications
       * Alerts
       * Authentication messages
       * Messaging to supported Latin American countries
     - * Business identity and address
       * Business and messaging information

Learn more about Sender ID types
================================

.. grid:: 1 1 2 2
   :gutter: 4

   .. grid-item-card:: **Alphanumeric**
      :link: alphanumeric
      :link-type: doc
      :text-align: left

      Present a recognizable business or brand name instead of a phone number.

   .. grid-item-card:: **Long-code**
      :link: long-code
      :link-type: doc
      :text-align: left

      Send A2P SMS from an eligible DID number and support replies where two-way messaging is available.

   .. grid-item-card:: **Toll-Free**
      :link: toll-free
      :link-type: doc
      :text-align: left

      Send business messages from an eligible US Toll-Free DID number.

   .. grid-item-card:: **Carrier**
      :link: carrier
      :link-type: doc
      :text-align: left

      Use a dynamic Sender ID that is assigned by the carrier when the message is delivered.

Related resources
=================

.. grid:: 1 1 2 3
   :gutter: 4

   .. grid-item-card:: **How-to guides**
      :link: ../how-to-guides/index
      :link-type: doc
      :text-align: left

      Create and manage Sender ID Verifications in the DIDWW User Panel.

   .. grid-item-card:: **Sender ID Verification reference**
      :link: ../sender-id-verification-reference
      :link-type: doc
      :text-align: left

      Look up verification fields, types, statuses, and use-case values.

   .. grid-item-card:: **Compliance content requirements**
      :link: ../compliance-content-requirements
      :link-type: doc
      :text-align: left

      Prepare compliant message content, consent flows, and opt-out methods.

.. toctree::
   :maxdepth: 1
   :hidden:

   Alphanumeric <alphanumeric.rst>
   Long-code <long-code.rst>
   Toll-Free <toll-free.rst>
   Carrier <carrier.rst>


.. _alphanumeric_sender_ids:

============
Alphanumeric
============

An Alphanumeric Sender ID is a recognizable business or brand name, such as ``MyBrand``, that appears instead of a phone number in one-way A2P SMS messages. It must contain 2 to 11 characters and may include only letters (``a-z`` and ``A-Z``) and numbers (``0-9``).

Common uses
===========

Use an Alphanumeric Sender ID when recipients should recognize the sender and do not need to reply directly. Common uses include:

- Authentication and security notifications.
- Account and service alerts.
- Appointment or delivery updates.
- Transactional notifications.
- Marketing messages that meet the applicable requirements.

How messages appear
===================

Recipients usually see the approved Sender ID instead of a phone number. Its exact appearance may vary by mobile carrier, device, and messaging application. Use a value that clearly matches the business or brand sending the message.

.. figure:: https://doc.didww.com/_images/alphanumeric.webp
   :figclass: align-center
   :alt: Example message from an Alphanumeric Sender ID with a link for help or opting out.
   :width: 40%

   **Fig. 1.** Example message from an Alphanumeric Sender ID.

Messaging and replies
=====================

Recipients cannot reply directly to an Alphanumeric Sender ID because it is not a phone number. If recipients need to contact you or opt out, include a supported contact or opt-out method in the message.

Relationship with DID numbers
=============================

An Alphanumeric Sender ID is not linked to a DID number. You do not need to purchase, port, or assign a DID number to the DIDWW account to use this Sender ID type.

Availability
============

Alphanumeric Sender ID availability varies by country.

Check current availability on the `DIDWW website <https://www.didww.com/services/two-way-sms/a2p-messaging>`_ or view the available verification options in the `DIDWW User Panel <https://my.didww.com/#/sender_id_verifications/get_started>`_.

Verification requirements
=========================

An Alphanumeric Sender ID must be verified before use. The verification links the Sender ID to the business, target countries, and messaging use case submitted for review.

The Sender ID and messages sent with it must match the approved verification details. For required submission fields, see :ref:`Alphanumeric verification <alphanumeric_verification_reference>`.

To submit a verification, see :doc:`Create Alphanumeric Sender ID Verification <../how-to-guides/create-alphanumeric-verification>`.

Using a verified Sender ID
==========================

After the verification becomes :ref:`Active <sender_id_verification_statuses>`, associate it with an outbound SMS trunk. Use that trunk to send messages that match the approved business, destination countries, and messaging use case.

For sending instructions, see :doc:`Send SMS using verified Sender ID <../how-to-guides/send-sms-using-verified-sender-id>` or the :doc:`HTTP Specification <../../sms-trunks/technical-data/http-specification>`.

Related resources
=================

- :doc:`Create Alphanumeric Sender ID Verification <../how-to-guides/create-alphanumeric-verification>`
- :doc:`Sender ID Verification reference <../sender-id-verification-reference>`
- :doc:`Sender ID content requirements <../compliance-content-requirements>`
- :doc:`Sender ID types <index>`


.. _long_code_sender_ids:

=========
Long-code
=========

A Long-code Sender ID is an eligible DID phone number used to send A2P SMS messages. Recipients see the DID number as the message sender. Long-code Sender IDs can also support two-way messaging.

Common uses
===========

Use a Long-code Sender ID when recipients should see a consistent DID number or need to reply. Common uses include:

- Two-way customer support and conversations.
- Appointment and delivery updates that allow replies.
- Account and service notifications sent from a consistent phone number.
- US A2P messaging that requires 10DLC registration.

How messages appear
===================

Recipients see the approved DID number as the message sender. Using the same number for related messages helps recipients recognize the sender and follow the conversation.

.. figure:: https://doc.didww.com/_images/long-code.webp
   :figclass: align-center
   :alt: Example message from a Long-code Sender ID with instructions to reply STOP to unsubscribe or HELP for assistance.
   :width: 40%

   **Fig. 1.** Example message from a Long-code Sender ID.

Messaging and replies
=====================

Recipients can reply to messages sent from a Long-code Sender ID when two-way messaging is supported. To receive their replies, use a DID number that
supports inbound SMS and assign it to an inbound SMS trunk. Support for replies varies by destination country and mobile network.

Relationship with DID numbers
=============================

A Long-code Sender ID is a DID number assigned to the DIDWW account. Before
including the number in a verification, either
:doc:`purchase the number <../../../phone-numbers/buy-numbers/index>` or
:doc:`port an existing number to DIDWW
<../../../phone-numbers/number-porting/index>`.

The number must be active and available in :doc:`My Numbers <../../../phone-numbers/my-numbers/index>`, and support
**Outbound A2P SMS**. See the :doc:`supported feature filters
<../../../phone-numbers/buy-numbers/filters-reference>`.

A DID number already assigned to another Sender ID Verification cannot be
selected for a new verification.

Availability
============

Long-code Sender ID availability varies by country.

Check current availability on the `DIDWW website <https://www.didww.com/services/two-way-sms/a2p-messaging>`_ or view the available verification options in the `DIDWW User Panel <https://my.didww.com/#/sender_id_verifications/get_started>`_.

Verification requirements
=========================

Each DID number must be included in an approved Long-code verification before use. The verification associates the selected DID numbers with the business, target country, and messaging use case submitted for review.

The Sender ID, business identity, message content, consent process, and and messages sent must meet the requirements of the destination country.

To submit a verification, see :doc:`Create Long-code Sender ID Verification <../how-to-guides/create-long-code-verification>`. For required submission fields, see :ref:`Long-code verification <long_code_verification_reference>`.

US A2P 10DLC registration
=========================

Application-to-person traffic sent to United States recipients using a 10-digit long code requires US A2P 10DLC registration. The registration associates the business, use case, consent process, sample messages, and selected numbers.

The submitted information must match the actual business and messaging use case. Consent must be collected directly for the specific campaign. The sample
messages, website, privacy policy, terms of service, and opt-out process must also describe the same brand and messaging use case.

To register eligible 10-digit long-code DID numbers, see :doc:`Create US 10DLC Verification <../how-to-guides/create-us-10dlc-verification>`. For required US submission fields, see :ref:`United States 10DLC business information fields <us_10dlc_verification_reference_business_information>`.

Using a verified Sender ID
==========================

After the verification becomes :ref:`Active <sender_id_verification_statuses>`, the selected DID numbers can be used as Sender IDs. Associate the verification with an outbound SMS trunk
and send only messages that match the approved business, destination country, and messaging use case.

For sending instructions, see :doc:`Send SMS using verified Sender ID <../how-to-guides/send-sms-using-verified-sender-id>` or the :doc:`HTTP Specification <../../sms-trunks/technical-data/http-specification>`.

Related resources
=================

- :doc:`Create Long-code Sender ID Verification <../how-to-guides/create-long-code-verification>`
- :doc:`Create US 10DLC Verification <../how-to-guides/create-us-10dlc-verification>`
- :doc:`Sender ID Verification reference <../sender-id-verification-reference>`
- :doc:`Sender ID content requirements <../compliance-content-requirements>`
- :doc:`Sender ID types <index>`


.. _toll_free_sender_ids:

=========
Toll-Free
=========

A Toll-Free Sender ID is a US Toll-Free DID number used to send A2P SMS messages. Recipients see the DID number as the message sender. It can also support replies when two-way messaging is available.

Common uses
===========

Use a Toll-Free Sender ID when recipients should see a US Toll-Free number and may need to reply. Common uses include:

- Customer care and support.
- Account and service notifications.
- Delivery and appointment updates.
- Authentication messages.
- Informational and marketing messages that meet the applicable requirements.

How messages appear
===================

Recipients see the approved Toll-Free DID number as the message sender. The same number can provide a consistent sender for customer support, service notifications, and other approved business messages.

.. figure:: https://doc.didww.com/_images/toll-free.webp
   :figclass: align-center
   :alt: Example message from a Toll-Free Sender ID with instructions to reply STOP to unsubscribe or HELP for assistance.
   :width: 40%

   **Fig. 1.** Example message from a Toll-Free Sender ID.

Messaging and replies
=====================

Recipients can reply to messages sent from a Toll-Free Sender ID when two-way messaging is supported. To receive their replies, use a Toll-Free DID number
that supports inbound SMS and assign it to an inbound SMS trunk. Recipients can reply only if their mobile network supports it.

Relationship with DID numbers
=============================

A Toll-Free Sender ID is a US Toll-Free DID number assigned to the DIDWW
account. Before including the number in a verification, either :doc:`purchase it
<../../../phone-numbers/buy-numbers/index>` or :doc:`port an existing number to
DIDWW <../../../phone-numbers/number-porting/index>`.

The number must be active, available in :doc:`My Numbers <../../../phone-numbers/my-numbers/index>`,
and support **Outbound A2P SMS**. See the :doc:`supported feature
filters <../../../phone-numbers/buy-numbers/filters-reference>`.

A DID number already assigned to another Sender ID Verification cannot be
selected for a new verification.

Availability
============

Toll-Free Sender ID availability is limited to the United States.

Check current availability on the `DIDWW website <https://www.didww.com/services/two-way-sms/a2p-messaging>`_ or view the available verification options in the `DIDWW User Panel <https://my.didww.com/#/sender_id_verifications/get_started>`_.

Verification requirements
=========================

Each Toll-Free DID number must be included in an approved verification before use. The submitted business identity, messaging use case, consent process, sample messages, and supporting information must match the messages sent from the number.

Approval does not guarantee message delivery or remove carrier sending limits. You must continue to follow all applicable consent, content, and messaging requirements.

For required submission fields, see :ref:`Toll-Free verification <toll_free_verification_reference>`.

To submit a verification, see :doc:`Create Toll-Free Sender ID Verification <../how-to-guides/create-toll-free-verification>`.

Using a verified Sender ID
==========================

After the verification becomes :ref:`Active <sender_id_verification_statuses>`, the selected Toll-Free DID numbers can be used as Sender IDs. Associate the verification with an outbound
SMS trunk and send only messages that match the approved business and messaging use case.

For sending instructions, see :doc:`Send SMS using verified Sender ID <../how-to-guides/send-sms-using-verified-sender-id>` or the :doc:`HTTP Specification <../../sms-trunks/technical-data/http-specification>`.

Related resources
=================

- :doc:`Create Toll-Free Sender ID Verification <../how-to-guides/create-toll-free-verification>`
- :doc:`Sender ID Verification reference <../sender-id-verification-reference>`
- :doc:`Sender ID content requirements <../compliance-content-requirements>`
- :doc:`Sender ID types <index>`


.. _carrier_sender_ids:

=======
Carrier
=======

A Carrier Sender ID is a dynamic Sender ID selected according to the rules of the destination carrier. The business does not choose or reserve the Sender ID that recipients see.

DIDWW also generates a ``DDWW0xxxxx`` Sender ID for submitting traffic. This value is different from the Sender ID that recipients see.

Common uses
===========

Carrier Sender IDs are commonly used for:

- Authentication messages.
- Account, service, and delivery notifications.
- Messaging to supported Latin American countries.

Use this type when recipients do not need to see a fixed business name or phone number.

How messages appear
===================

The destination carrier determines the Sender ID that recipients see. It may not match the business name or phone numbers in the DIDWW account, and it may change between messages.

.. figure:: https://doc.didww.com/_images/carrier.webp
   :figclass: align-center
   :alt: Example message using a Carrier Sender ID with a link for help or opting out.
   :width: 40%

   **Fig. 1.** Example message using a Carrier Sender ID.

Messaging and replies
=====================

Carrier Sender IDs are intended for one-way messages. Recipients should not be expected to reply to the displayed Sender ID. If recipients must reply to a fixed phone number, use a Long-code or Toll-Free Sender ID.

Relationship with DID numbers
=============================

A Carrier Sender ID is not linked to a DID number in the DIDWW account. You do
not need to purchase, port, or assign a phone number to use this Sender ID
type.

Availability
============

Carrier Sender ID availability varies by country.

View the available verification options in the `DIDWW User Panel <https://my.didww.com/#/sender_id_verifications/get_started>`_.

Verification requirements
=========================

Before using this type, you must have an :ref:`Active <sender_id_verification_statuses>` Carrier Sender ID Verification. The verification links the business and messaging use case to the destination countries submitted for review.

The DIDWW-generated Sender ID is created automatically and cannot be changed.
It is shown as a copyable value on the verification list, view page, and edit
page.

The business identity, message content, consent process, and messages sent must meet the requirements of each destination country.

For required submission fields, see :ref:`Carrier verification <carrier_verification_reference>`.

To submit a verification, see :doc:`Create Carrier Sender ID Verification <../how-to-guides/create-carrier-verification>`.

Using a verified Sender ID
==========================

After the verification becomes :ref:`Active <sender_id_verification_statuses>`, send messages that match the approved business, destination countries, and messaging use case through the associated outbound SMS trunk.

For sending instructions, see :doc:`Send SMS using verified Sender ID <../how-to-guides/send-sms-using-verified-sender-id>` or the :doc:`HTTP Specification <../../sms-trunks/technical-data/http-specification>`.

Related resources
=================

- :doc:`Create Carrier Sender ID Verification <../how-to-guides/create-carrier-verification>`
- :doc:`Sender ID Verification reference <../sender-id-verification-reference>`
- :doc:`Sender ID content requirements <../compliance-content-requirements>`
- :doc:`Sender ID types <index>`


.. _sender_id_verification_reference:

.. |br| raw:: html

   <br />

================================
Sender ID Verification reference
================================

This reference describes the fields and values used for Sender ID Verifications
in the DIDWW User Panel. The fields shown during creation and on the verification
details page depend on the verification type, destination, and status.

General
=======

The following fields and values apply to all Sender ID Verifications.

Filters
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Filter
     - Filter condition
     - Description
   * - Name
     - Contains text input
     - Filters by verification friendly name.
   * - Sender ID
     - Contains text input
     - Filters by Sender ID.
   * - Country
     - Searchable single-select filter
     - Filters by target country.
   * - :ref:`Status <sender_id_verification_statuses>`
     - Searchable single-select filter
     - Filters by verification status.
   * - :ref:`Type <sender_id_verification_type_values>`
     - Searchable single-select filter
     - Filters by Sender ID Verification type.
   * - SMS Trunk
     - Searchable single-select filter
     - Filters by assigned outbound SMS trunk or verifications without an
       assigned SMS trunk.
   * - Identity
     - Searchable single-select filter
     - Filters by assigned business identity.
   * - Address
     - Searchable single-select filter
     - Filters by assigned business address.

Filter conditions
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Filter condition
     - Description
   * - Contains text input
     - Matches values that contain the entered text.
   * - Searchable single-select filter
     - Allows one value to be selected from a searchable list.

.. _sender_id_verification_fields:

Sender ID Verification fields
-----------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Friendly name
     - The account-level name used to identify the verification.
   * - Reference ID
     - The short reference shown below the friendly name on the
       **Verifications** page.
   * - Campaign ID
     - The unique UUID assigned to the verification and shown on its details
       page. In the API, this value is used as ``campaign_id``. See
       :ref:`Outbound SMS examples <sms_out_spec_sending>`.
   * - :ref:`Status <sender_id_verification_statuses>`
     - The current verification status.
   * - Reject reason
     - The reason changes are required.

       .. note::

          This field is shown when the verification status is
          **Changes Required**.
   * - Reject comment
     - Additional information about the changes required for the verification.

       .. note::

          This field is shown when the verification status is
          **Changes Required**.
   * - :ref:`Type <sender_id_verification_type_values>`
     - The Sender ID Verification type.
   * - Target countries
     - The destination countries covered by the verification.
   * - SMS Trunk
     - The outbound SMS trunk associated with the verification. When no SMS
       trunk is assigned, the **Verifications** page shows **SMS: none** and the
       verification details page shows a dash.
   * - Identity (Business)
     - The business identity assigned to the verification.
   * - Address
     - The business address assigned to the verification.
   * - Sender IDs
     - The Sender IDs covered by the verification. For Carrier verifications,
       this is the immutable, system-generated value in the ``DDWW0xxxxx``
       format, not the dynamic Sender ID presented to the recipient.
   * - Next billing price
     - The next verification charge. This field is shown before an approved
       verification has a renewal price.
   * - Renew price
     - The recurring price for an active verification.
   * - Renew date
     - The next scheduled renewal date. A dash is shown when no renewal date is
       scheduled.
   * - Order ref
     - The order reference associated with an active verification, shown as a
       link to the order.

.. _sender_id_verification_type_values:

Verification type values
------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Type
     - Description
   * - Alphanumeric
     - Verifies a Sender ID containing letters and numbers.
   * - Long-code
     - Verifies one or more active Long-code DID numbers for A2P SMS.
   * - Toll-Free
     - Verifies one or more active US Toll-Free DID numbers for A2P SMS.
   * - Carrier (Dynamic)
     - Verifies messaging traffic for a supported country. The recipient-facing
       Sender ID is assigned dynamically by the destination carrier. DIDWW also
       generates an immutable Sender ID for submitting traffic.

.. _sender_id_verification_statuses:

Status values
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - New
     - The verification has been created, but its review has not started.
   * - In Process
     - The submitted verification is being reviewed.
   * - Active
     - The verification is approved and can be used for the approved business, destination countries, and messaging purpose.
   * - Changes Required
     - The verification requires changes or additional information before review can continue.
   * - Pending Closure
     - Closure has been requested and is being processed.
   * - Closed
     - The verification is closed and can no longer be used to send messages.

.. _sender_id_use_case_type_values:

Use case type values
--------------------

The use case type identifies the general purpose of the messages. Available
values may depend on the verification type and destination country.

For US 10DLC registration, use cases are grouped into standard and special use
cases.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Standard use cases

      Select from the following standard use cases. These are common message
      categories that typically do not require additional MNO vetting:

      .. list-table::
         :header-rows: 1
         :widths: 20 80
         :width: 100%

         * - Value
           - Description
         * - 2FA (OTP)
           - Authentication and one-time passcodes.
         * - Account Notification
           - Account updates, billing notices, and password reset messages.
         * - Customer Care
           - Customer service and support messages.
         * - Delivery Notification
           - Notifications about delivery status.
         * - Fraud Alert Messaging
           - Fraud or suspicious activity alerts.
         * - Higher Education
           - Messages from colleges, universities, and other educational institutions.
         * - Low Volume Mixed
           - Low-volume messages that cover more than one use case.
         * - Machine to Machine (M2M)
           - Automated communication between devices or systems without a human recipient.
         * - Marketing
           - Promotional and marketing content.
         * - Mixed
           - Messages that cover more than one standard use case.
         * - Polling and Voting
           - Interactive campaigns such as polls or surveys.
         * - Public Service Announcement
           - Government or civic alerts.
         * - Security Alert
           - Alerts for system or user security.

   .. tab-item:: Special use cases

      Special Use Cases are sensitive and may require pre/post-registration
      approval by mobile network operators (MNOs). Requirements vary depending
      on the carrier.

      .. list-table::
         :header-rows: 1
         :widths: 20 80
         :width: 100%

         * - Value
           - Description
         * - Charity
           - Non-profit organizations sending donation-related messages.
         * - Emergency
           - Critical public safety or health notifications.
         * - Social
           - Messages from social platforms or apps.

----

.. _alphanumeric_verification_reference:

Alphanumeric verification
=========================

An Alphanumeric Sender ID Verification registers a Sender ID containing letters
and numbers for the selected target countries. The information requested during
creation can vary according to the selected countries and their identity
requirements.

.. _alphanumeric_verification_reference_setup_fields:

Verification setup fields
-------------------------

These fields are shown in the **General** step when creating an Alphanumeric
Sender ID Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Friendly name
     - The account-level name used to identify the verification.
   * - Target countries
     - A predefined country group for which the Sender ID is being verified.
       Selecting any country in a group selects the entire group; countries
       cannot be added or removed individually, and groups cannot be
       combined. Pricing and Identity Requirements apply once to the whole
       group.
   * - Sender ID
     - The Alphanumeric Sender ID being verified. The value must contain 2 to
       11 characters and can use ``a-z``, ``A-Z``, and ``0-9``.
   * - Identity (Business)
     - The business identity assigned to the verification.
   * - Address
     - The business address assigned to the verification.

.. _alphanumeric_verification_reference_business_information:

Verification details fields
---------------------------

These fields are shown in the **Verification details** step when creating an
Alphanumeric Sender ID Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Legal Company Name
     - The legal name of the business that will use the Sender ID.
   * - Website
     - The website associated with the business and messaging use case.
   * - :ref:`Use case type <sender_id_use_case_type_values>`
     - The category that best describes the messages sent with the Sender ID.
   * - Campaign description
     - A specific description of the messaging purpose and content.
   * - How will consumers opt in?
     - A description of the complete consumer opt-in flow or the script used by
       an agent to obtain consent.
   * - Sample content messages #1
     - A representative example of the messages that will be sent.
   * - Sample content messages #2
     - A second representative example of the messages that will be sent.

----

.. _long_code_verification_reference:

Long-code verification
======================

A Long-code Sender ID Verification registers eligible DID numbers for A2P SMS
in the selected target countries. An active eligible DID number is required in
each selected country.

Verification setup fields
-------------------------

These fields are shown in the **General** step when creating a Long-code Sender
ID Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Friendly name
     - The account-level name used to identify the verification.
   * - Target countries
     - The destinations for which the Sender IDs are being verified.
   * - Identity (Business)
     - The business identity assigned to the verification.
   * - Address
     - The business address assigned to the verification.

Sender ID selection fields
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75
   :width: 100%

   * - Field
     - Description
   * - Available source numbers
     - Active DID numbers that support **Outbound A2P SMS**, are compatible
       with the selected business identity, and are not assigned to another
       Sender ID Verification.
   * - Allowed source addresses
     - The DID numbers selected for this verification.

.. _long_code_verification_reference_business_information:

Standard verification details fields
------------------------------------

These fields are shown in the **Verification details** step when the selected
target country does not require a country-specific form.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Legal Company Name
     - The legal name of the business that will use the Sender IDs.
   * - Website
     - The website associated with the business and messaging use case.
   * - :ref:`Use case type <sender_id_use_case_type_values>`
     - The category that best describes the messages sent with the Sender IDs.
   * - Campaign description
     - A specific description of the messaging purpose and content.
   * - How will consumers opt in?
     - A description of the complete consumer opt-in flow or the script used by
       an agent to obtain consent.
   * - Sample content messages #1
     - A representative example of the messages that will be sent.
   * - Sample content messages #2
     - A second representative example of the messages that will be sent.

----

.. _us_10dlc_verification_reference_business_information:

United States 10DLC verification details fields
-----------------------------------------------

These fields are shown in the **Verification details** step when **United
States** is selected as the target country. They collect the business and
campaign information required for US A2P 10DLC registration.

.. list-table::
   :header-rows: 1
   :widths: 20 35 45
   :width: 100%

   * - Field
     - Example
     - Description
   * - Legal Company Name
     - ``DIDWW``
     - Enter the full legal name of the company.
   * - DBA (Doing Business As) or Brand Name
     - ``DIDWW``
     - Enter the brand name if it differs from the legal name.
   * - Business entity type
     - ``Private Company``
     - Choose the legal structure of the entity (e.g., Private Company,
       Charity/Non-profit Organization, Publicly Traded Company).
   * - Stock symbol (if applicable)
     - ``AAPL``
     - If the company is publicly listed, provide the stock ticker symbol.
   * - Stock exchange (if applicable)
     - ``NASDAQ``
     - If the company is publicly listed, provide the stock exchange.
   * - Vertical type
     - ``Retail``, ``Financial Services``, or ``Healthcare``
     - Select the business category that best describes your organization
       (e.g., Retail, Financial Services, Healthcare).
   * - Website
     - ``https://didww.com``
     - Enter the business website. All links must include the full URL starting
       with ``https://`` or ``http://``.
   * - :ref:`Use case type <sender_id_use_case_type_values>`
     - ``Account Notification``
     - Account status updates, password resets.
   * - Campaign description
     - **Billing Notifications** |br| **Objective**: Notify users about billing
       events. |br| **Content**: Monthly statements, due date alerts, and
       payment confirmations. |br| **Audience**: Customers with active DIDWW
       services.
     - Provide a concise summary of the campaign. This should outline the
       campaign's primary objectives, the type of message content that will be
       sent, and the intended target audience.
   * - How will customers opt in?
     - **Through my website**, **Through my app**, **Verbal agreement**, or
       **Physical form**
     - Select one or more methods used to obtain consent.
   * - Provide screenshots or scans of the opt-in form
     - ``opt-in-form.png``
     - Upload supporting files when **Through my app** or **Physical form** is
       selected. Multiple files can be attached.
   * - Detailed opt-in flow description
     - **Checkout Page Consent** |br| During checkout on an e-commerce
       platform, customers are shown a checkbox with the label: |br| **Yes, I
       want to receive order updates and special offers via SMS (4
       messages/month).** |br| The box is unchecked by default and must be
       selected manually to opt in.
     - Describe each step of the opt-in process or provide the exact script
       used by an agent to obtain consent. Include the channel, wording, and
       confirmation step.
   * - I confirm that my opt-in flow requires mandatory, manual user confirmation to receive messages based on the campaign and allows users to freely opt out.
     - Selected
     - This confirmation is required before the verification can be submitted.
   * - Opt-In Keywords
     - ``START``, ``JOIN``, or ``SUBSCRIBE``
     - Specify acceptable keywords.
   * - Opt-In Message
     - ``Welcome to DIDWW``
     - Include an acknowledgement that the user accepted an invitation, the
       brand name, message frequency disclosure, the standard **Message and
       Data Rates May Apply** disclaimer, and STOP and HELP instructions.
   * - Opt-Out Keywords
     - ``STOP``, ``CANCEL``, or ``UNSUBSCRIBE``
     - Common unsubscribe terms that subscribers can use to leave the campaign
       at any time.
   * - Opt-Out Message
     - ``You have been unsubscribed from DIDWW alerts``
     - Include the brand name, acknowledgement of the opt-out, and confirmation
       that no further messages will be sent.
   * - Help Keywords
     - ``HELP``, ``INFO``, or ``SUPPORT``
     - Standard terms that subscribers can use to receive assistance.
   * - Help Message
     - ``DIDWW: Contact support at support@didww.com. Message and data rates may
       apply.``
     - Include the brand name, support contact details, and a statement that
       standard messaging rates may apply.
   * - Sample content messages #1
     - **DIDWW:** |br| Your monthly billing statement is now available. Log in
       at `didww.com <https://didww.com>`_ to view. |br| Messages & Data rates
       may apply. |br| Reply **HELP** to get help, reply **STOP** to opt-out of
       the messaging campaign.
     - Provide an example that reflects the type of SMS content your campaign
       will send. The message must include the brand name, representative
       message content, and opt-out and help instructions.
   * - Sample content messages #2
     - **DIDWW Alert:** |br| Your porting request has been received. You’ll
       receive an update within 24 hrs. |br| Messages & Data rates may apply.
       |br| Reply **HELP** to get help, reply **STOP** to opt-out of the
       messaging campaign.
     - Provide a second example that reflects the type of SMS content your
       campaign will send. The message must include the brand name,
       representative message content, and opt-out and help instructions.
   * - URLs included in messages
     - ``https://didww.com``
     - List the URLs included in SMS content. All URLs must include the full URL
       starting with ``https://`` or ``http://``.
   * - Phone numbers included in messages
     - ``+1 212 555 0100``
     - List the clickable or static phone numbers included in SMS content.
   * - Link to privacy policy
     - ``https://didww.com/privacy-policy``
     - Provide a direct URL to the privacy policy. The privacy policy must
       explicitly state that subscriber data will not be sold or shared with
       third parties.
   * - Link to Terms and conditions
     - ``https://didww.com/terms-and-conditions``
     - Provide a direct URL to the terms and conditions. The link must include
       the full URL starting with ``https://`` or ``http://``.

.. note::

   For US A2P 10DLC registration, the business or brand name must appear in the
   opt-in, opt-out, help, and sample messages. The opt-in message must also
   disclose the message frequency, applicable message and data rates, and HELP
   and STOP instructions.

----

.. _toll_free_verification_reference:

Toll-Free verification
======================

A Toll-Free Sender ID Verification registers an eligible US Toll-Free DID
number for A2P SMS. An active US Toll-Free DID number is required on the DIDWW
account.

Verification setup fields
-------------------------

These fields are shown in the **General** step when creating a Toll-Free Sender
ID Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Friendly name
     - The account-level name used to identify the verification.
   * - Identity (Business)
     - The business identity assigned to the verification.
   * - Address
     - The business address assigned to the verification.

Sender ID selection fields
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75
   :width: 100%

   * - Field
     - Description
   * - Available source numbers
     - Active DID numbers that support **Outbound A2P SMS**, are compatible
       with the selected business identity, and are not assigned to another
       Sender ID Verification.
   * - Allowed source addresses
     - The DID numbers selected for this verification.

.. _toll_free_verification_reference_business_information:

Verification details fields
---------------------------

These fields are shown in the **Verification details** step when creating a
Toll-Free Sender ID Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Business Registration Number
     - The Employer Identification Number (EIN) for a business registered in
       the United States, or the government-issued business registration number
       for a business registered outside the United States.
   * - Legal Company Name
     - The legal name of the business that will use the Toll-Free Sender ID.
   * - :ref:`Business entity type <sender_id_business_entity_type_values>`
     - The legal classification of the business.
   * - Business registration type
     - The type of registration number entered for the business.
   * - Website
     - The complete website URL associated with the business and messaging use
       case, including the ``https://`` or ``http://`` prefix.
   * - Fortune 500 or 1000 company?
     - Indicates whether the business is listed in the Fortune 500 or Fortune
       1000.
   * - :ref:`Use case type <sender_id_use_case_type_values>`
     - The category that best describes the messages sent with the Toll-Free
       Sender ID.
   * - Campaign description
     - A specific description of the messaging purpose and content.
   * - How will customers opt in?
     - One or more consent methods: **Through my website**, **Through my app**,
       **Verbal agreement**, or **Physical form**.
   * - Provide screenshots or scans of the opt-in form
     - Supporting files for the opt-in process. This field is shown when
       **Through my app** or **Physical form** is selected, and accepts multiple
       attachments.
   * - Detailed opt-in flow description
     - A step-by-step description of the opt-in process or the exact script
       used by an agent to obtain consent. Include the channel, wording, and
       confirmation step.
   * - I confirm that my opt-in flow requires mandatory, manual user confirmation to receive messages based on the campaign and allows users to freely opt out.
     - Confirms that consent requires a manual action and that recipients can
       opt out. This checkbox is required before submission.
   * - Sample content messages #1
     - A representative message containing the business or brand name, expected
       message content, and applicable HELP and STOP wording.
   * - Sample content messages #2
     - A second representative message containing the business or brand name,
       expected message content, and applicable HELP and STOP wording.
   * - URLs included in messages
     - All URLs expected to appear in messages sent under the verification.
       Listing these URLs helps prevent message blocking.
   * - Phone numbers included in messages
     - All phone numbers expected to appear in messages sent under the
       verification. Listing these numbers helps prevent message blocking.
   * - Description
     - A description of where customers can find the Toll-Free numbers, such as
       the business website, online advertisements, or application store
       listings.
   * - Screenshots (optional)
     - Supporting screenshots showing where the Toll-Free numbers are
       published.
   * - Message volume type
     - Indicates whether the monthly message volume is existing or projected.
   * - Estimated quantity
     - The estimated total number of messages sent each month.
   * - Promotes commercial product?
     - Indicates whether the messages promote a commercial product. Available
       values are **Yes**, **No**, and **Unsure**.
   * - Was this traffic previously on another messaging service?
     - Indicates whether the messages are new or were previously sent through
       another messaging provider.
   * - Previous content copy
     - Representative messages, including HELP and STOP wording, used with the
       previous provider. Shown when the traffic was previously sent using a
       short code or long number.
   * - Number(s) used with previous vendor
     - The sending numbers used with the previous provider. Shown when the
       traffic was previously sent using a short code or long number.
   * - Link to privacy policy
     - The complete URL of the business privacy policy, including the
       ``https://`` or ``http://`` prefix.
   * - Link to Terms and conditions
     - The complete URL of the terms and conditions that apply to the messaging
       service, including the ``https://`` or ``http://`` prefix.

.. _sender_id_business_entity_type_values:

Business entity type values
---------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Value
     - Description
   * - Private Profit
     - A privately owned for-profit business.
   * - Public Profit
     - A publicly traded for-profit business.
   * - Non Profit
     - A nonprofit organization.
   * - Government
     - A government organization.
   * - Sole Proprietor
     - A business owned and operated by one individual.

----

.. _carrier_verification_reference:

Carrier verification
====================

A Carrier Sender ID Verification approves a business and its messaging use
case for supported destinations where the Sender ID is assigned dynamically.
You do not select or enter a Sender ID. The destination carrier assigns it when
the SMS message is delivered.

Verification setup fields
-------------------------

These fields are shown in the **General** step when creating a Carrier Sender ID
Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Friendly name
     - The account-level name used to identify the verification.
   * - Target countries
     - A predefined country group for which the messaging traffic is being
       verified. Selecting any country in a group selects the entire group;
       countries cannot be added or removed individually, and groups cannot
       be combined. Pricing and Identity Requirements apply once to the whole
       group.
   * - Identity (Business)
     - The business identity assigned to the verification.
   * - Address
     - The business address assigned to the verification.

.. _carrier_verification_reference_business_information:

Verification details fields
---------------------------

These fields are shown in the **Verification details** step when creating a
Carrier Sender ID Verification.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Legal Company Name
     - The legal name of the business that will send the messages.
   * - Website
     - The website associated with the business and messaging use case.
   * - :ref:`Use case type <sender_id_use_case_type_values>`
     - The category that best describes the messages that will be sent.
   * - Campaign description
     - A specific description of the messaging purpose and content.
   * - How will consumers opt in?
     - A description of the complete consumer opt-in flow or the script used by
       an agent to obtain consent.
   * - Sample content messages #1
     - A representative example of the messages that will be sent.
   * - Sample content messages #2
     - A second representative example of the messages that will be sent.

Related resources
=================

- :doc:`How Sender ID Verification works <how-sender-id-verification-works>`
- :doc:`Sender ID types <sender-id-verification-types/index>`
- :doc:`Sender ID Verification how-to guides <how-to-guides/index>`
- :doc:`Sender ID content requirements <compliance-content-requirements>`


.. |br| raw:: html

  <br>

.. _user_panel_sms_smpp_esme:
.. _sms_esme:

=================
SMPP ESME Trunk
=================

An SMPP ESME (External Short Messaging Entity) trunk lets your application connect directly to the DIDWW SMSC (Short Message Service Center) to send and receive SMS. This provides a fast, reliable solution for real-time application-to-person (A2P) messaging. Two-way communication is supported when you assign one or more DIDs with inbound SMS to the SMPP ESME trunk.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Trunk**
      :link: user_panel_sms_smpp_esme_create
      :link-type: ref
      :text-align: center

      Create and configure a new SMPP ESME Trunk.

   .. grid-item-card:: :octicon:`key` **View or Regenerate Credentials**
      :link: user_panel_sms_smpp_esme_credentials
      :link-type: ref
      :text-align: center

      Access or update your System ID and password.

   .. grid-item-card:: :octicon:`link` **Bind SMPP ESME Trunk**
      :link: user_panel_sms_smpp_esme_bind
      :link-type: ref
      :text-align: center

      Connect your application using the trunk credentials.

   .. grid-item-card:: :octicon:`pencil` **Edit Trunk**
      :link: user_panel_sms_smpp_esme_edit
      :link-type: ref
      :text-align: center

      Update the settings of an existing trunk.

   .. grid-item-card:: :octicon:`trash` **Delete Trunk(s)**
      :link: user_panel_sms_smpp_esme_delete
      :link-type: ref
      :text-align: center

      Remove one or more trunks from your account.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_esme_create:

Create SMPP ESME Trunk
======================

Step 1: Start Creating SMPP ESME Trunk
----------------------------------------

In the user panel menu, navigate to **SMS > SMS Trunks**. Click the **Create New** button and select **SMPP ESME** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Navigating to create a new SMPP ESME Trunk.
   :width: 100%

   **Fig. 1.** Navigating to create a new SMPP ESME Trunk.

.. raw:: html

    <br>

Step 2: Configure SMPP ESME Trunk
----------------------------------

Enter the general information required to configure your SMPP ESME trunk. Provide a unique friendly name, specify which IP addresses are authorized to connect, and optionally define a system type to categorize your ESME binding.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: The Create SMPP ESME Trunk configuration page.
   :width: 100%

   **Fig. 2.** The SMPP ESME Trunk configuration page.

General Settings
^^^^^^^^^^^^^^^^

    .. list-table::
       :widths: 15 65
       :header-rows: 1

       * - Setting
         - Description
       * - **Friendly name**
         - A unique name to identify this trunk.
       * - **Allowed IP addresses**
         - IP addresses from which access to the API is allowed in the format (IPv4|IPv6)[/mask] (not mandatory). |br| Allow all IP addresses if empty.
       * - **System type**
         - The system_type parameter is used to categorize the type of ESME that is binding to the SMSC. |br| Examples include “VMS” (voice mail system) and “OTA” (over-the-air activation system).

.. raw:: html

    <br>

Source Address Settings
^^^^^^^^^^^^^^^^^^^^^^^

The **Source Address Settings** section controls which DID numbers can be used as the sender ID for outbound SMS.

Use the **Allow any DID(s) for SMS OUT** toggle to choose how sender IDs are assigned:

    - **Toggle on (default):** All DIDs with Outbound P2P SMS enabled in your account can be used as the sender ID.
    - **Toggle off:** You can specify which DIDs are allowed. To do this, select numbers from the **Available Source Addresses** list and add them to the **Allowed Source Addresses** list. Only the numbers you add will be available as sender IDs.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Selecting and allowing specific DIDs to be used as source addresses.
   :width: 100%

   **Fig. 3.** Authorizing specific DIDs as sender IDs.

.. note::
   When the **Allow any DID(s) for SMS OUT** toggle is turned off, the **Available Sender IDs** list shows only DIDs that support outbound P2P SMS.

.. raw:: html

    <br>

Trunk Group Configuration (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You may assign the trunk to an existing trunk group in order to enable failover or load-balancing. Within the trunk group, you can also define the trunk’s **priority**, which determines the order in which trunks will be used.

.. note:: The system attempts to contact the target SMS trunk with the highest-numbered priority first.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Trunk Group configuration section for SMPP ESME Trunk.
   :width: 100%

   **Fig. 4.** Trunk Group configuration section for SMPP ESME Trunk.

.. raw:: html

    <br>

Step 3: Create the SMPP ESME Trunk
------------------------------------

Once you have entered all required fields, click **Create** at the bottom of the page to save the new trunk. The trunk credentials (System ID, Password, Host, and Port) will then be available for you to use when binding your application to the DIDWW SMSC.

.. note:: For detailed instructions on how to connect, see :ref:`Bind SMPP ESME Trunk <user_panel_sms_smpp_esme_bind>`.

.. raw:: html

    <br>

Step 4: Assign the SMPP ESME Trunk to DIDs (Inbound SMS Only)
-------------------------------------------------------------

.. note::
   You only need to assign DIDs if you want to receive inbound SMS. For outbound SMS, DID assignment is not required.

To receive SMS on this trunk, assign one or more DIDs that support inbound SMS. Messages sent to those DIDs are then delivered to your SMPP connection. For detailed steps, see :ref:`Assign an SMS trunk <assigning-sms-trunk>`.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_esme_credentials:

View or Regenerate Credentials
==============================

    1.  Navigate to **SMS > SMS Trunks** in the user panel.
    2.  Locate the SMPP ESME trunk.
    3.  Click the |credentials| key icon in the **Credentials** column to open the credentials window.

.. figure:: https://doc.didww.com/_images/credentials_button.png
   :figclass: align-center
   :alt: The credentials button in the SMS Trunks list.

   **Fig. 5.** Credentials button.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *View Credentials*

      In the credentials pop-up window, you can view the SMPP ESME connection details. Click the **eye** icon to show the password.

      .. figure:: https://doc.didww.com/_images/credentials.png
         :figclass: align-center
         :alt: Viewing credentials for an SMPP ESME Trunk.

         **Fig. 6.** Viewing credentials.

   .. tab-item:: *Regenerate Credentials*

      .. important::
            The password is updated immediately when you regenerate credentials. Update all integrations right away to avoid authentication failures.

      1. In the credentials pop-up window, click **Regenerate** next to the **Password** field to generate new credentials.
      2. Copy the new **System ID** and **Password**, and update all systems that use these credentials.

      .. figure:: https://doc.didww.com/_images/credentials-regenerate.png
         :figclass: align-center
         :alt: Regenerating the password for an SMPP ESME Trunk.

         **Fig. 7.** Regenerating credentials.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_esme_bind:

Bind SMPP ESME Trunk
==========================

Configure your application to connect (or "bind") to the DIDWW SMSC gateway using the credentials of your SMPP ESME trunk.

.. raw:: html

    <br>

Before You Begin
-----------------

 1. Make sure you have an SMPP ESME trunk configured in the DIDWW User Panel. If you don’t have one yet, see instruction in :ref:`Create an SMPP ESME Trunk <user_panel_sms_smpp_esme_create>`.
 2. Have the trunk’s credentials ready (Host, Port, System ID, Password, and System Type).

.. raw:: html

    <br>

Mandatory SMPP ESME Bind Parameters
-----------------------------------

    .. list-table::
       :widths: 25 75
       :header-rows: 1

       * - Parameter
         - Value
       * - **host**
         - ``us.sms-out.didww.com`` (:ref:`SMPP endpoint list <smpp_outbound_sms_endpoints>`)
       * - **port**
         - ``2775``
       * - **system_id**
         - The **System ID** from the trunk's :ref:`Credentials <user_panel_sms_smpp_esme_credentials>`.
       * - **password**
         - The **Password** from the trunk's :ref:`Credentials <user_panel_sms_smpp_esme_credentials>`.
       * - **system_type**
         - The value you defined in the trunk's **System type** field.

.. note::
       For complete technical details, including encoding, concatenated messages, and all available endpoints, refer to our :ref:`SMPP Specifications <service_incoming_sms>` guide.

.. raw:: html

    <br>

Check SMPP ESME Bind Status
----------------------------------

After configuring your application to bind, you can verify the connection status directly from the user panel:

    1.  Navigate to the **SMS > SMS Trunks** list page.
    2.  Locate the trunk and click the |actions| button next to it.
    3.  Select **Check Status** from the dropdown menu.

A pop-up will display the current connection status of your trunk (e.g., "Connected" or "Not Connected").

.. figure:: https://doc.didww.com/_images/check_status.png
   :figclass: align-center
   :alt: Check bind status button.
   :width: 100%

   **Fig. 8.** Check bind status button.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_esme_edit:

Edit SMPP ESME Trunk
====================

    1.  In the user panel menu, navigate to **SMS > SMS Trunks**.
    2.  Locate the trunk you wish to edit and click the |actions| button next to it.
    3.  Select **Edit** from the dropdown menu.
    4.  On the **Edit SMPP ESME Trunk** page, modify the settings as needed.
    5.  Click **Save** to apply your changes.

.. figure:: https://doc.didww.com/_images/fig_actions_edit.png
   :figclass: align-center
   :alt: Edit action for SMPP ESME Trunk.
   :width: 100%

   **Fig. 9.** Edit action for SMPP ESME Trunk.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_esme_delete:

Delete SMPP ESME Trunk(s)
=========================

You can delete a single SMPP ESME trunk or multiple trunks at once by using batch actions.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Delete a Single Trunk*

      1.  Navigate to the **SMS Trunks** list page.
      2.  Locate the trunk you wish to remove and click the |actions| button next to it.
      3.  Select **Delete** from the dropdown menu.
      4.  In the confirmation pop-up window, click **Delete** to permanently remove the trunk.

      .. figure:: https://doc.didww.com/_images/fig9.png
          :figclass: align-center
          :alt: Delete action for SMPP ESME Trunk.
          :width: 100%

          **Fig. 10.** Delete action for SMPP ESME Trunk.

   .. tab-item:: *Delete Multiple Trunks*

      1.  Navigate to the **SMS Trunks** list page.
      2.  Select the trunks you wish to delete by checking the boxes next to them.
      3.  At the bottom of the page, click **Batch Actions** and select **Delete Trunks**.
      4.  In the confirmation pop-up window, click **Delete** to permanently remove the selected trunks.

      .. figure:: https://doc.didww.com/_images/fig10.png
         :figclass: align-center
         :alt: Batch delete action for SMPP ESME Trunks.

         **Fig. 11.** Batch delete action for SMPP ESME Trunks.

----

.. raw:: html

    <br>

Related Resources
======================

.. card:: **SMPP Specification**
   :link: service_incoming_sms
   :link-type: ref

   Review detailed protocol information, including encoding, concatenation, and all available DIDWW endpoints.

.. card:: **Assign an SMS trunk**
    :link: assigning-sms-trunk
    :link-type: ref

    Learn how to assign your newly created trunk to one or more DID numbers to start receiving messages.

.. card:: **Sender ID Verifications**
   :link: user_panel_sms_campaign
   :link-type: ref

   Register sender IDs for Application-to-Person (A2P) messaging.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button

.. |credentials| image:: /img/new_user_panel/trunks/sms/smpp_esme/key.png
   :class: inline-img no-shadow
   :width: 24px
   :height: 24px
   :alt: Credentials button


.. |br| raw:: html

  <br>

.. _user_panel_sms_smpp_smsc:
.. _sms_smsc:

=================
SMPP SMSC Trunk
=================

SMPP SMSC (Short Message Service Center) trunks let the DIDWW system act as an ESME (External Short Messaging Entity) and connect to your SMSC server or application. This setup is mainly used to receive inbound SMS, but it also supports outbound delivery for two-way communication.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Trunk**
      :link: user_panel_sms_smpp_smsc_create
      :link-type: ref
      :text-align: center

      Create and configure a new SMPP SMSC Trunk.

   .. grid-item-card:: :octicon:`key` **View Credentials**
      :link: user_panel_sms_smpp_smsc_credentials
      :link-type: ref
      :text-align: center

      View the configured System ID, password, host, and other details for your SMPP SMSC trunk.

   .. grid-item-card:: :octicon:`server` **Accept SMPP Bind Requests**
      :link: user_panel_sms_smpp_smsc_bind
      :link-type: ref
      :text-align: center

      Configure your server to accept bind requests and verify the bind status.

   .. grid-item-card:: :octicon:`pencil` **Edit Trunk**
      :link: user_panel_sms_smpp_smsc_edit
      :link-type: ref
      :text-align: center

      Update the settings of an existing trunk.

   .. grid-item-card:: :octicon:`trash` **Delete Trunk(s)**
      :link: user_panel_sms_smpp_smsc_delete
      :link-type: ref
      :text-align: center

      Remove one or more trunks from your account.

----

.. _user_panel_sms_smpp_smsc_create:

Create SMPP SMSC Trunk
======================

Step 1: Start Creating SMPP SMSC Trunk
---------------------------------------

In the user panel menu, navigate to **SMS > SMS Trunks**. Click the **Create New** button and select **SMPP SMSC** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Navigating to create a new SMPP SMSC Trunk.
   :width: 100%

   **Fig. 1.** Navigating to create a new SMPP SMSC Trunk.

.. raw:: html

    <br>

Step 2: Configure SMPP SMSC Trunk
---------------------------------

Enter the general information required to configure your SMPP SMSC trunk. Provide a unique friendly name, specify which IP addresses are authorized to connect, and optionally define a system type to categorize your ESME binding.

General Settings
^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 15 75
   :header-rows: 1

   * - Setting
     - Description
   * - **Friendly name**
     - A unique name to identify this trunk.
   * - **Password**
     - A secure value used by the SMSC to authenticate the ESME during bind.
   * - **Host**
     - The public hostname or IP address of your SMPP server.
   * - **TX port**
     - Transmitter Port (when Transceiver Mode turned off) or Transceiver Port (when Transceiver Mode turned on).
   * - **RX port**
     - Receiver Port is ignored when Transceiver Mode turned off.
   * - **System type**
     - An optional parameter that categorizes the ESME binding |br| (e.g., “VMS” for voice mail system or “OTA” for over-the-air activation system).
   * - **System ID**
     - Identifies the ESME to the SMSC at bind process. Used for authentication and to label the entity in the connection.
   * - **Use SSL**
     - SSL encryption for the SMPP connection.
   * - **Connection timeout**
     - Timeout between TCP Connection retries (seconds).
   * - **Transceiver mode**
     - Defines how messages are exchanged between the ESME and the SMSC. |br|

        - Off (default): The trunk uses separate **Transmitter** (TX) and **Receiver** (RX) connections. |br|
        - On: Combines both into a single **Transceiver** connection for two-way communication, using only the **TX port**.

       .. tip::
           - Leave this **off** if your system uses separate Transmitter and Receiver connections.
           - Turn it **on** if your system supports a single Transceiver connection.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: The Create SMPP SMSC Trunk configuration page.
   :width: 100%

   **Fig. 2.** The SMPP SMSC Trunk configuration page.

Source Address Settings
^^^^^^^^^^^^^^^^^^^^^^^

The **Source Address Settings** section controls which DID numbers can be used as the sender ID for outbound SMS.

Use the **Allow any DID(s) for SMS OUT** toggle to choose how sender IDs are assigned:

    - **Toggle on (default):** All DIDs with Outbound P2P SMS enabled in your account can be used as the sender ID.
    - **Toggle off:** You can specify which DIDs are allowed. To do this, select numbers from the **Available Source Addresses** list and add them to the **Allowed Source Addresses** list. Only the numbers you add will be available as sender IDs.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Selecting and allowing specific DIDs to be used as source addresses.
   :width: 100%

   **Fig. 3.** Authorizing specific DIDs as sender IDs.

.. note::
   When the **Allow any DID(s) for SMS OUT** toggle is turned off, the **Available Sender IDs** list shows only DIDs that support outbound P2P SMS.

.. raw:: html

    <br>

Trunk Group Configuration (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You may assign the trunk to an existing trunk group in order to enable failover or load-balancing. Within the trunk group, you can also define the trunk’s **priority**, which determines the order in which trunks will be used.

.. note:: The system attempts to contact the target SMS trunk with the highest-numbered priority first.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Trunk Group configuration section for SMPP SMSC Trunk.
   :width: 100%

   **Fig. 4.** Trunk Group configuration section for SMPP SMSC Trunk.

.. raw:: html

    <br>

Step 3: Create the SMPP SMSC Trunk
------------------------------------

Once you have entered all required fields, click **Create** at the bottom of the page to save the new trunk. DIDWW will then use the credentials and server details you provided to initiate the bind process to your SMSC.

.. note::

   After you create an SMPP SMSC trunk with valid details, DIDWW automatically starts the bind process. |br|
   Make sure your server is ready to accept connections by:

       - Running an SMPP service that can accept external bind requests.
       - Allowing inbound traffic from all DIDWW SMPP server :ref:`endpoints <smpp_outbound_sms_endpoints>`.

   To confirm the connection, see :ref:`Check SMPP SMSC Bind Status <user_panel_sms_smpp_smsc_status>`. |br|
   For complete technical details about the protocol, encoding, and supported features, see the :ref:`SMPP Specifications <service_incoming_sms>` guide.

.. raw:: html

    <br>

Step 4: Assign the SMPP SMSC Trunk to DIDs (Inbound SMS Only)
------------------------------------------------------------------------

.. note::
   You only need to assign DIDs if you want to receive inbound SMS. For outbound SMS, DID assignment is not required.

To receive SMS on this trunk, assign one or more DIDs that support inbound SMS. Messages sent to those DIDs are then delivered to your SMPP connection. For detailed steps, see :ref:`Assign an SMS trunk <assigning-sms-trunk>`.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_smsc_credentials:

View Credentials
================

    1.  Navigate to **SMS > SMS Trunks** in the user panel.
    2.  Locate the SMPP SMSC trunk.
    3.  Click the |credentials| key icon in the **Credentials** column to open the credentials window.

.. figure:: https://doc.didww.com/_images/credentials_button.png
   :figclass: align-center
   :alt: The credentials button in the SMS Trunks list.

   **Fig. 5.** Credentials button.

----

.. raw:: html

    <br>

.. _user_panel_sms_smpp_smsc_bind:

Accept SMPP Bind Requests from DIDWW
====================================

Configure your server to accept incoming SMPP bind requests from DIDWW, which connects to your SMSC as an ESME using the credentials you defined in the trunk.

.. raw:: html

    <br>

Before You Begin
----------------

    1. Make sure you have an SMPP SMSC trunk configured in the DIDWW User Panel. If you don’t have one yet, see :ref:`Create an SMPP SMSC Trunk <user_panel_sms_smpp_smsc_create>`.
    2. Verify your server is running an SMPP service capable of accepting external bind requests.
    3. Configure your firewall to allow inbound connections from all DIDWW SMPP server :ref:`endpoints <smpp_outbound_sms_endpoints>`.

.. note::
   - After the trunk is created with valid details, DIDWW automatically begins the bind process. No further action is required to initiate the connection.
   - For full technical details about the protocol, encoding, and other details, see the :ref:`SMPP Specifications <service_incoming_sms>` guide.

.. raw:: html

    <br>

Mandatory SMPP SMSC Bind Parameters
-----------------------------------

When you create an SMPP SMSC trunk, you provide DIDWW with the connection details and credentials for your SMSC server. DIDWW will use these parameters when attempting to bind as an ESME.

    .. list-table::
       :widths: 12 75
       :header-rows: 1

       * - Parameter
         - Description
       * - **system_id**
         - The System ID that your SMSC requires for authentication.
       * - **password**
         - The password that your SMSC requires for authentication.
       * - **host**
         - The public hostname or IP address of your SMSC server.
       * - **port**
         - The TCP port your SMSC listens on (default: ``2775``).
       * - **system_type**
         - (Optional) A categorization value for the binding, such as “VMS” (voice mail system) or “OTA” (over-the-air activation).

.. raw:: html

    <br>

.. _user_panel_sms_smpp_smsc_status:

Check SMPP SMSC Bind Status
---------------------------

After configuring your server, you can verify the connection status in the User Panel:

    1. Navigate to the **SMS > SMS Trunks** list page.
    2. Find the trunk and click the |actions| button.
    3. Select **Check Status** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Accessing the Check Status option for an SMPP SMSC Trunk.
   :width: 100%

   **Fig. 5.** Checking the trunk status.

----

.. _user_panel_sms_smpp_smsc_edit:

Edit SMPP SMSC Trunk
====================

    1.  In the user panel menu, navigate to **SMS > SMS Trunks**.
    2.  Locate the trunk you wish to edit and click the |actions| button next to it.
    3.  Select **Edit** from the dropdown menu.
    4.  On the **Edit SMPP SMSC Trunk** page, modify the settings as needed.
    5.  Click **Save** to apply your changes.

.. figure:: https://doc.didww.com/_images/actions_edit.png
   :figclass: align-center
   :alt: Edit option for SMPP SMSC Trunk.
   :width: 100%

   **Fig. 6.** Edit option for SMPP SMSC Trunk.

----

.. _user_panel_sms_smpp_smsc_delete:

Delete SMPP SMSC Trunk(s)
=========================

You can delete a single SMPP SMSC trunk or multiple trunks at once by using batch actions.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Delete a Single Trunk*

      1.  Navigate to the **SMS Trunks** list page.
      2.  Locate the trunk you wish to remove and click the |actions| button next to it.
      3.  Select **Delete** from the dropdown menu.
      4.  In the confirmation pop-up window, click **Delete** to permanently remove the trunk.

      .. figure:: https://doc.didww.com/_images/actions_delete.png
         :figclass: align-center
         :alt: Delete option for SMPP SMSC Trunk.
         :width: 100%

         **Fig. 7.** Delete option for SMPP SMSC Trunk.

   .. tab-item:: *Delete Multiple Trunks*

      1.  Navigate to the **SMS Trunks** list page.
      2.  Select the trunks you wish to delete by checking the boxes next to them.
      3.  At the bottom of the page, click **Batch Actions** and select **Delete Trunks**.
      4.  In the confirmation pop-up window, click **Delete** to permanently remove the selected trunks.

      .. figure:: https://doc.didww.com/_images/delete_batch_actions.png
         :figclass: align-center
         :alt: Batch delete option for SMPP SMSC Trunks.

         **Fig. 8.** Batch delete option for SMPP SMSC Trunks.

----

.. raw:: html

    <br>

Related Resources
======================

.. card:: **Assign an SMS trunk**
    :link: assigning-sms-trunk
    :link-type: ref

    Learn how to assign your newly created trunk to DID numbers to receive inbound messages.

.. card:: **SMPP Specifications**
   :link: service_incoming_sms
   :link-type: ref

   Review detailed protocol information, including encoding and concatenation.

.. card:: **Sender ID Verifications**
   :link: user_panel_sms_campaign
   :link-type: ref

   Register sender IDs for Application-to-Person (A2P) messaging.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button

.. |credentials| image:: /img/new_user_panel/trunks/sms/smpp_esme/key.png
   :class: inline-img no-shadow
   :width: 24px
   :height: 24px
   :alt: Credentials button


.. |br| raw:: html

  <br>

.. _user_panel_sms_to_http_in_trunk:
.. _sms_in_http:

=============
HTTP IN Trunk
=============

HTTP IN SMS trunks allow you to forward incoming SMS messages from your Direct Inward Dialing (DID) numbers to a specified web server or application endpoint. Each message is delivered as an HTTP request.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Trunk**
      :link: user_panel_sms_to_http_in_trunk_create
      :link-type: ref
      :text-align: center

      Create and configure a new SMS to HTTP IN Trunk.

   .. grid-item-card:: :octicon:`pencil` **Edit Trunk**
      :link: user_panel_sms_to_http_in_trunk_edit
      :link-type: ref
      :text-align: center

      Update the settings of an existing trunk.

   .. grid-item-card:: :octicon:`trash` **Delete Trunk(s)**
      :link: user_panel_sms_to_http_in_trunk_delete
      :link-type: ref
      :text-align: center

      Remove one or more trunks from your account.

----

.. raw:: html

  <br>

.. _user_panel_sms_to_http_in_trunk_create:

Create HTTP IN Trunk
====================

Step 1: Start Creating HTTP IN Trunk
----------------------------------------------------------------

In the user panel menu, navigate to **SMS > SMS Trunks**. Click the **Create New** button in the top-right corner and select **HTTP IN** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Navigating to create a new SMS to HTTP IN Trunk.
   :width: 100%

   **Fig. 1.** Navigating to create a new SMS to HTTP IN Trunk.

Step 2: Configure HTTP IN Trunk
-------------------------------

Enter the general information required to set up your SMS to HTTP IN trunk. Provide a descriptive friendly name and define how incoming SMS messages should be delivered to your HTTP endpoint.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: SMS to HTTP IN Trunk configuration page.
   :width: 100%

   **Fig. 2.** Create HTTP IN Trunk Settings.

.. raw:: html

    <br>

General Settings
^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Setting
     - Description
   * - **Friendly name**
     - Enter a unique name to identify this trunk.
   * - **HTTP method**
     - Select the HTTP method for delivering messages: ``GET``, ``POST``, or ``PUT``.
   * - **Validate HTTPS certificate**
     - Enable to validate the SSL certificate of the destination server for secure transactions.
   * - **Follow redirect**
     - Enable to allow the system to follow HTTP 3xx redirect status codes.
   * - **Request URL**
     - Specify the destination URL of your web server or application endpoint. |br|
       Example: ``https://example.com/sms-handler``
   * - **Query Parameters**
     - Add custom key-value pairs to be sent as query parameters in the URL.
   * - **Headers**
     - Add custom HTTP headers to include in the request.
   * - **Body type**
     - Available for ``POST`` and ``PUT`` methods only. Defines the format method of HTTP request body: |br|
       |br|

       - **JSON** – Sends a raw JSON object.
       - **HTML-Multipart** – Sends data as ``multipart/form-data`` with key-value pairs.
       - **HTML URL Encoded** – Sends data as ``application/x-www-form-urlencoded`` with key-value pairs.
       - **RAW**: Sends a raw, unformatted payload.

.. note::
   You can use the following variables in the **Request URL**, **Query Parameters**, **Headers**, and **Body** fields to customize the request:

       * ``{SMS_TIME}``: The time the SMS was received.
       * ``{SMS_SRC_ADDR}``: The sender's phone number.
       * ``{SMS_DST_ADDR}``: The recipient DID number.
       * ``{SMS_TEXT}``: The raw text of the SMS message.
       * ``{SMS_TEXT_BASE64_ENCODED}``: The SMS message content encoded in Base64.

.. raw:: html

    <br>

Trunk Group Configuration (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You may assign the trunk to an existing trunk group in order to enable failover or load-balancing. Within the trunk group, you can also define the trunk’s **priority**, which determines the order in which trunks will be used.

.. note:: The system attempts to contact the target SMS trunk with the highest-numbered priority first.

.. raw:: html

    <br>

Step 3: Create the HTTP IN Trunk
---------------------------------------------

Click **Create** at the bottom of the page to save the new trunk.

.. raw:: html

    <br>

Step 4: Assign the HTTP IN Trunk to DIDs
--------------------------------------------

To receive messages, assign the new trunk to one or more DIDs that support inbound SMS. For detailed steps, see :ref:`Assign an SMS trunk <assigning-sms-trunk>`.

----

.. raw:: html

    <br>

.. _user_panel_sms_to_http_in_trunk_edit:

Edit HTTP IN Trunk
=========================

    1.  In the user panel menu, navigate to **SMS > SMS Trunks**.
    2.  Locate the trunk you wish to edit and click the |actions| button next to it.
    3.  Select **Edit** from the dropdown menu.
    4.  On the **Edit HTTP IN Trunk** page, modify the settings as needed.
    5.  Click **Save** to apply your changes.

.. figure:: https://doc.didww.com/_images/actions_edit.png
  :figclass: align-center
  :alt: Accessing the Edit option for an SMS to HTTP IN Trunk.
  :width: 100%

  **Fig. 3.** Accessing the Edit option for an SMS to HTTP IN Trunk.

----

.. raw:: html

    <br>

.. _user_panel_sms_to_http_in_trunk_delete:

Delete HTTP IN Trunk(s)
==============================

You can delete a single SMS to HTTP IN trunk or multiple trunks at once by using batch actions.

.. note::
    A trunk that is currently assigned to any DID number cannot be deleted until it is unassigned.

.. tab-set::
    :class: my-tabs

    .. tab-item:: *Delete a Single Trunk*

        1.  Navigate to the **SMS Trunks** list page.
        2.  Locate the trunk you wish to remove and click the |actions| button next to it.
        3.  Select **Delete** from the dropdown menu.
        4.  In the confirmation pop-up window, click **Delete** to permanently remove the trunk.

        .. figure:: https://doc.didww.com/_images/actions_delete.png
          :figclass: align-center
          :alt: Accessing the Delete option for an SMS to HTTP IN Trunk.
          :width: 100%

          **Fig. 4.** Accessing the Delete option for an SMS to HTTP IN Trunk.

    .. tab-item:: *Delete Multiple Trunks*

        1.  Navigate to the **SMS Trunks** list page.
        2.  Select the trunks you wish to delete by checking the boxes next to them.
        3.  At the bottom of the page, click **Batch Actions** and select **Delete Trunks**.
        4.  In the confirmation pop-up window, click **Delete** to permanently remove the selected trunks.

        .. figure:: https://doc.didww.com/_images/delete_batch_actions.png
          :figclass: align-center
          :alt: Using Batch Actions to delete multiple SMS to HTTP IN Trunks.
          :width: 100%

          **Fig. 5.** Using Batch Actions to delete multiple SMS to HTTP IN Trunks.

----

.. raw:: html

    <br>

Related Resources
======================

.. card:: **Assign an SMS trunk**
    :link: assigning-sms-trunk
    :link-type: ref

    Learn how to assign your newly created trunk to one or more DID numbers to start receiving messages.

.. card:: **Create an SMS Trunk Group**
    :link: user_panel_sms_trunk_group
    :link-type: ref

    Discover how to group multiple SMS trunks together for failover and load-balancing purposes.

.. card:: **SMS HTTP Specification**
    :link: user_panel_sms_http_specification
    :link-type: ref

    View the technical specification for HTTP-based SMS delivery.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button


.. |br| raw:: html

  <br>

.. _user_panel_sms_out:

================
HTTP OUT Trunks
================

HTTP OUT SMS trunks allow you to send outbound SMS messages from your DID numbers to a specified HTTP(s) endpoint. This enables direct integration with your own systems or third-party services.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Trunk**
      :link: user_panel_sms_http_out_trunk_create
      :link-type: ref
      :text-align: center

      Create and configure a new SMS HTTP OUT Trunk.

   .. grid-item-card:: :octicon:`key` **View or Regenerate Credentials**
      :link: user_panel_sms_http_out_trunk_credentials
      :link-type: ref
      :text-align: center

      Access or update HTTP OUT trunk credentials.

   .. grid-item-card:: :octicon:`paper-airplane` **Send SMS**
      :link: user_panel_sms_sending
      :link-type: ref
      :text-align: center

      Send a test SMS message from HTTP OUT trunk.

   .. grid-item-card:: :octicon:`pencil` **Edit Trunk**
      :link: user_panel_sms_http_out_trunk_edit
      :link-type: ref
      :text-align: center

      Update the settings of an existing trunk.

   .. grid-item-card:: :octicon:`trash` **Delete Trunk(s)**
      :link: user_panel_sms_http_out_trunk_delete
      :link-type: ref
      :text-align: center

      Remove one or more trunks from your account.

----

.. raw:: html

    <br>

.. _user_panel_sms_http_out_trunk_create:

Create HTTP OUT Trunk
=========================

Step 1: Start Creating HTTP OUT Trunk
-------------------------------------------------------------------

In the user panel menu, navigate to **SMS > SMS Trunks**. Click the **Create New** button in the top-right corner and select **HTTP OUT** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig1.png
    :figclass: align-center
    :alt: Navigating to create a new SMS to HTTP OUT Trunk.

    **Fig. 1.** Navigating to create a new SMS to HTTP OUT Trunk.

.. raw:: html

    <br>

Step 2: Configure HTTP OUT Trunk
--------------------------------

Enter the general information required to set up your SMS to HTTP OUT trunk. Provide a descriptive friendly name, configure the callback URL for delivery notifications, specify allowed IP addresses, and define the sender ID settings for outbound SMS.

.. figure:: https://doc.didww.com/_images/fig2.png
    :figclass: align-center
    :alt: SMS to HTTP OUT Trunk configuration window.

    **Fig. 2.** SMS to HTTP OUT Trunk configuration window.

.. _user_panel_sms_http_out_general_settings:

General Settings
^^^^^^^^^^^^^^^^

    .. list-table::
       :widths: 15 65
       :header-rows: 1

       * - Setting
         - Description
       * - **Friendly name**
         - A unique name to identify this trunk.
       * - **Callback URL**
         - URL to get the delivery status of the text messages you have sent. |br| The server will call your callback URL and post SMS delivery notifications.
       * - **Allowed IP addresses**
         - IP addresses from which access to the API is allowed in the format (IPv4|IPv6)[/mask] (not mandatory). |br| Allow all IP addresses if empty.

.. raw:: html

    <br>

.. _user_panel_sms_http_out_trunk_source_address_settings:

Source Address Settings
^^^^^^^^^^^^^^^^^^^^^^^

The **Source Address Settings** section controls which DID numbers can be used as the sender ID for outbound SMS.

Use the **Allow any DID(s) for SMS OUT** toggle to choose how sender IDs are assigned:

    - **Toggle on (default):** All DIDs with Outbound P2P SMS enabled in your account can be used as the sender ID.
    - **Toggle off:** You can specify which DIDs are allowed. To do this, select numbers from the **Available Source Addresses** list and add them to the **Allowed Source Addresses** list. Only the numbers you add will be available as sender IDs.

.. figure:: https://doc.didww.com/_images/gif1.gif
    :figclass: align-center
    :alt: Source address selection for SMS to HTTP OUT Trunk.

    **Fig. 3.** Source address selection for SMS to HTTP OUT Trunk.

.. note::
   When the **Allow any DID(s) for SMS OUT** toggle is turned off, the **Available Sender IDs** list shows only DIDs that support outbound P2P SMS.

Step 3: Create the Trunk
------------------------

Click **Create** at the bottom of the page to save the new trunk.

----

.. raw:: html

    <br>

.. _user_panel_sms_http_out_trunk_credentials:

View or Regenerate HTTP OUT Trunk Credentials
=================================================

    1.  Navigate to **SMS > SMS Trunks** in the user panel.
    2.  Locate the HTTP OUT trunk you want to manage.
    3.  Click the |credentials| key icon in the **Credentials** column to open the credentials window.

.. figure:: https://doc.didww.com/_images/fig_credentials1.png
        :figclass: align-center
        :alt: Credentials pop-up window for SMS to HTTP OUT Trunk.

        **Fig. 4.** Credentials button for SMS to HTTP OUT Trunk.

.. tab-set::
    :class: my-tabs

    .. tab-item:: *View Credentials*

        In the credentials pop-up window, you can see the HTTP OUT trunk **Username** and **Password**. Click the **eye** icon to show the password.

        .. figure:: https://doc.didww.com/_images/fig_credentials2.png
                :figclass: align-center
                :alt: Viewing credentials for an SMS to HTTP OUT Trunk.

                **Fig. 5.** Viewing credentials.

    .. tab-item:: *Regenerate Credentials*

        .. important::
            The password is updated immediately when you regenerate credentials. Update all integrations right away to avoid authentication failures.

        1. In the credentials pop-up window, click **Regenerate** next to the **Password** field to generate new credentials.
        2. Copy the new credentials and update any systems that use them.

        .. figure:: https://doc.didww.com/_images/fig_credentials2-regenerate.png
                :figclass: align-center
                :alt: Regenerating password for SMS to HTTP OUT Trunk.

                **Fig. 6.** Regenerating credentials.

----

.. raw:: html

    <br>

.. _user_panel_sms_sending:

Send SMS
========

From the SMS Trunks list, you can use the built-in tool to send a test message or a one-time message through any of your HTTP OUT trunks.

.. raw:: html

    <br>

Before You Begin
----------------

Before sending messages, make sure you have:

   1. A DID number with outbound P2P SMS enabled. If you don’t have one, see :ref:`How to Buy DID Numbers <user_panel_buy_numbers_process>`.
   2. Sender IDs configured in your HTTP OUT trunk. For details, see :ref:`Source Address Settings <user_panel_sms_http_out_trunk_source_address_settings>`.

.. raw:: html

    <br>

Step 1: Open the Send SMS Tool
-------------------------------

    1. In the user panel menu, navigate to **SMS > SMS Trunks**.
    2. Locate the desired HTTP OUT trunk and click the |actions| button next to it.
    3. Select **Send SMS** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/send1.png
  :figclass: align-center
  :alt: Accessing the SMS sending tool.

  **Fig. 7.** Accessing the SMS sending tool.

Step 2: Compose the Message
---------------------------

In the Send SMS window, select a source address, enter the destination number, and type your message.

.. list-table::
   :widths: 15 65
   :header-rows: 1

   * - Field
     - Description
   * - **Source Address**
     - Select one of your authorized DID numbers with outbound P2P SMS enabled.
   * - **Destination**
     - Enter the recipient's phone number in international format (for example, ``15551234567``).
   * - **Text**
     - Enter the message content.

.. figure:: https://doc.didww.com/_images/send2.png
  :figclass: align-center
  :alt: Composing an SMS message.

  **Fig. 8.** Composing an SMS message.

Step 3: Send the Message
------------------------

Click **Send** to deliver your message.

.. note::
   The system automatically selects the message encoding:

    - **GSM-7** is used for Latin-based characters. Each SMS fragment can contain up to 160 characters.
    - **UCS-2** is used for non-Latin characters. Each SMS fragment can contain up to 70 characters.

   Billing is based on SMS fragments, not on the message as submitted. If a
   long SMS is split into multiple fragments, each fragment is billed
   separately.

----

.. raw:: html

    <br>

.. _user_panel_sms_http_out_trunk_edit:

Edit HTTP OUT SMS Trunk
=======================

    1. In the user panel menu, navigate to **SMS > SMS Trunks**.
    2. Locate the trunk you wish to edit and click the |actions| button next to it.
    3. Select **Edit** from the dropdown menu.
    4. On the **Edit SMS to HTTP OUT Trunk** page, modify the settings as needed.
    5. Click **Save** to apply your changes.

    .. figure:: https://doc.didww.com/_images/fig_edit.png
         :figclass: align-center
         :alt: Edit option for SMS to HTTP OUT Trunk.
         :width: 100%

         **Fig. 9.** Edit option for SMS to HTTP OUT Trunk.

----

.. raw:: html

    <br>

.. _user_panel_sms_http_out_trunk_delete:

Delete HTTP OUT Trunk(s)
=========================

You can delete a single SMS to HTTP OUT trunk or multiple trunks at once by using batch actions.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Delete a Single Trunk*

      1. Navigate to the **SMS Trunks** list page.
      2. Locate the trunk you wish to remove and click the |actions| button next to it.
      3. Select **Delete** from the dropdown menu.
      4. In the confirmation pop-up window, click **Delete** to permanently remove the trunk.

      .. figure:: https://doc.didww.com/_images/fig_delete.png
         :figclass: align-center
         :alt: Delete option for SMS to HTTP OUT Trunk.
         :width: 100%

         **Fig. 10.** Delete option for SMS to HTTP OUT Trunk.

   .. tab-item:: *Delete Multiple Trunks*

      1. Navigate to the **SMS Trunks** list page.
      2. Select the trunks you wish to delete by checking the boxes next to them.
      3. At the bottom of the page, click **Batch Actions** and select **Delete Trunks**.
      4. In the confirmation pop-up window, click **Delete** to permanently remove the selected trunks.

      .. figure:: https://doc.didww.com/_images/fig_delete_batch.png
         :figclass: align-center
         :alt: Batch delete option for SMS to HTTP OUT Trunks.

         **Fig. 11.** Batch delete option for SMS to HTTP OUT Trunks.

----

.. raw:: html

  <br>

Related Resources
======================

.. card:: **How to Send Messages**
    :link: user_panel_sms_sending
    :link-type: ref

    Learn how to send SMS messages directly from the DIDWW User Panel using an HTTP OUT Trunk.

.. card:: **HTTP Specification**
    :link: user_panel_sms_http_specification
    :link-type: ref

    See full technical details for HTTP message delivery formats and variables.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button

.. |credentials| image:: /img/new_user_panel/trunks/sms/http_out/credentials.png
   :class: inline-img no-shadow
   :width: 24px
   :height: 24px
   :alt: Credentials button


.. |br| raw:: html

  <br>

.. _user_panel_sms_to_email_trunk:
.. _sms_in_email:

==================
SMS to Email Trunk
==================

SMS to Email trunks allow you to forward incoming SMS messages from your Direct Inward Dialing (DID) numbers directly to a specified email address. Each message is converted and delivered as a standard email.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Trunk**
      :link: user_panel_sms_to_email_trunk_create
      :link-type: ref
      :text-align: center

      Create and configure a new SMS to Email Trunk.

   .. grid-item-card:: :octicon:`pencil` **Edit Trunk**
      :link: user_panel_sms_to_email_trunk_edit
      :link-type: ref
      :text-align: center

      Update the settings of an existing trunk.

   .. grid-item-card:: :octicon:`trash` **Delete Trunk(s)**
      :link: user_panel_sms_to_email_trunk_delete
      :link-type: ref
      :text-align: center

      Remove one or more trunks from your account.

----

.. raw:: html

  <br>

.. _user_panel_sms_to_email_trunk_create:

Create SMS to Email Trunk
=========================

Step 1: Start Creating SMS to Email Trunk
------------------------------------------------------------------------

In the user panel menu, navigate to **SMS > SMS Trunks**. Click the **Create New** button in the top-right corner and select **Email** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Navigating to create a new SMS to Email Trunk.
   :width: 100%

   **Fig. 1.** Navigating to create a new SMS to Email Trunk.

Step 2: Configure SMS To Email Trunk
------------------------------------

Enter the general information required to set up your SMS to Email trunk. Provide a descriptive friendly name and define how incoming SMS messages should be forwarded by email.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: SMS to Email Trunk configuration page.
   :width: 100%

   **Fig. 2.** SMS to Email Trunk configuration settings.

.. raw:: html

    <br>

General Settings
^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Setting
     - Description
   * - **Friendly name**
     - Enter a unique name to identify this trunk.
   * - **Recipient email**
     - Specify the email address where incoming SMS messages will be delivered.
   * - **Email subject**
     - Define the subject line of the forwarded email. Dynamic variables are supported. |br|
       Example: ``SMS Received From: {SMS_SRC_ADDR} To: {SMS_DST_ADDR}``
   * - **Email body**
     - Define the body content of the forwarded email. Dynamic variables are supported. |br|
       Example: ``{SMS_TIME}, {SMS_TEXT}``

.. note::
   You can use the following variables in the **Email subject** and **Email body** fields to customize the output:

       * ``{SMS_TIME}``: The time the SMS was received.
       * ``{SMS_SRC_ADDR}``: The sender's phone number.
       * ``{SMS_DST_ADDR}``: The recipient DID number.
       * ``{SMS_TEXT}``: The raw text of the SMS message.
       * ``{SMS_TEXT_BASE64_ENCODED}``: The SMS message content encoded in Base64.

.. raw:: html

    <br>

Trunk Group Configuration (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You may assign the trunk to an existing trunk group in order to enable failover or load-balancing. Within the trunk group, you can also define the trunk’s **priority**, which determines the order in which trunks will be used.

.. note:: The system attempts to contact the target SMS trunk with the highest-numbered priority first.

.. raw:: html

    <br>

Step 3: Create the SMS To Email Trunk
---------------------------------------

Click **Create** at the bottom of the page to save the new trunk.

.. raw:: html

    <br>

Step 4: Assign the SMS To Email Trunk to DIDs
---------------------------------------------

To receive messages, assign the new trunk to one or more DIDs that support inbound SMS. For detailed steps, see :ref:`Assign an SMS trunk <assigning-sms-trunk>`.

----

.. raw:: html

    <br>

.. _user_panel_sms_to_email_trunk_edit:

Edit SMS to Email Trunk
=======================

    1.  In the user panel menu, navigate to **SMS > SMS Trunks**.
    2.  Locate the trunk you wish to edit and click the |actions| button next to it.
    3.  Select **Edit** from the dropdown menu.
    4.  On the **Edit SMS to Email Trunk** page, modify the settings as needed.
    5.  Click **Save** to apply your changes.

.. figure:: https://doc.didww.com/_images/actions_edit.png
   :figclass: align-center
   :alt: Accessing the Edit option for an SMS to Email Trunk.
   :width: 100%

   **Fig. 3** Edit option for an SMS to Email Trunk.

----

.. raw:: html

    <br>

.. _user_panel_sms_to_email_trunk_delete:

Delete SMS to Email Trunk(s)
============================

You can delete a single SMS to Email trunk or multiple trunks at once by using batch actions.

.. note::
       A trunk that is currently assigned to any DID number cannot be deleted until it is unassigned.

.. tab-set::
    :class: my-tabs

    .. tab-item:: *Delete a Single Trunk*

        1.  Navigate to the **SMS Trunks** list page.
        2.  Locate the trunk you wish to remove and click the |actions| button next to it.
        3.  Select **Delete** from the dropdown menu.
        4.  In the confirmation pop-up window, click **Delete** to permanently remove the trunk.

        .. figure:: https://doc.didww.com/_images/actions_delete.png
           :figclass: align-center
           :alt: Accessing the Delete option for an SMS to Email Trunk.
           :width: 100%

           **Fig. 4** Delete option for an SMS to Email Trunk.

    .. tab-item:: *Delete Multiple Trunks*

        1.  Navigate to the **SMS Trunks** list page.
        2.  Select the trunks you wish to delete by checking the boxes next to them.
        3.  At the bottom of the page, click **Batch Actions** and select **Delete Trunks**.
        4.  In the confirmation pop-up window, click **Delete** to permanently remove the selected trunks.

        .. figure:: https://doc.didww.com/_images/delete_batch_actions.png
           :figclass: align-center
           :alt: Using Batch Actions to delete multiple trunks.
           :width: 100%

           **Fig. 5** Batch delete option for SMS to Email Trunks.

----

.. raw:: html

    <br>

Related Resources
======================

.. card:: **Assign an SMS trunk**
    :link: assigning-sms-trunk
    :link-type: ref

    Learn how to assign your newly created trunk to one or more DID numbers to start receiving messages.

.. card:: **Create an SMS Trunk Group**
    :link: user_panel_sms_trunk_group
    :link-type: ref

    Discover how to group multiple SMS trunks together for failover and load-balancing purposes.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button


.. _userpanel_sms:

==========
SMS Trunks
==========

SMS trunks enable users to send and receive text messages sent to their local, national and mobile SMS-enabled DIDs. Users can easily create, configure and monitor the SMS trunks through the DIDWW User Panel.

----

.. grid:: 1 1 2 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`inbox` **SMS to Email Trunk**
      :link: create-sms-to-email-trunk
      :link-type: doc
      :text-align: left

      Forward incoming SMS messages to a specified email address with customizable subject and body fields.

   .. grid-item-card:: :octicon:`code` **HTTP IN Trunk**
      :link: create-sms-http-trunk-in
      :link-type: doc
      :text-align: left

      Forward inbound SMS to an HTTP endpoint with customizable methods, headers, and parameters.

   .. grid-item-card:: :octicon:`arrow-right` **HTTP OUT Trunk**
      :link: create-sms-http-trunk-out
      :link-type: doc
      :text-align: left

      Set up outbound SMS delivery to HTTP endpoints with configurable sender IDs and secure access controls.

   .. grid-item-card:: :octicon:`broadcast` **SMPP ESME Trunk**
      :link: create-smpp-esme-trunk
      :link-type: doc
      :text-align: left

      Set up SMPP ESME trunks for enterprise SMS delivery.

   .. grid-item-card:: :octicon:`server` **SMPP SMSC Trunk**
      :link: create-smpp-smsc-trunk
      :link-type: doc
      :text-align: left

      Configure SMPP SMSC trunks for carrier-grade SMS connectivity.

   .. grid-item-card:: :octicon:`git-merge` **SMS Trunk Group**
      :link: trunk-group
      :link-type: doc
      :text-align: left

      Combine multiple SMS trunks into groups for redundancy and load balancing.

   .. grid-item-card:: :octicon:`arrow-switch` **Assign an SMS trunk**
      :link: assigning-sms-trunk
      :link-type: ref
      :text-align: left

      Assign SMS trunks to one or multiple DIDs to enable inbound message routing.

   .. grid-item-card:: :octicon:`file` **Technical Specifications**
      :link: technical-specifications
      :link-type: doc
      :text-align: left

      Review detailed SMS trunk specifications, protocols, and supported features.

.. toctree::
  :maxdepth: 1
  :glob:
  :hidden:

  SMS to Email Trunk <create-sms-to-email-trunk.rst>
  HTTP IN Trunk <create-sms-http-trunk-in.rst>
  HTTP OUT Trunk <create-sms-http-trunk-out.rst>
  SMPP ESME Trunk <create-smpp-esme-trunk.rst>
  SMPP SMSC Trunk <create-smpp-smsc-trunk.rst>
  SMS Trunk Group <trunk-group.rst>
  Technical Specifications <technical-specifications.rst>


.. _user_panel_sms_trunk_group:

=================
SMS Trunk Groups
=================

SMS Trunk Groups provide failover (redundancy) for your inbound SMS services. By grouping multiple SMS trunks together, you can define a prioritized order for routing messages. If the primary trunk is unavailable, the system will automatically attempt to deliver the message via the next trunk in the sequence.

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Trunk Group**
      :link: user_panel_sms_trunk_group_create
      :link-type: ref
      :text-align: center

      Create and configure a new SMS Trunk Group.

   .. grid-item-card:: :octicon:`list-unordered` **Manage Trunks in Group**
      :link: user_panel_sms_trunk_group_manage_trunks
      :link-type: ref
      :text-align: center

      Add trunks to the group and set their priority order.

   .. grid-item-card:: :octicon:`pencil` **Edit Trunk Group**
      :link: user_panel_sms_trunk_group_edit
      :link-type: ref
      :text-align: center

      Update the name or modify the members of an existing trunk group.

   .. grid-item-card:: :octicon:`trash` **Delete Trunk Group(s)**
      :link: user_panel_sms_trunk_group_delete
      :link-type: ref
      :text-align: center

      Remove a trunk group and its assigned trunks from your account.

----

.. raw:: html

   <br>

Before You Begin
================

Make sure you have **at least two existing SMS trunks**. A trunk group requires multiple trunks to provide redundancy and failover.

----

.. raw:: html

   <br>

.. _user_panel_sms_trunk_group_create:

Create SMS Trunk Group
======================

Step 1: Start Creating Trunk Group
-------------------------------------

In the user panel menu, navigate to **SMS > SMS Trunks**. Click the **Create New** button and select **Trunk group** from the dropdown menu.

    .. figure:: https://doc.didww.com/_images/fig1.png
       :figclass: align-center
       :alt: Navigating to create a new SMS Trunk Group.
       :width: 100%

       **Fig. 1.** Navigating to create a new SMS Trunk Group.

.. raw:: html

   <br>

Step 2: Configure Trunk Group
--------------------------------

Assign a descriptive friendly name to identify the group and select two or more SMS trunks.

.. note:: The SMS trunk dropdown shows only trunks that are not already part of another trunk group.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: The Create SMS Trunk Group configuration page.
   :width: 100%

   **Fig. 2.** The SMS Trunk Group configuration page.

.. raw:: html

   <br>

Step 3: Create the Group
------------------------

After entering all required details, click **Create** at the bottom of the page to save your trunk group. The group will then appear in the SMS Trunk Groups list.

.. raw:: html

   <br>

Step 4: Assign the Trunk Group to DIDs
--------------------------------------

To receive messages, assign the trunk group to one or more DIDs that support inbound SMS. For detailed steps, see :ref:`Assign an SMS trunk <assigning-sms-trunk>`.

----

.. raw:: html

   <br>

.. _user_panel_sms_trunk_group_manage_trunks:

Manage Trunks in a Group
========================

After creating a trunk group, you can manage its member trunks from the **SMS Trunks** list.

Setting Trunk Priority
----------------------

Priority controls the order in which trunks are used for message delivery. The trunk with the highest number in the **Priority** field has the highest priority and is attempted first.

    1. In the **SMS Trunks** list, expand the trunk group by clicking the arrow next to its name.
    2. The member trunks will be displayed, each with a **Priority** field.
    3. Click the number in the **Priority** column to edit it. A higher value represents a higher priority.

For example, if trunks have priorities ``2``, ``1``, and ``0``, the system attempts the trunk with priority ``2`` first. If it fails, the system tries priority ``1``, followed by priority ``0``.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Viewing and editing the priority of trunks within a group.
   :width: 100%

   **Fig. 3.** Managing trunk priorities.

----

.. raw:: html

   <br>

.. _user_panel_sms_trunk_group_edit:

Edit SMS Trunk Group
====================

1.  Navigate to the **SMS Trunks** list page.
2.  Locate the trunk group and click the |actions| button next to it.
3.  Select **Edit**, make the necessary changes, and click **Save**.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: The Edit SMS Trunk Group button.
   :width: 100%

   **Fig. 4.** The Edit SMS Trunk Group button.

----

.. raw:: html

   <br>

.. _user_panel_sms_trunk_group_delete:

Delete SMS Trunk Group
======================

1.  Navigate to the **SMS Trunks** list page.
2.  Find the trunk group you want to remove and click the actions button |actions|.
3.  Select **Delete**.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: The Delete SMS Trunk Group button.
   :width: 100%

   **Fig. 5.** The Delete SMS Trunk Group button.

4. In the confirmation window, choose how to handle the member trunks:

   * **Remove SMS trunks from the group** — Deletes the trunk group but keeps the individual trunks in your account.
   * **Delete SMS trunks** — Permanently deletes both the group and all of its member trunks.

5. Click **Delete** to confirm.

.. note::
   SMS trunks that are currently assigned to a DID cannot be deleted. Unassign the trunks from all DIDs before attempting to delete them.

.. figure:: https://doc.didww.com/_images/fig6.png
   :figclass: align-center
   :alt: The confirmation modal for deleting an SMS Trunk Group.
   :width: 100%

   **Fig. 6.** The Delete SMS Trunk Group confirmation window.

----

.. raw:: html

   <br>

Related Resources
======================

.. card:: **Assign an SMS trunk**
    :link: assigning-sms-trunk
    :link-type: ref

    Learn how to assign your trunk groups to DID numbers to receive inbound messages.

.. card:: **Create an SMS to Email Trunk**
   :link: sms_in_email
   :link-type: ref

   Learn how to configure a trunk to forward inbound SMS messages to an email address.

.. card:: **Create an SMS to HTTP IN Trunk**
   :link: sms_in_http
   :link-type: ref

   Learn how to configure a trunk to forward inbound SMS messages to a web server.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button


.. _userpanel_sms_technical_specifications:

========================
Technical Specifications
========================

This section provides comprehensive documentation necessary for implementing and integrating SMS services. It includes technical guidelines, protocol specifications, and best practices to ensure seamless integration and optimal use of the SMS functionalities.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`server` **SMPP Specification**
      :link: technical-data/smpp-specification
      :link-type: doc
      :text-align: left

      Technical guide for exchanging SMS over SMPP (ESME ↔ SMSC).

   .. grid-item-card:: :octicon:`code-square` **HTTP Specification**
      :link: technical-data/http-specification
      :link-type: doc
      :text-align: left

      Technical guide for sending and receiving SMS over HTTP.

   .. grid-item-card:: :octicon:`shield` **Inbound SMS Guidelines**
      :link: technical-data/guidelines
      :link-type: doc
      :text-align: left

      Key considerations, restrictions, and troubleshooting for inbound SMS.

.. toctree::
   :maxdepth: 1
   :hidden:

   SMPP Specification <technical-data/smpp-specification>
   HTTP Specification <technical-data/http-specification>
   Inbound SMS Guidelines <technical-data/guidelines>

  	


.. |br| raw:: html

  <br>

.. _service_smpp_specification:
.. _service_incoming_sms:

===================
SMPP Specifications
===================

The SMPP specification defines how to exchange SMS messages with DIDWW using the Short Message Peer-to-Peer protocol. It is fully compliant with the `SMPP v3.4 Specifications <https://smpp.org/SMPP_v3_4_Issue1_2.pdf>`_ and supports both outbound messages sent from an External Short Messaging Entity (ESME) to an SMSC and inbound messages delivered from an SMSC to an ESME.

    - **External Short Messaging Entity (ESME)** is an external application that connects to a Short Message Service Center (SMSC) to engage in the sending and/or receiving SMS messages
    - **Short Message Service Center (SMSC)** is a network element in the mobile telephone network. Its purpose is to store, forward, convert and deliver SMS messages.

----

.. raw:: html

    <br>

P2P and A2P Messaging
=====================

The SMPP protocol is used for both Person-to-Person (P2P) and Application-to-Person (A2P) messaging.

    - **P2P** - Low-volume, two-way exchange of SMS between end-users. Typically handled through either ESME or SMSC trunks, depending on direction.
    - **A2P** - High-volume SMS generated by applications and sent to subscribers. Usually sent over an ESME trunk, where your application connects directly to the SMSC.

.. important::
   A2P traffic requires a sender ID registered through an active :ref:`Sender ID Verification <user_panel_sms_campaign>`.

----

.. raw:: html

    <br>

.. _smpp_bind_parameters:

Bind Parameters for SMPP ESME Trunks
====================================

When your application connects to the DIDWW SMSC (using an :ref:`ESME trunk <sms_esme>`), it must perform a bind with the following parameters.

.. list-table::
   :widths: 15 70
   :header-rows: 1

   * - Parameter
     - Description
   * - **system_id**
     - The **System ID** from the trunk's :ref:`Credentials <user_panel_sms_smpp_esme_credentials>`. |br| Identifies your ESME during the bind request.
   * - **password**
     - The **Password** from the trunk's :ref:`Credentials <user_panel_sms_smpp_esme_credentials>`. |br| Used with the system_id for authentication.
   * - **system_type**
     - Optional field set when :ref:`creating the SMPP trunk <user_panel_sms_smpp_esme_create>`. |br| Categorizes the bind (e.g., ``VMS`` for voicemail, ``OTA`` for over-the-air updates).
   * - **host**
     - The SMPP server address. |br| Use the global endpoint ``46.19.209.214`` or a regional :ref:`endpoint <smpp_endpoints>`.
   * - **port**
     - ``2775`` (default SMPP port).

.. important::
   - For :ref:`SMPP SMSC trunks <sms_smsc>`, DIDWW performs the bind to your system automatically using the credentials you provide in the trunk settings. |br|
   - Your SMSC must be configured to **accept incoming bind_transmitter or bind_transceiver requests** on the specified host/port, and validate them using the system_id and password you defined in the trunk.
   - Configure your firewall to **allow inbound connections from DIDWW SMPP server** global endpoint ``46.19.209.214`` and all other :ref:`regional endpoints <smpp_endpoints>`.

----

.. raw:: html

    <br>

.. _smpp_pdu_flow:

SMPP Message Flow
====================

In SMPP, the SMS payload and control are exchanged using **Protocol Data Units (PDUs)**.
The key PDUs for message delivery are:

    - **submit_sm** — Sent by an ESME to submit an outbound SMS. It typically carries fields like ``source_addr``, ``destination_addr``, and the ``short_message`` text.
    - **deliver_sm** — Sent by an SMSC to deliver an inbound (MO) SMS to an ESME, or to return a delivery receipt (DLR). It may carry either message text or status information.

Message flow depends on the SMPP trunk type:

    - **ESME** – Your application binds as the ESME to DIDWW’s SMSC. You send SMS using ``submit_sm`` and receive inbound SMS or DLRs via ``deliver_sm``.
    - **SMSC** – DIDWW binds as an ESME to your SMSC. DIDWW submits SMS with ``submit_sm``, and your SMSC can send inbound messages or receipts with ``deliver_sm``.

When :ref:`creating an SMSC trunk <user_panel_sms_smpp_smsc_create>`, you can choose the SMPP connection mode:

    - **Transmitter** — The ESME (DIDWW) can only send outbound messages to your SMSC. Uses the **TX (Transmitter) port**, while the RX port is ignored.
    - **Transceiver** — The ESME (DIDWW) can both send and receive messages on the same bind session. Uses the **Transceiver port** (TX/RX combined).

.. note::
   - The SMS text is normally carried in the ``short_message`` field.
   - Concatenated messages use a User Data Header (UDH) within ``short_message`` to split and reassemble long SMS.
   - Delivery receipts (DLR) are also sent in ``deliver_sm`` and typically contain status information.
   - Each PDU requires an acknowledgement: ``submit_sm`` ↔ ``submit_sm_resp``, ``deliver_sm`` ↔ ``deliver_sm_resp``.

----

.. raw:: html

    <br>

.. _smpp_encoding:

Data Coding Scheme (DCS)
========================

The ``data_coding`` parameter, also known as **DCS (Data Coding Scheme)**, specifies the character set for an SMS message. The encoding you use directly impacts how many characters can fit into a single SMS part.

.. list-table::
   :widths: 14 38 27
   :header-rows: 1

   * - DCS Value
     - Encoding
     - Max characters per SMS
   * - ``0``
     - GSM-7 (Default).
     - 160
   * - ``1``
     - US-ASCII.
     - 160
   * - ``3``
     - Latin1 (`ISO-8859-1 <https://www.iso.org/standard/28245.html>`_).
     - 160
   * - ``8``
     - Unicode / UCS-2 (`ISO/IEC-10646 <https://www.iso.org/standard/76835.html>`_).
     - 70

.. note::
   - GSM-7 is the standard encoding for most SMS.
   - UCS-2 is required for non-Latin scripts (e.g., Chinese, Arabic, Cyrillic) but reduces the per-SMS character limit.

----

.. raw:: html

    <br>

.. _smpp_concatenated_messages:

Concatenated Messages
=====================

To overcome the 160-character limit of a single SMS, long texts are split into smaller fragments and reassembled at the recipient’s device.
This creates a multi-part SMS, known as a concatenated message.
A User Data Header (UDH) is added to each part, which slightly reduces the character capacity.

.. note::
   - Up to **255 parts** can be combined to form one long message.
   - Each part is billed as a separate SMS.

.. list-table::
   :widths: 15 8 11 23
   :header-rows: 1

   * - Encoding
     - Bit Size
     - Max Chars |br| (Single SMS)
     - Max Chars |br| (per Part in Concatenated SMS)
   * - **GSM-7 & Latin-1/9**
     - 7-bit
     - 160
     - 153
   * - **UCS-2 (Unicode)**
     - 16-bit
     - 70
     - 67

----

.. raw:: html

    <br>

.. _smpp_endpoints:
.. _smpp_outbound_sms_endpoints:

Endpoints
=========

.. list-table::
   :header-rows: 1

   * - Hostname
   * - sms-out.didww.com
   * - us.sms-out.didww.com
   * - nyc.us.sms-out.didww.com
   * - mia.us.sms-out.didww.com
   * - lac.us.sms-out.didww.com
   * - eu.sms-out.didww.com
   * - sg.sms-out.didww.com


.. |br| raw:: html

   <br />

.. _sms_in_guidelines:

=========================
Inbound SMS Guidelines
=========================

The Inbound SMS guidelines outline important considerations when receiving SMS on DID numbers.
These guidelines explain how delivery works, highlight potential restrictions, and describe the limitations related to A2P messaging, SMS verification, and troubleshooting.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_local:

SMS Delivery
------------

DID numbers are optimized to receive SMS **within their country of registration**. International delivery may be affected by:

    - **Local restrictions** — Some countries enforce regulatory or technical limits on inbound international SMS to DIDs.
    - **Outdated routing data** — Originating networks may rely on outdated or incomplete routing databases, causing delivery failures.

.. note::
   Delivery behavior may vary depending on the **originating network** and **message type**, and international traffic can sometimes experience **delays or message loss** due to upstream carrier dependencies.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_email:

SMS to Email Delivery
---------------------

If you are using an :ref:`SMS to Email trunk <sms_in_email>`, inbound SMS messages will be automatically forwarded to the **recipient email address** you configured.

    - All forwarded messages are delivered **from** the address ``sms-forwarding@didww.com``.
    - The **subject line** and **email body** are generated according to the configuration you set when creating the trunk.
    - Supported placeholders (e.g., ``{SMS_SRC_ADDR}``, ``{SMS_DST_ADDR}``, ``{SMS_TEXT}``) can be used in the trunk setup to customize the email output.

.. note::
   Make sure your email system allows incoming mail from ``sms-forwarding@didww.com`` so that inbound SMS messages are not filtered as spam or rejected.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_verification:

SMS Verification Notice
-----------------------

Using DID numbers for **SMS verification** is **not recommended**. DID numbers are **non-exclusive** and may be reassigned over time, which can create security and continuity risks for verification workflows.

.. note::
   - Some applications and platforms **may not deliver** one-time codes to DID numbers by policy. They may restrict delivery to mobile (cellular) ranges only, or block numbers identified by number-validation checks.
   - If you must use SMS verification, ensure you have an alternative verification path and do **not** rely on a single DID for long-term account recovery.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_a2p:

A2P Messaging
-------------

DID numbers are primarily intended for two-way person-to-person communication. In certain countries, Application-to-Person (A2P) traffic to DIDs may be restricted by regulation or commercial policy.

.. note::
   To reduce costs, some originators run **number validation** before sending messages. These tools can misclassify DID prefixes if their databases are outdated or incomplete. |br|
   Originators may also deliver A2P messages with **alphanumeric sender IDs**, which can behave differently from numeric MSISDNs.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_encoding:

Encoding and Concatenation
--------------------------

Inbound SMS may arrive in different encodings depending on the sender:

    - **GSM-7** — Standard encoding, up to 160 characters.
    - **UCS-2 (Unicode)** — Required for non-Latin scripts (e.g., Chinese, Arabic, Cyrillic), up to 70 characters per message.

When a message exceeds these limits, it is delivered as a **concatenated message** (multi-part SMS).
A **User Data Header (UDH)** is used to split and reassemble long messages. Up to **255 parts** may be supported for a single message.

.. note::
   Applications must be able to process UDH headers and reassemble multi-part SMS to correctly display long messages.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_firewall:

Firewall Configuration
----------------------

To receive inbound SMS correctly, ensure your firewall allows traffic from DIDWW inbound SMS delivery IP addresses.
Requests will always originate from DIDWW-defined IPs (see :ref:`Endpoints <smpp_endpoints>`), which must be explicitly permitted.

----

.. raw:: html

   <br>

.. _sms_in_guidelines_troubleshooting:

Troubleshooting
---------------

If you have delivery issues after reviewing the points above, contact **DIDWW Technical Support** at support@didww.com and include the SMS details below.

.. list-table::
   :widths: 28 52
   :header-rows: 1

   * - **Field**
     - **Description**
   * - **Date and Time (UTC)**
     - Exact timestamp when the SMS was sent.
   * - **Originating Number**
     - The sender’s phone number.
   * - **Destination DID**
     - The DID number that should receive the SMS.
   * - **Originating Network/Operator**
     - Name of the operator or platform that submitted the SMS, if known.
   * - **Any Error/Status from Sender Side**
     - Delivery status, error code, or logs provided by the originating platform.

SMS Details Example
^^^^^^^^^^^^^^^^^^^

When opening a trouble ticket to our support team at support@didww.com you may copy the example below and replace the placeholder values with your real SMS details.

.. code-block:: text

   Date and Time (UTC): YYYY-MM-DD HH:MM:SS
   Originating Number: +<E.164>
   Destination DID: +<E.164>
   Originating Network/Operator: <Name, if known>
   Any Error/Status from Sender Side: <Delivery status, error code, or logs, if available>

.. note::
   More context reduces investigation time. If you performed **multiple test attempts**, please share **multiple samples** with different timestamps.

.. |br| raw:: html

  <br>

.. _user_panel_sms_http_specification:

==================
HTTP Specification
==================

The SMS HTTP specification defines how to exchange SMS messages with DIDWW over HTTP. It includes information about inbound SMS delivery to your systems and outbound SMS submission to the DIDWW network, covering request formats, authentication, failover handling, and callback mechanisms.

.. grid:: 1 1 1 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`comment` **Inbound SMS Specification**
      :link: sms_in_specification
      :link-type: ref
      :text-align: center

      Technical details for receiving inbound SMS from DIDWW via HTTP.

   .. grid-item-card:: :octicon:`arrow-right` **Outbound SMS Specification**
      :link: sms_out_specification
      :link-type: ref
      :text-align: center

      API reference for sending outbound SMS to the DIDWW network.

----

.. raw:: html

    <br>

.. _sms_in_specification:

Inbound SMS Specification
==========================

The Inbound SMS service lets you receive text messages by having DIDWW forward them to your HTTP endpoint.
Find out how requests are sent, which variables you can use, the formats supported for the request body, and key technical details such as retries and failover.

.. raw:: html

    <br>

.. _sms_in_spec_request:

HTTP Request Details from DIDWW
----------------------------------

When a message is received on one of your DIDs, DIDWW will send an HTTP request to the **Request URL** configured in your :ref:`SMS to HTTP IN Trunk <sms_in_http>`.

.. list-table::
   :widths: 15 40
   :header-rows: 1

   * - Property
     - Description
   * - **HTTP Methods**
     - Supported methods are ``GET``, ``POST``, and ``PUT``.
   * - **Source IPs**
     - Requests may originate from ``46.19.209.214`` or ``185.238.173.74``.
   * - **Connection Type**
     - HTTPS (recommended) and HTTP are supported.

.. note::
   Allow requests from **46.19.209.214** and **185.238.173.74** in your firewall.

.. raw:: html

    <br>

.. _sms_in_spec_variables:

Available Variables
-------------------

.. list-table::
   :widths: 21 55
   :header-rows: 1

   * -   Variable
     -   Description
   * -   ``{SMS_UUID}``
     -   The unique ID of the received message.
   * -   ``{SMS_SRC_ADDR}``
     -   The sender's phone number (source address), for more information see `RFC 3986 <https://www.rfc-editor.org/rfc/rfc3986.html>`_.
   * -   ``{SMS_DST_ADDR}``
     -   The DID number that received the SMS (destination address), for more information see `RFC 3986 <https://www.rfc-editor.org/rfc/rfc3986.html>`_.
   * -   ``{SMS_TEXT}``
     -   The raw text of the SMS message body.
   * -   ``{SMS_TEXT_BASE64_ENCODED}``
     -   The SMS message body, encoded using `Base64 <https://en.wikipedia.org/wiki/Base64>`_.
   * -   ``{SMS_TIME}``
     -   The date and time the message was received, for more information see `RFC 1123 <https://www.rfc-editor.org/rfc/rfc1123.html#page-55>`_.

.. note:: You can use these variables to construct the **Request URL**, **Query Parameters**, **Headers**, and **Body** of the request in your trunk configuration.

.. raw:: html

    <br>

Request Body Formats
----------------------------

When DIDWW forwards an inbound SMS to your HTTP endpoint, the SMS data is placed in the **body** of the HTTP request. The format is selected in your trunk settings and determines how your server should parse the data.

Available formats:
    - **RAW**
    - **JSON** (``application/json``)
    - **URL encoded** (``application/x-www-form-urlencoded``)
    - **Multipart** (``multipart/form-data``)

.. note::
   Choose the format that matches how your endpoint is designed.
   For example, if your system expects JSON but receives URL encoded data, it will not parse correctly.

.. raw:: html

    <br>

.. _sms_in_spec_technical:
.. _blocked:

Technical Details
-----------------

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Failover*

      If your endpoint does not respond with a ``2xx`` status code, DIDWW will re-attempt to deliver the message until its Time To Live (TTL) of **3600 seconds (1 hour)** expires.

   .. tab-item:: *Concatenated Messages*

      The maximum size of an inbound SMS message is **64 KB**. |br| Concatenated messages will be reassembled using **User Data Header (UDH)** before being delivered to your endpoint. Information about fragmentation will not be transmitted.

----

.. raw:: html

    <br>

.. _sms_out_specification:

Outbound SMS Specification
======================================

DIDWW supports both Person-to-Person (P2P) and Application-to-Person (A2P) messaging.
Outbound SMS can be sent using the DIDWW REST API, which follows the `JSON:API specification <https://jsonapi.org/format/>`_, or via SMPP, which follows the standard SMPP specifications.

.. raw:: html

   <div class="postman-run-button"
        data-postman-action="collection/fork"
        data-postman-visibility="public"
        data-postman-var-1="15857673-bdb1d760-4929-41ed-a5b0-1642a6562ad7"
        data-postman-collection-url="entityId=15857673-bdb1d760-4929-41ed-a5b0-1642a6562ad7&entityType=collection&workspaceId=df32e55b-0b93-45c2-82c0-e6f15ee2d5c1">
   </div>

   <script type="text/javascript">
     (function (p,o,s,t,m,a,n) {
       !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
       !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
         (n = o.createElement("script")),
         (n.id = s+t), (n.async = 1), (n.src = m), n
       ));
     }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
   </script>
   <br>
   <br>

.. raw:: html

    <br>

.. _sms_out_spec_authentication:

Authentication
--------------

API requests are secured with two layers: IP whitelisting and HTTP Basic Authentication. Both must be valid for a request to succeed.

.. raw:: html

    <br>

1. IP Whitelisting (Network Layer)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In your :ref:`HTTP OUT trunk configuration <user_panel_sms_http_out_trunk_create>`, specify the Allowed IP addresses. The API rejects requests from any other source.

.. raw:: html

    <br>

2. Basic Authentication (Application Layer)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After IP validation, the system checks your credentials with **HTTP Basic Authentication**.
The following tabs show two ways to provide credentials in a `cURL` command: a convenient shortcut and a manual method.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Simple Example (cURL shortcut)*

      The easiest way to send credentials with `cURL` is the ``-u`` flag. It automatically combines your username and password, Base64-encodes them, and adds the required ``Authorization`` header.

      ::

         curl -u username:password \
           -X POST \
           -H "Content-Type: application/vnd.api+json" \
           https://sms-out.didww.com/outbound_messages \
           -d '{
             "data": {
               "type": "outbound_messages",
               "attributes": {
                 "destination": "15551234567",
                 "source": "12125551234",
                 "content": "Hello World!"
               }
             }
           }'

   .. tab-item:: *Manual Header Construction*

      This method shows what the `-u` flag does behind the scenes.

          1. Combine credentials: ``username:password``
          2. Base64 encode the string: ``dXNlcm5hbWU6cGFzc3dvcmQ=``
          3. Add the result as an ``Authorization`` header: ``Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=``

      ::

         curl -X POST \
           -H "Content-Type: application/vnd.api+json" \
           -H "Authorization: Basic am9objpkb2U=" \
           https://sms-out.didww.com/outbound_messages \
           -d '{
             "data": {
               "type": "outbound_messages",
               "attributes": {
                 "destination": "15551234567",
                 "source": "12125551234",
                 "content": "Hello World!"
               }
             }
           }'

.. raw:: html

    <br>

.. _sms_out_spec_rate_limit:

Rate Limit
----------

Outbound SMS requests sent via HTTP OUT trunks are subject to a rate limit.

The maximum request rate for HTTP OUT trunks is **10 requests per second (RPS)**.

If this limit is exceeded, the API returns an :ref:`429 Too Many Requests response error <sms_out_spec_errors>`.

.. raw:: html

    <br>

.. _sms_out_spec_endpoints_headers:

Endpoints & Headers
-------------------

All API requests use the ``POST`` method and must be sent to a valid API endpoint with the required headers.

.. list-table::
   :widths: 25 55
   :header-rows: 1

   * -   Component
     -   Value
   * -   **Global Endpoint**
     -   ``https://sms-out.didww.com`` |br| (Use this for general-purpose requests.)
   * -   **Regional Endpoints**
     -   Use a regional endpoint for potentially lower latency:

         -   ``https://us.sms-out.didww.com`` (United States)
         -   ``https://nyc.us.sms-out.didww.com`` (New York)
         -   ``https://mia.us.sms-out.didww.com`` (Miami)
         -   ``https://lac.us.sms-out.didww.com`` (Los Angeles)
         -   ``https://eu.sms-out.didww.com`` (Europe)
         -   ``https://sg.sms-out.didww.com`` (Singapore)
   * -   **Request Paths**
     -   Append to your chosen endpoint:

         -   **Single SMS:** ``/outbound_messages``
         -   **Bulk SMS:** ``/bulk_outbound_messages``
   * -   **Content-Type Header**
     -   ``Content-Type: application/vnd.api+json``
   * -   **Authorization Header**
     -   ``Authorization: Basic <b64_value>``. See :ref:`Authentication <sms_out_spec_authentication>`.

.. raw:: html

    <br>

.. _sms_out_spec_sending:

Outbound SMS Examples
------------------------------

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Single SMS without source*

      .. note::

         When ``campaign_id`` is provided and ``source`` is omitted, DIDWW randomly selects one of the Sender IDs registered under that Sender ID Verification. In the DIDWW User Panel, the value used for ``campaign_id`` is displayed as **Campaign ID** on the verification details page. See :ref:`Sender ID Verification fields <sender_id_verification_fields>`.

      .. http:example:: curl

         POST /outbound_messages HTTP/1.1
         Host: sms-out.didww.com
         Content-Type: application/vnd.api+json
         Authorization: Basic

         {
           "data": {
             "type": "outbound_messages",
             "attributes": {
               "destination": "37041654321",
               "content": "Hello World!",
               "campaign_id": "1111aaa-1a1a-a1a1-aaaa-11aaaaa1111"
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "type": "outbound_messages",
             "id": "550e8400-e29b-41d4-a716-446655440000"
           }
         }

   .. tab-item:: *Single SMS*

      .. note::

         When ``source`` is present with a sender ID from the registered campaign, ``campaign_id`` is not required.

      .. http:example:: curl

         POST /outbound_messages HTTP/1.1
         Host: sms-out.didww.com
         Content-Type: application/vnd.api+json
         Authorization: Basic

         {
           "data": {
             "type": "outbound_messages",
             "attributes": {
               "destination": "37041654321",
               "source": "37041123456",
               "content": "Hello World!"
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "type": "outbound_messages",
             "id": "550e8400-e29b-41d4-a716-446655440000"
           }
         }

   .. tab-item:: *Bulk SMS*

      .. http:example:: curl

         POST /bulk_outbound_messages HTTP/1.1
         Host: sms-out.didww.com
         Content-Type: application/vnd.api+json
         Authorization: Basic

         {
           "data": {
             "type": "bulk_outbound_messages",
             "attributes": {
               "destination": ["37041654321", "37041654322"],
               "source": "37041123456",
               "content": "Hello World!"
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "type": "bulk_outbound_messages",
             "id": "2C4807D1-74E4-4639-BBC4-057402F052FF",
             "relationships": {
               "outbound_messages": {
                 "data": [
                   {"type": "outbound_messages", "id": "E34C1810-434B-4E64-AFD9-EC0568F324A9"},
                   {"type": "outbound_messages", "id": "B6A48E34-3219-407D-99E6-770CF524F611"}
                 ]
               }
             }
           }
         }

.. raw:: html

    <br>

.. _outbound_attributes:

Outbound SMS Attributes
^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 10 8 49
   :header-rows: 1

   * -   Attribute
     -   Required?
     -   Description
   * -   ``destination``
     -   Required
     -   Recipient’s number in **E.164 format**. For bulk requests, use an array of numbers. |br| (maximum **1000 numbers** per request)

         .. note:: If the destination region is not in your price list, you’ll receive a callback with :ref:`code_id: 2 <callback_error_codes_http>`.
   * -   ``source``
     -   Optional
     -   DID number to use as the sender ID (E.164 format).

         .. note:: The source DID must be authorized in your trunk’s **Source Address Settings**. |br| Otherwise, you’ll receive a callback with :ref:`code_id: 8 <callback_error_codes_http>`.
   * -   ``content``
     -   Required
     -   Message text (UTF-8). A single SMS supports up to **160 characters**.
   * -   ``campaign_id``
     -   Optional
     -   Campaign ID of a registered :ref:`Sender ID Verification <user_panel_sms_campaign>`.

.. raw:: html

    <br>

.. _sms_out_spec_callbacks:
.. _sms_callback_http:
.. _callback_dlr_event:

Status Callbacks
----------------

You can receive events related to your message processing status using the **Callback** mechanism.
See the Callback URL configuration in :ref:`Outbound SMS trunk settings <user_panel_sms_http_out_general_settings>`.

.. note::
   Configure your firewall to allow requests from the DIDWW callback IP ranges:

       - **IPv4:** ``46.19.208.0/21``
       - **IPv6:** ``2a01:ad00::/32``

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Message Status Callback*

      Sent after processing an outbound SMS.

      **Payload Example:**
      ::

         {
           "data": {
             "type": "outbound_message_callbacks",
             "id": "550e8400-e29b-41d4-a716-446655440000",
             "attributes": {
               "time_start": "2025-08-12T12:24:30.45Z",
               "time_end": "2025-08-12T12:24:31.15Z",
               "destination": "15551234567",
               "source": "12125551234",
               "status": "Success",
               "code_id": null,
               "fragments_sent": 1,
               "price": 0.0075
             }
           }
         }

      **Attributes:**

      .. list-table::
         :widths: 25 75
         :header-rows: 1

         * -   Attribute
           -   Description
         * -   ``time_start``
           -   Time message routing started (`ISO 8601 <https://tools.ietf.org/html/rfc3339#section-5.6>`_).
         * -   ``time_end``
           -   Time message processing finished (`ISO 8601 <https://tools.ietf.org/html/rfc3339#section-5.6>`_).
         * -   ``source``
           -   Sender ID of the message.
         * -   ``destination``
           -   Recipient’s number.
         * -   ``status``
           -   Processing status: ``Success``, ``Routing Error``, or ``Failed``.
         * -   ``fragments_sent``
           -   Number of fragments used.
         * -   ``price``
           -   Cost per message fragment.
         * -   ``code_id``
           -   Error code if status is not ``Success``. See :ref:`Callback Error Codes <sms_out_spec_errors>`.

   .. tab-item:: *DLR Event Callback*

      Sent from the carrier with the final delivery status (for example, ``DELIVERED``, ``FAILED``, or ``EXPIRED``).

      .. note::
         To enable DLR event notifications, contact support@didww.com.

      **Payload Example:**
      ::

         {
           "data": {
             "type": "dlr_event",
             "id": "550e8400-e29b-41d4-a716-446655440000",
             "attributes": {
               "status": "DELIVERED",
               "time_start": "2025-08-12T12:24:32.00Z"
             }
           }
         }

      **Attributes:**

      .. list-table::
         :widths: 15 65
         :header-rows: 1

         * -   Attribute
           -   Description
         * -   ``id``
           -   ID of the related outbound message |br| (matches the ``id`` from the corresponding ``outbound_message_callbacks``).
         * -   ``status``
           -   Final carrier status (e.g., ``DELIVERED``, ``FAILED``, ``EXPIRED``).
         * -   ``time_start``
           -   Time the DLR event was generated (`ISO 8601 <https://tools.ietf.org/html/rfc3339#section-5.6>`_).

.. raw:: html

    <br>

Callback Examples
^^^^^^^^^^^^^^^^^^

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Single SMS Callback*

      If you configure callbacks for your endpoint, the following attributes are returned for each outbound SMS.
      In some cases, a :ref:`DLR event callback <callback_dlr_event>` may also be sent with additional status information.

      .. list-table::
         :widths: 20 10 10 8 8 5 8 5
         :header-rows: 1

         * - Unique ID
           - Time Start
           - Time End
           - Source
           - Destination
           - Status
           - Fragments Sent
           - Price
         * - 83950010-3954-43a6-8419-c1417807672f
           - 2023-04-11 09:07:35
           - 2023-04-11 09:07:35
           - 447418350728
           - 447418356937
           - Success
           - 5
           - 0.0375

   .. tab-item:: *Bulk SMS Callback*

      When sending bulk SMS, you receive callbacks for every destination number with a unique ID.
      A :ref:`DLR event callback <callback_dlr_event>` may also be sent with final delivery details.

      .. list-table::
         :widths: 20 10 10 8 8 5 8 5
         :header-rows: 1

         * - Unique ID
           - Time Start
           - Time End
           - Source
           - Destination
           - Status
           - Fragments Sent
           - Price
         * - dc38aa6b-c454-438f-9761-e3bdea13bee0
           - 2023-04-11 09:14:30
           - 2023-04-11 09:14:31
           - 447418350728
           - 37067738955
           - Success
           - 1
           - 0.0075
         * - 8075ceco-9fb9-41b6-8580-dabbbb41f0e9
           - 2023-04-11 09:14:30
           - 2023-04-11 09:14:31
           - 447418350728
           - 447418356937
           - Success
           - 1
           - 0.0075

.. raw:: html

    <br>

.. _sms_out_spec_errors:

Handling Errors
---------------

API Error Responses
^^^^^^^^^^^^^^^^^^^

If your API request is malformed or unauthorized, the service returns an immediate error response.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *400 Bad Request*

    Returned when the request payload does not follow `JSON:API <https://jsonapi.org/format/>`_.

    .. code-block:: json

       {
         "errors": [
           {
             "title": "Bad Request",
             "detail": "Invalid request",
             "code": "400",
             "status": "400"
           }
         ]
       }

   .. tab-item:: *401 Unauthorized*

    Returned when the ``Authorization`` header is missing/invalid **or** the request comes from a non-allowed IP. See :ref:`Authentication <sms_out_spec_authentication>`.

    .. code-block:: json

       {
         "errors": [
           {
             "title": "Unauthorized",
             "detail": "Authorization failed",
             "code": "401",
             "status": "401"
           }
         ]
       }

   .. tab-item:: *429 Too Many Requests*

    Returned when the request rate exceeds the allowed :ref:`rate limit <sms_out_spec_rate_limit>`.

    .. code-block:: json

       {
         "errors": [
           {
             "title": "Too many requests",
             "detail": "too many requests in a given amount of time",
             "code": "429",
             "status": "429"
           }
         ]
       }

.. raw:: html

    <br>

.. _callback_error_codes_http:

Callback Error Codes and Retry Logic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Callback Error Codes*

      The ``code_id`` in a status callback provides specific details about a message failure.

      .. list-table::
         :widths: 20 80
         :header-rows: 1

         * -   Code
           -   Description
         * -   null
           -   Message was sent successfully
         * -   1, 3
           -   No routes found
         * -   2
           -   No rate found
         * -   4, 6
           -   Internal error
         * -   5
           -   SMS trunk is blocked
         * -   7
           -   Origination account is blocked
         * -   8
           -   SMS source address is not allowed
         * -   9
           -   SMS destination address is not allowed
         * -   10, 11
           -   SMS Campaign not found or blocked
         * -   100
           -   Insufficient balance
         * -   101
           -   All delivery attempts failed within the TTL
         * -   102
           -   No encoding available
         * -   103
           -   Max balance attempts reached
         * -   104
           -   Message defragmentation failed
         * -   105
           -   Routing failed

   .. tab-item:: *Callback Retry Logic*

      If your callback endpoint returns a **non-2xx** HTTP response or times out (**60 seconds**), the system will retry delivery up to **9** more times.

      .. csv-table::
         :header: "Callback Attempt", "Wait Interval"

         "2", "1 minute"
         "3", "10 minutes"
         "4", "30 minutes"
         "5", "1 hour"
         "6", "3 hours"
         "7", "6 hours"
         "8", "12 hours"
         "9", "1 day"
         "10", "2 days"


================
Logs & Analytics
================

Get clear insights with Logs & Analytics. Track communication metrics, analyze call and SMS logs, and export data to improve efficiency, ensure compliance, and make data-driven decisions.

----

.. grid::  1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`graph` **Statistics**
      :link: statistics/index
      :link-type: doc
      :text-align: left

      View performance metrics and filter voice and SMS traffic statistics for insights.

   .. grid-item-card:: :octicon:`report` **Reports**
      :link: reports/index
      :link-type: doc
      :text-align: left

      Generate detailed Voice and SMS traffic reports with grouping, metrics, and filters.

   .. grid-item-card:: :octicon:`file` **Call Logs**
      :link: call-logs/index
      :link-type: doc
      :text-align: left

      View, filter inbound and outbound call records.

   .. grid-item-card:: :octicon:`comment` **SMS Logs**
      :link: sms-logs/index
      :link-type: doc
      :text-align: left

      Track inbound and outbound SMS activity.

   .. grid-item-card:: :octicon:`download` **Exports**
      :link: exports/index
      :link-type: doc
      :text-align: left

      Create and download exports for call logs, SMS logs, DIDs, orders, and payments.



.. _inbound_cdr_logs:

=================
Inbound Call Logs
=================

Inbound call logs provide detailed records of inbound call activity. These logs are essential for monitoring, analysis, and troubleshooting.

----

Call Log Filters
================

Various filters are available to help you locate the exact call logs.

.. list-table::
   :header-rows: 1

   * - **Filter Name**
     - **Description**
   * - **Date / Time Start (UTC)**
     - Filter logs for specific time ranges: ``Today``, ``This week``, ``This month``, ``Previous month``, or ``Custom Range``.
   * - **Source**
     - Filter logs by specific source numbers using ``Equals`` or ``Contains``.
   * - **Destination DID**
     - Filter logs by specific DID numbers using ``Equals`` or ``Contains``.
   * - **Voice IN Trunk**
     - Filter logs based on specific Voice IN Trunks.
   * - **Trunk Group**
     - Filter logs based on specific Trunk Groups.
   * - **Capacity Group**
     - Filter logs based on specific Capacity Groups.
   * - **Status**
     - Filter logs by call status: ``Any Status``, ``Success``, ``Capacity Exceeded``, or ``Failed``.
   * - **Type**
     - Filter logs by service type: ``PSTN``, ``Toll-Free``, ``Metered Channels``, or ``CNAM IN``.
   * - **Call ID**
     - Filter logs by the system-generated Call ID using ``Equals`` or ``Contains``.

.. tip::

   You can filter multiple values in call log filters, such as source numbers,
   destination numbers, or other fields, by entering the values separated by commas
   (``,``) or spaces. For example, enter ``123,456`` or ``123 456`` to filter
   multiple entries in a single field.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Inbound Call Log Filters
   :width: 80%

   **Fig. 1.** Inbound Call Log Filters.

----

Call Log Fields
======================

The following fields are included in the inbound call logs:

.. list-table::
   :header-rows: 1

   * - **Field Name**
     - **Description**
   * - **Call ID**
     - The system-generated identifier for the call.
   * - **Date / Time Start (UTC)**
     - The time when DIDWW received the call.
   * - **Date / Time Connect (UTC)**
     - The time when the call was connected.
   * - **Date / Time End (UTC)**
     - The time when the call ended.
   * - **Status**
     - Indicates whether the call was successful or failed.
   * - **Source**
     - The originating source number of the call.
   * - **Source Name**
     - The caller’s name. If CNAM IN lookup is disabled, this field may be empty or show the source number.
   * - **Destination DID**
     - The DID number to which the call was routed.
   * - **Duration (sec)**
     - The duration of the call in seconds.
   * - **Attempt**
     - The routing attempt to deliver the call.
   * - **Response**
     - The SIP response code for the call. See: :ref:`SIP Response Codes <inbound_technical_sip_response_codes_in_call_logs>`.
   * - **Disconnect Initiator**
     - The party that disconnected the call (Origination or Destination).
   * - **Voice IN Trunk**
     - The trunk to which the call was routed.
   * - **Destination**
     - The full URI of the Voice IN Trunk.
   * - **Trunk Group**
     - The Trunk Group to which the Voice IN Trunk is assigned.
   * - **Capacity Group**
     - The channel group to which the DID number is assigned.
   * - **Toll-free (USD)**
     - The price for calls received on a Toll-Free DID number, in USD.
   * - **PSTN (USD)**
     - The price for PSTN forwarding, in USD.
   * - **Metered (USD)**
     - The price for the use of metered channels, in USD.
   * - **CNAM IN (USD)**
     - The price for CNAM IN lookup, in USD.
   * - **Total (USD)**
     - The total price of the call, in USD.
   * - **Call ID**
     - The system generated call ID.

.. admonition:: Billing Information

   Call charges are calculated based on the total call duration, including milliseconds.
   Any fraction of time that exceeds a full billing interval is automatically rounded up to the next interval.
   This means that even a few milliseconds beyond a complete interval are counted as a full additional interval for billing purposes.

   For example, when the billing increment is ``60/60``:

       - If a call lasts ``60.000`` seconds, it is billed as ``60`` seconds (one interval).
       - If a call lasts ``60.001`` seconds (where ``0.001`` represents milliseconds), it is billed as ``120`` seconds (two intervals).

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Inbound Call Logs.
   :width: 80%

   **Fig. 2.** Inbound Call Logs.


=========
Call Logs
=========

The **Call Logs** section provides a detailed record of all call activity, including inbound and outbound calls. You can perform the following tasks:

 - View call details, such as time, duration, source or destination numbers, and trunk used.
 - Filter logs by call direction (inbound or outbound).
 - Export logs in ``.csv`` format for further analysis or reporting.

To access Call Logs, go to the **Logs & Analytics** menu, select **Call Logs**, and then choose :ref:`Inbound <inbound_cdr_logs>` or :ref:`Outbound <outbound_cdr_logs>`.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :width: 80%

   **Fig. 1.** Call Logs.

.. note::
   - Logs can be exported as .csv files from the :ref:`Exports <exports>` section.
   - Logs are retained for the current month and the previous two months.

----

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`arrow-down` **Inbound Call Logs**
      :link: inbound-logs
      :link-type: doc
      :text-align: left

      Review and monitor inbound call activity, including caller details and timestamps.

   .. grid-item-card:: :octicon:`arrow-up` **Outbound Call Logs**
      :link: outbound-logs
      :link-type: doc
      :text-align: left

      Track outbound call records, view call results, and analyze dialing patterns.

.. toctree::
   :maxdepth: 1
   :hidden:

   Inbound Logs <inbound-logs>
   Outbound Logs <outbound-logs>


.. _outbound_cdr_logs:

==================
Outbound Call Logs
==================

Outbound call logs provide detailed records of outbound call activity. These logs are essential for monitoring, analysis, and troubleshooting.

----

Call Log Filters
================

Various filters are available to help you locate the exact call logs.

.. list-table::
   :header-rows: 1

   * - **Filter Name**
     - **Description**
   * - **Date / Time Start (UTC)**
     - Filter logs for specific time ranges: ``Today``, ``This week``, ``This month``, ``Previous month``, or ``Custom Range``.
   * - **Source**
     - Filter logs by specific source numbers using ``Equals`` or ``Contains``.
   * - **CLI**
     - Filter logs by specific Caller IDs using ``Equals`` or ``Contains``.
   * - **Destination Number**
     - Filter logs by specific destination numbers using ``Equals`` or ``Contains``.
   * - **Voice OUT Trunk**
     - Filter logs based on specific Voice OUT Trunks.
   * - **Status**
     - Filter logs by call status: ``Any Status``, ``Success``, ``Capacity Exceeded``, or ``Failed``.
   * - **Source Countries**
     - Filter logs by specific source countries. Multiple selections are allowed.
   * - **Destination Countries**
     - Filter logs by specific destination countries. Multiple selections are allowed.
   * - **Call Type**
     - Filter logs by call type: ``International``, ``Origin Based``, ``Local``, or ``Emergency``.
   * - **P-Charge-Info**
     - Filter logs by the p-charge-info header using ``Equals`` or ``Contains``. :ref:`Learn more about the P-Charge-Info header <service_termination_sip_details_p_charge_info>`.
   * - **Call ID**
     - Filter logs by the system-generated Call ID using ``Equals`` or ``Contains``.

.. tip::

   You can filter multiple values in call log filters, such as source numbers,
   destination numbers, or other fields, by entering the values separated by commas
   (``,``) or spaces. For example, enter ``123,456`` or ``123 456`` to filter
   multiple entries in a single field.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Outbound Call Log Filters.
   :width: 80%

   **Fig. 1.** Outbound Call Log Filters.

----

Call Log Fields
=================

The following fields are included in the outbound call logs:

.. list-table::
   :header-rows: 1

   * - **Field Name**
     - **Description**
   * - **Date / Time Start (UTC)**
     - The time when DIDWW received the call.
   * - **Date / Time Connect (UTC)**
     - The time when the call was connected.
   * - **Date / Time End (UTC)**
     - The time when the call ended.
   * - **Status**
     - Indicates whether the call was successful or failed.
   * - **Source**
     - The originating number from which the call was made.
   * - **CLI**
     - The Caller ID from which the call originated.
   * - **Destination Number**
     - The number to which the call was routed.
   * - **Call / Billing Duration (sec)**
     - The call duration in seconds and the billed duration in seconds.
   * - **Response**
     - The SIP response code for the call.
   * - **Voice OUT Trunk**
     - The trunk through which the call was routed.
   * - **Destination Country**
     - The country of the destination number.
   * - **Network**
     - The network of the destination number.
   * - **Call Type**
     - The type of call, determined by the destination country.
   * - **Rate (USD)**
     - The rate charged for the call in USD.
   * - **Charged (USD)**
     - The total charge for the call in USD.
   * - **P-Charge-Info**
     - The value sent in the P-Charge-Info header. :ref:`Learn more about the P-Charge-Info header <service_termination_sip_details_p_charge_info>`.
   * - **Call ID**
     - The system-generated identifier for the call.

.. admonition:: Billing Information

   Call charges are calculated based on the total call duration, including milliseconds.
   Any fraction of time that exceeds a full billing interval is automatically rounded up to the next interval.
   This means that even a few milliseconds beyond a complete interval are counted as a full additional interval for billing purposes.

   For example, when the billing increment is ``60/60``:

   - If a call lasts ``60.000`` seconds, it is billed as ``60`` seconds (one interval).
   - If a call lasts ``60.001`` seconds (where ``0.001`` represents milliseconds), it is billed as ``120`` seconds (two intervals).

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Outbound Call Logs.
   :width: 80%

   **Fig. 2.** Outbound Call Logs.



.. _exports:

.. |br| raw:: html

   <br />

=======
Exports
=======

Exports allow you to create, download, and review various data types from your account at DIDWW. The following items can be exported:

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`arrow-down` **Inbound Call Logs**
      :link: userpanel_exports_incalllogs
      :link-type: ref
      :text-align: left

      View and export logs of all inbound calls, including timestamps and caller details.

   .. grid-item-card:: :octicon:`arrow-up` **Outbound Call Logs**
      :link: userpanel_exports_outcalllogs
      :link-type: ref
      :text-align: left

      Review and export outbound call records with duration, status, and recipient information.

   .. grid-item-card:: :octicon:`arrow-down` **Inbound SMS Logs**
      :link: userpanel_exports_insmslogs
      :link-type: ref
      :text-align: left

      Monitor inbound SMS activity with sender details, message content, and timestamps.

   .. grid-item-card:: :octicon:`arrow-up` **Outbound SMS Logs**
      :link: userpanel_exports_outsmslogs
      :link-type: ref
      :text-align: left

      Export outbound SMS data including delivery status, recipients, and message history.

   .. grid-item-card:: :octicon:`number` **DID Numbers**
      :link: userpanel_exports_didnumbers
      :link-type: ref
      :text-align: left

      Access and export your DID numbers, including assignment and routing details.

   .. grid-item-card:: :octicon:`file` **Orders**
      :link: userpanel_exports_orders
      :link-type: ref
      :text-align: left

      Review and export order history, including status and purchase details.

   .. grid-item-card:: :octicon:`credit-card` **Payments**
      :link: userpanel_exports_payments
      :link-type: ref
      :text-align: left

      View and export payment transactions with amounts, dates, and payment methods.

To create an export click on "Create Export" button and select the required export type from the dropdown menu. 

.. figure:: https://doc.didww.com/_images/fig1.png
    :figclass: align-center

    **Fig. 1.** "Exports" section.

----

.. _userpanel_exports_incalllogs:

Inbound call logs
=================

The Inbound Call Logs export functionality allows you to generate a report for inbound call logs, with the following additional filters available for customization:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Source**
     - Filters call logs by the source (calling) number.
   * - **Destination DID**
     - Filters call logs by the destination number.
   * - **Voice IN trunk(s)**
     - Filters call logs by the selected Voice IN trunk(s).
   * - **Trunk group(s)**
     - Filters call logs by the selected Trunk group(s).
   * - **Capacity group(s)**
     - Filters call logs by the selected Capacity group(s).
   * - **Status**
     - Filters call logs by the status of the call. The following statuses can be selected from the dropdown menu:

        - **Any Status** - Filters all call logs regardless of the call status.
        - **Success** - Filters call logs of all successful calls.
        - **Capacity Exceeded** - Filters call logs that failed due to insufficient capacity.
        - **Failed** - Filters call logs of all failed calls.
   * - **Overload Reason**
     - Is available if Status **Capacity Exceeded** is selected. Filters call logs based on the capacity overload reason. The following reasons can be selected from the dropdown menu:

        - **Capacity exceeded - All** - Filters all call logs that failed due to insufficient capacity.
        - **Dedicated channels capacity exceeded** - Filters call logs that failed due to insufficient :ref:`dedicated capacity <flexible_capacity>`.
        - **Shared channels capacity exceeded** - Filters call logs that failed due insufficient shared capacity.
        - **Metered channels capacity exceeded** - Filters call logs that failed due to insufficient metered capacity.
   * - **Billing type(s)**
     - Filters call logs by the billing type(s). The following type(s) can be selected from the dropdown menu:

        - **PSTN** - Filters call logs that contain PSTN charges.
        - **Toll-free** - Filters call logs that contain Toll-free charges.
        - **Metered Channels** - Filters call logs that contain Metered Channels charges.
        - **CNAM Lookup** - Filters call logs that contain CNAM Lookup charges.
   * - **Call ID**
     - Filters call logs by the system generated Call ID.

  
.. figure:: https://doc.didww.com/_images/fig2.png
    :figclass: align-center

    **Fig. 2.** "Export Inbound Call Logs" creation dialog.

----

.. _userpanel_exports_outcalllogs:    

Outbound call logs
==================
    
The Outbound Call Logs export functionality allows you to generate a report for outbound call logs, with the following additional filters available for customization:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Source**
     - Filters call logs by the source (calling) number.
   * - **CLI**
     - Filters call logs by the source (calling) number. CLI may be different if the source number replacement is performed by DIDWW.
   * - **Destination number**
     - Filters call logs by the destination number.
   * - **Voice OUT trunk(s)**
     - Filters call logs by the selected Voice OUT trunk(s).
   * - **Status**
     - Filters call logs by the status of the call. The following statuses can be selected from the dropdown menu:

        - **Any Status** - Filters all call logs regardless of the call status.
        - **Success** - Filters call logs of all successful calls.
        - **Capacity Exceeded** - Filters call logs that failed due to insufficient capacity.
        - **Failed** - Filters call logs of all failed calls.
   * - **Source countries**
     - Filters call logs by the selected source (calling) countries.
   * - **Destination countries**
     - Filters call logs by the selected destination (called) countries.
   * - **Call types**
     - Filters call logs by the selected type(s). The following types can be selected from the dropdown menu:

        - **Any** - Filters all call logs regardless of the type.
        - **Origin Based** - Filters call logs by the origin-based type.
        - **Local** - Filters call logs by the local type.
        - **International** - Filters call logs by the international type.
   * - **P-Charge-Info**
     - Filters call logs by the P-Charge-Info. :ref:`Learn more about the P-Charge-Info header <service_termination_sip_details_p_charge_info>`.
   * - **Call ID**
     - Filters call logs by the system generated Call ID.

  
.. figure:: https://doc.didww.com/_images/fig3.png
    :figclass: align-center

    **Fig. 3.** "Export Outbound Call Logs" creation dialog.

----

.. _userpanel_exports_insmslogs:

Inbound SMS logs
================

The Inbound SMS Logs export functionality allows you to generate a report for inbound SMS logs, with the following additional filters available for customization:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Source address**
     - Filters SMS logs by the source (sender) number.
   * - **Destination address**
     - Filters SMS logs by the destination (receiver) number.
   * - **SMS trunk(s)**
     - Filters SMS logs by the selected SMS trunk(s).
   * - **Status**
     - Filters SMS logs by the delivery status. The following statuses can be selected from the dropdown menu:

        - **Any status** - Filters all SMS logs regardless of the delivery status.
        - **Success** - Filters SMS logs that were successfully delivered.
        - **Failed** - Filters SMS logs that failed to be delivered.
   * - **Trunk type(s)**
     - Filters SMS logs by the trunk type(s). The following types can be selected from the dropdown menu:

        - **Email** - Filters SMS logs that were received to email trunk type.
        - **HTTP IN** - Filters SMS logs that were received to HTTP IN trunk type.
        - **SMPP ESME** - Filters SMS logs that were received to SMPP ESME trunk type.
        - **SMPP SMSC** - Filters SMS logs that were received to SMPP SMSC trunk type.
   * - **SMS ID**
     - Filters SMS logs by the SMS ID.

.. figure:: https://doc.didww.com/_images/fig4.png
    :figclass: align-center

    **Fig. 4.** "Export Inbound SMS Logs" creation dialog.

----
    
.. _userpanel_exports_outsmslogs:

Outbound SMS logs
=================

The Outbound SMS Logs export functionality allows you to generate a report for outbound SMS logs, with the following additional filters available for customization:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Source address**
     - Filters SMS logs by the source (sender) number.
   * - **Destination address**
     - Filters SMS logs by the destination (receiver) number.
   * - **SMS trunk(s)**
     - Filters SMS logs by the selected SMS trunk(s).
   * - **Status**
     - Filters SMS logs by the delivery status. The following statuses can be selected from the dropdown menu:

        - **Any status** - Filters all SMS logs regardless of the delivery status.
        - **Success** - Filters SMS logs that were successfully delivered.
        - **Failed** - Filters SMS logs that failed to be delivered.
        - **Routing Error** - Filters SMS logs that failed to be delivered due to a routing error.
        - **Queued** - Filters SMS logs that are queued to be delivered.
        - **In Progress** - Filters SMS logs that are in process of delivery.
   * - **Service Type**
     - Filters SMS logs by the service type. The following type(s) can be selected from the dropdown menu:

        - **A2P** - Filters SMS logs by the Application to Person (A2P) service type.
        - **P2P** - Filters SMS logs by the Person to Person (P2P) service type.
   * - **SMS campaign(s)**
     - Filters SMS logs by the selected SMS campaign(s).

.. figure:: https://doc.didww.com/_images/fig5.png
    :figclass: align-center

    **Fig. 5.** "Export Outbound SMS Logs" creation dialog.

----

.. _userpanel_exports_didnumbers:

DID Numbers
===========

The DID Numbers export functionality allows you to generate a report for the owned DID numbers by the account, with the following additional filters available for customization:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Quick Filter**
     - Filters DID numbers by pre-defined parameters:

        - **Active** - Filters DID numbers which are active.
        - **Not Configured** - Filters DID numbers which are not configured.
   * - **DID Number**
     - Filters DID numbers by the specified numbers. Enter comma separated numbers to search for multiple DIDs (e.g. ``+35319609036,+35319600837``).
   * - **Description**
     - Filters DID numbers by the description.
   * - **Country**
     - Filters DID numbers by country.
   * - **Feature**
     - Filters DID numbers by the feature. The following features can be selected from the dropdown menu:

        - **Any Feature** - Filters DID numbers regardless of associated features.
        - **Voice IN** - Filters DID numbers with Voice IN feature.
        - **Voice OUT** - Filters DID numbers with Voice OUT feature.
        - **T.38** - Filters DID numbers with T.38 (Fax) feature.
        - **SMS IN** - Filters DID numbers with SMS IN feature.
        - **SMS OUT P2P** - Filters DID numbers with Person to Person (P2P) SMS OUT feature.
        - **SMS OUT A2P** - Filters DID numbers with Application to Person (A2P) SMS OUT feature.
        - **Emergency Calling** - Filters DID numbers with emergency calling feature.
        - **CNAM OUT** - Filters DID numbers with CNAM OUT feature.
   * - **Order ref**
     - Filters DID numbers by the order reference number.
   * - **Voice trunk**
     - Filters DID numbers by the selected voice trunk.
   * - **SMS trunk**
     - Filters DID numbers by the selected SMS trunk.
   * - **Capacity pool**
     - Filters DID numbers by the selected capacity pool.
   * - **Verification ref**
     - Filters DID numbers by the verification reference number.
   * - **Identity**
     - Filters DID numbers by the selected identity.
   * - **Number types**
     - Filters DID numbers by the selected number type. The following types can be selected from the dropdown menu:

        - **Global / UIFN** - Filters DID numbers by the Global / UIFN type.
        - **Local** - Filters DID numbers by the Local type.
        - **Mobile** - Filters DID numbers by the Mobile type.
        - **National** - Filters DID numbers by the National type.
        - **Shared cost** - Filters DID numbers by the Shared cost type.
        - **Toll-free** - Filters DID numbers by the Toll-free type.
   * - **Address**
     - Filters DID numbers by the assigned address.
   * - **Regulatory area**
     - Filters DID numbers by the regulatory area.

.. figure:: https://doc.didww.com/_images/fig6.png
    :figclass: align-center

    **Fig. 6** "Export DID Numbers" creation dialog.

----

.. _userpanel_exports_orders:

Orders
=======

The **Orders** export feature allows you to generate a report of all orders created on your account. You can customize the export by applying the following filters:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Date**
     - Filters orders by the selected time period.
   * - **Reference**
     - Filters orders by the selected reference number.
   * - **Status**
     - Filter by **Completed**, **Canceled**, or **Pending**:

        - **Completed** - Filter for completed items.
        - **Canceled** - Filter for canceled items.
        - **Pending** - Filter for pending items.
   * - **Refunded**
     - Filters order by the refund status **Yes** or **No**.

.. figure:: https://doc.didww.com/_images/fig7.png
   :figclass: align-center
   :alt: Export Orders dialog.

   **Fig. 7.** Export Orders dialog box.

----

.. _userpanel_exports_payments:

Payments
========

The Payments export functionality allows you to generate a report for all payments created on the account, with the following additional filters available for customization:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Status**
     - Filters payments by the status of the payment. The following statuses can be selected from the dropdown menu:

        -   **Completed** - Filters completed payments.
        -   **Action Required** - Filters payments that require additional action.
        -   **Pending** - Filters pending payments.
        -   **Canceled** - Filters cancelled payments.

  
.. figure:: https://doc.didww.com/_images/fig8.png
    :figclass: align-center

    **Fig. 8** "Export Payments" creation dialog.


.. _userpanel_reports:

Reports
=======

The Reports page helps you analyze your Voice and SMS traffic in one place.

Reports are useful when you want to monitor service usage, investigate changes in traffic patterns, evaluate call and messaging performance, or review charges related to your Voice and SMS activity.
By combining predefined grouping options with available filters, the Reports page helps you focus on the data that is most relevant to your analysis.

----

.. _userpanel_reports_voice_in:

Inbound Voice
-------------

Use the Inbound Voice tab to analyze inbound call performance.

.. figure:: https://doc.didww.com/_images/fig1.png
    :figclass: align-center

    **Fig. 1.** The "Inbound Voice" tab.

Grouping options
~~~~~~~~~~~~~~~~

The available grouping options are predefined. You can select one of the following options:

.. list-table::
   :header-rows: 1
   :widths: 30 75

   * - **Grouping option**
     - **Description**
   * - **DID Number**
     - Groups data by the DID number that received the inbound call.
   * - **Voice IN Trunk**
     - Groups data by the Inbound Voice trunk that handled the inbound call.
   * - **Trunk Group**
     - Groups data by the trunk group associated with the inbound call.
   * - **DID Country**
     - Groups data by the country of the DID number that received the inbound call.

Metrics
~~~~~~~

.. note:: The first column in the report table changes based on the selected grouping option.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Metric**
     - **Description**
   * - **Calls Count**
     - The total number of calls received during the selected period.
   * - **Total Duration**
     - The total duration of all calls, in minutes.
   * - **ACD (Average Call Duration)**
     - The average call duration, calculated by dividing the total duration by the number of calls.
   * - **ASR (Answer-Seizure Ratio)**
     - The percentage of successfully connected calls out of the total call attempts.
   * - **PSTN Charged**
     - Charges for calls routed through PSTN trunks.
   * - **Metered Charged**
     - Usage-based charges for services billed per minute.
   * - **Toll-free Charged**
     - Charges for toll-free services.
   * - **CNAM IN Charged**
     - Charges for CNAM lookup services.
   * - **Total Charged**
     - The total amount charged for inbound voice traffic.

Available filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 27 75

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters data by the selected timeframe: 24 hours, 7 days, 30 days, 60 days, or 90 days.
   * - **DID Number**
     - Filters data by the selected DID number.
   * - **Type**
     - Filters data by the selected type: PSTN, Toll-free, Metered Channels, or CNAM Lookup.
   * - **DID Country**
     - Filters data by the selected country.
   * - **Voice IN Trunk**
     - Filters data by the selected Inbound Voice trunk.
   * - **Trunk Group**
     - Filters data by the selected trunk group.

----

.. _userpanel_reports_voice_out:

Outbound Voice
--------------

Use the Outbound Voice tab to analyze outbound call performance.

.. figure:: https://doc.didww.com/_images/fig2.png
    :figclass: align-center

    **Fig. 2.** The "Outbound Voice" tab.

Grouping options
~~~~~~~~~~~~~~~~

The available grouping options are predefined. You can select one of the following options:

.. list-table::
   :header-rows: 1
   :widths: 34 75

   * - **Grouping option**
     - **Description**
   * - **Destination Country**
     - Groups data by the country of the dialed destination number.
   * - **Voice OUT Trunk**
     - Groups data by the Outbound Voice trunk used for the outbound call.
   * - **P-Charge-Info**
     - Groups data by the value of the ``P-Charge-Info`` header.

Metrics
~~~~~~~

.. note:: The first column in the report table changes based on the selected grouping option.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Metric**
     - **Description**
   * - **Calls Count**
     - The total number of calls made during the selected period.
   * - **Total Duration**
     - The total duration of all calls, in minutes.
   * - **ACD (Average Call Duration)**
     - The average call duration, calculated by dividing the total duration by the number of calls.
   * - **ASR (Answer-Seizure Ratio)**
     - The percentage of successfully connected calls out of the total call attempts.
   * - **International Cost**
     - Charges for calls made through international routes.
   * - **Origin-based Cost**
     - Charges for calls made through origin-based routes.
   * - **Local Cost**
     - Charges for calls made through local routes.
   * - **Emergency Cost**
     - Charges for calls made to emergency numbers.
   * - **Total Charge**
     - The total amount charged for outbound calls.

Available filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters data by the selected timeframe: 24 hours, 7 days, 30 days, 60 days, or 90 days.
   * - **Destination Country**
     - Filters data by the country of the dialed destination number.
   * - **Voice OUT Trunk**
     - Filters data by the selected Outbound Voice trunk.
   * - **Call Type**
     - Filters data by the selected call type: International, Origin-based, Local, or Emergency.
   * - **P-Charge-Info**
     - Filters data by the ``P-Charge-Info`` header value. :ref:`Learn more about the P-Charge-Info header <service_termination_sip_details_p_charge_info>`.

----

.. _userpanel_reports_sms_in:

Inbound SMS
-----------

Use the Inbound SMS tab to analyze inbound SMS performance.

.. figure:: https://doc.didww.com/_images/fig3.png
    :figclass: align-center

    **Fig. 3.** The "Inbound SMS" tab.

Grouping options
~~~~~~~~~~~~~~~~

The available grouping options are predefined. You can select one of the following options:

.. list-table::
   :header-rows: 1
   :widths: 27 75

   * - **Grouping option**
     - **Description**
   * - **Destination Address**
     - Groups data by the destination address that received the SMS message.
   * - **SMS IN Trunk**
     - Groups data by the Inbound SMS trunk that received the SMS message.
   * - **DID Country**
     - Groups data by the country of the DID number that received the SMS message.

Metrics
~~~~~~~

.. note:: The first column in the report table changes based on the selected grouping option.

.. list-table::
   :header-rows: 1
   :widths: 22 75

   * - **Metric**
     - **Description**
   * - **Total SMS Received**
     - The total number of SMS messages received during the selected period.
   * - **Successful**
     - The total number of successfully delivered SMS messages during the selected period.
   * - **Delivery Rate**
     - The percentage of successfully delivered SMS messages out of the total received SMS messages.
   * - **Total SMS Cost**
     - The total cost for received SMS messages.

Available filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters data by the selected timeframe: 24 hours, 7 days, 30 days, 60 days, or 90 days.
   * - **Destination Address**
     - Filters data by the number that received the SMS message.
   * - **SMS IN Trunk**
     - Filters data by the selected Inbound SMS trunk.
   * - **DID Country**
     - Filters data by the selected country.

----

.. _userpanel_reports_sms_out:

Outbound SMS
------------

Use the Outbound SMS tab to analyze outbound SMS performance.

.. figure:: https://doc.didww.com/_images/fig4.png
    :figclass: align-center

    **Fig. 4.** The "Outbound SMS" tab.

Grouping options
~~~~~~~~~~~~~~~~

The available grouping options are predefined. You can select one of the following options:

.. list-table::
   :header-rows: 1
   :widths: 29 75

   * - **Grouping option**
     - **Description**
   * - **Source Address**
     - Groups data by the source address that sent the SMS message.
   * - **Destination Country**
     - Groups data by the country of the destination number.
   * - **SMS OUT Trunk**
     - Groups data by the Outbound SMS trunk used to send the SMS message.
   * - **A2P Campaign**
     - Groups data by the A2P Campaign used for the SMS message.

Metrics
~~~~~~~

.. note:: The first column in the report table changes based on the selected grouping option.

.. list-table::
   :header-rows: 1
   :widths: 23 75

   * - **Metric**
     - **Description**
   * - **Total SMS Sent**
     - The total number of SMS messages sent during the selected period.
   * - **Successful**
     - The total number of successfully delivered SMS messages during the selected period.
   * - **Delivery Rate**
     - The percentage of successfully delivered SMS messages out of the total sent SMS messages.
   * - **Total SMS Cost**
     - The total cost for sent SMS messages.

Available filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters data by the selected timeframe: 24 hours, 7 days, 30 days, 60 days, or 90 days.
   * - **Service Type**
     - Filters data by the selected service type: A2P or P2P.
   * - **A2P Campaign**
     - Filters data by the selected A2P campaign.
   * - **Source Address**
     - Filters data by the number that sent the SMS message.
   * - **Destination Address**
     - Filters data by the number that received the SMS message.
   * - **Destination Country**
     - Filters data by the country of the destination number.
   * - **SMS OUT Trunk**
     - Filters data by the selected Outbound SMS trunk.

.. _inbound_logs:

================
Inbound SMS Logs
================

Inbound SMS logs provide detailed records of inbound SMS activity. These logs are essential for monitoring, analysis, and troubleshooting.

----

Inbound SMS Log Filters
=======================

Various filters are available to help you locate the exact SMS logs.

.. list-table:: SMS Log Filters
   :header-rows: 1

   * - **Filter Name**
     - **Description**
   * - **Time Received (UTC)**
     - Filter logs for specific time ranges: ``Today``, ``This week``, ``This month``, ``Previous month``, or ``Custom Range``.
   * - **Destination Address**
     - Filter logs by specific destination numbers using ``Equals`` or ``Contains``.
   * - **Status**
     - Filter logs by SMS status: ``Any Status``, ``Success``, or ``Failed``.
   * - **Trunk Type**
     - Filter logs by trunk types: ``Email``, ``HTTP IN``, ``SMPP ESME``, or ``SMPP SMSC``.
   * - **Source Address**
     - Filter logs by specific source numbers using ``Equals`` or ``Contains``.
   * - **SMS Trunk**
     - Filter logs by specific trunks.
   * - **SMS ID**
     - Filter logs by the unique SMS ID assigned to each message.

.. tip::

   You can filter multiple values in SMS log filters, such as source or destination addresses,
   by entering the values separated by commas (`,`), or spaces. For example, enter ``123,456`` or ``123 456``
   to filter multiple entries in a single field.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Inbound SMS Log Filters.
   :width: 80%

   **Fig. 1.** Inbound SMS Log Filters.

----

Inbound SMS Logs
================

The following fields are included in the inbound SMS logs:

.. list-table:: Inbound SMS Log Descriptions
   :header-rows: 1

   * - **Field Name**
     - **Description**
   * - **Time Received (UTC)**
     - The time when DIDWW received the SMS message.
   * - **Time Sent (UTC)**
     - The time when the SMS message was sent to the user’s trunk.
   * - **Status**
     - Indicates whether the SMS was successfully delivered or failed.
   * - **Reason**
     - If delivery failed, this field shows the reason for the failure.
   * - **Source Address**
     - The source number from which the SMS was received.
   * - **Destination Address**
     - The destination number (DID) to which the SMS was sent.
   * - **Trunk / Type**
     - The trunk to which the SMS was sent.
   * - **Destination**
     - The final destination of the trunk (e.g., IP address for *SMPP* trunks or email for *SMS to Email*).
   * - **Fragments**
     - Displays the number of SMS fragments in the format: ``1/x``, ``2/x``, etc.
   * - **Attempt**
     - The number of attempts to deliver the SMS to the user’s end destination.
   * - **SMS ID**
     - The unique identifier assigned to each SMS message.
   * - **Billed Fragments**
     - The number of SMS fragments that were billed.
   * - **Charged (USD)**
     - The cost of the SMS message.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Inbound SMS Logs.
   :width: 80%

   **Fig. 2.** Inbound SMS Logs.

.. note::

   - Incoming SMS messages are billed if they reach DIDWW but fail to deliver to the user's destination.
   - If a DID number is not assigned to an SMS trunk, incoming messages will not be billed.

========
SMS Logs
========

The **SMS Logs** section provides a detailed record of all SMS activity, including inbound and outbound messages. You can perform the following tasks:

 - View SMS details, such as the time sent or received, forwarding address, and source or destination numbers.
 - Filter logs by SMS direction (inbound or outbound).
 - Export logs in ``.csv`` format for reporting or further analysis.

To access SMS Logs, go to the **Logs & Analytics** menu, select **SMS Logs**, and then choose :ref:`Inbound <inbound_logs>` or :ref:`Outbound <outbound_logs>`.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center

   **Fig. 1.** SMS Logs.

.. note::
   - Logs can be exported as .csv files from the :ref:`Exports <exports>` section.
   - Logs are retained for the current month and the previous two months.

----

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`arrow-down` **Inbound SMS Logs**
      :link: inbound-logs
      :link-type: doc
      :text-align: left

      Monitor inbound SMS messages, including sender details and timestamps.

   .. grid-item-card:: :octicon:`arrow-up` **Outbound SMS Logs**
      :link: outbound-logs
      :link-type: doc
      :text-align: left

      Review outbound SMS activity with delivery status, recipient details, and timestamps.

.. toctree::
   :maxdepth: 1
   :hidden:

   Inbound SMS Logs <inbound-logs>
   Outbound SMS Logs <outbound-logs>


.. _outbound_logs:

=================
Outbound SMS Logs
=================

Outbound SMS Logs provide detailed records of outbound SMS activity. These logs are essential for monitoring, analysis, and troubleshooting.

----

Outbound SMS Log Filters
========================

Various filters are available to help you locate the exact SMS logs.

.. list-table:: SMS Log Filters
   :header-rows: 1

   * - **Filter Name**
     - **Description**
   * - **Date / Time (UTC)**
     - Filter logs for specific time ranges: ``Today``, ``This week``, ``This month``, ``Previous month``, or ``Custom Range``.
   * - **Source Address**
     - Filter logs by specific source numbers using ``Equals`` or ``Contains``.
   * - **Destination Address**
     - Filter logs by specific destination numbers using ``Equals`` or ``Contains``.
   * - **SMS Trunk**
     - Filter logs by specific trunks.
   * - **Status**
     - Filter logs by SMS status: ``Any Status``, ``Success``, ``Failed``, ``Routing Error``, ``Queued``, or ``In Progress``.
   * - **Service Type**
     - Filter logs by the type of SMS: ``A2P`` or ``P2P``.
   * - **A2P Campaign**
     - Filter logs by specific SMS campaigns.

.. tip::

   You can filter multiple values in SMS log filters, such as source or destination addresses,
   by entering the values separated by commas (`,`), or spaces. For example, enter ``123,456`` or ``123 456``
   to filter multiple entries in a single field.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Outbound SMS Log Filters.
   :width: 80%

   **Fig. 1.** Outbound SMS Log Filters.

----

Outbound SMS Logs
=================

The following fields are included in the outbound SMS logs:

.. list-table:: Outbound SMS Log Descriptions
   :header-rows: 1

   * - **Field Name**
     - **Description**
   * - **Date / Time (UTC)**
     - The date and time when the SMS message was sent.
   * - **Status**
     - Indicates whether the SMS was successfully delivered or failed.
   * - **Reason**
     - If delivery failed, this field shows the reason for the failure.
   * - **Source Address**
     - The source number from which the SMS was sent.
   * - **Destination Address**
     - The destination number to which the SMS was sent.
   * - **Trunk / Type**
     - The trunk and trunk type through which the SMS was sent.
   * - **A2P Campaign**
     - The specific campaign associated with the SMS message.
   * - **Billed Fragments**
     - The number of SMS fragments that were billed.
   * - **Charged (USD)**
     - The total charge for the billed SMS fragments.

.. note::

   - Billing is based on SMS fragments, not on the message as submitted. If a
     long SMS is split into multiple fragments, each fragment is billed
     separately. The **Billed Fragments** field shows the number of fragments
     included in the charge.
   - The list of error codes can be found
     :ref:`here <callback_error_codes_http>`.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Outbound SMS Logs.
   :width: 80%

   **Fig. 2.** Outbound SMS Logs.


.. |br| raw:: html

   <br />

.. _userpanel_statistics:

==========
Statistics
==========

Statistics allow you to view different graphs that reflect the performance of your Voice and SMS traffic.

----

.. raw:: html

   <br>

Inbound Voice
=============

To analyze your inbound call performance, use the various metrics and filters available in the **Inbound Voice** tab.

.. figure:: https://doc.didww.com/_images/fig1.png
    :figclass: align-center
    :alt: Inbound Voice tab.
    :width: 80%

    **Fig. 1.** Inbound Voice tab.

Metrics
~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Metric**
     - **Description**
   * - **Concurrent Calls**
     - Displays active calls, updated every minute. Note: Very short calls may not be counted.
   * - **ACD (Average Call Duration)**
     - Shows the average duration of calls, calculated by dividing the total call time by the number of successful calls for each interval. |br|
       Interval length depends on your “Group By” settings.
   * - **ASR (Answer-Seizure Ratio)**
     - Represents the percentage of successful calls out of all call attempts for each interval. Interval length is determined by your “Group By” settings.
   * - **Total Call Count**
     - Indicates the number of calls sent to customers, calculated per interval defined by the “Group By” settings.
   * - **Total Call Duration (Minutes)**
     - Displays the total duration of calls sent to customers, calculated per interval based on the “Group By” settings.
   * - **Total Cost**
     - Shows the aggregated cost of calls for each interval. |br|
       Note: The same call may incur multiple charges due to different associated services (e.g., PSTN, Toll-free, Metered, CNAM IN).

Available Filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters charts by the selected timeframe (options: 24 hours, 7 days, 30 days, 60 days, 90 days).
   * - **DID Number**
     - Filters charts by the selected DID number.
   * - **DID Country**
     - Filters charts by the selected country.
   * - **Voice IN Trunk**
     - Filters charts by the selected Voice IN trunk.
   * - **Trunk Group**
     - Filters charts by the selected trunk group.
   * - **Type**
     - Filters charts by the selected type (options: PSTN, Toll-free, Metered Channels, CNAM Lookup).

----

.. raw:: html

   <br>

.. _userpanel_statistics_voice_out:

Outbound Voice
==============

To analyze your outbound call performance, use the various metrics and filters provided in the **Outbound Voice** tab.

.. figure:: https://doc.didww.com/_images/fig2.png
    :figclass: align-center
    :alt: Outbound Voice tab.
    :width: 80%

    **Fig. 2.** Outbound Voice tab.

Metrics
~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Metric**
     - **Description**
   * - **Concurrent Calls**
     - Displays active calls, with data measured once per minute. Note: Some short calls may not be counted.
   * - **ACD (Average Call Duration)**
     - Shows the average call duration, calculated by dividing the total call time by the number of successful calls for each interval. |br| Interval length depends on the "Group By" settings.
   * - **ASR (Answer-Seizure Ratio)**
     - Represents the percentage of successful calls out of all call attempts for each interval. Interval length depends on the "Group By" settings.
   * - **Total Call Count**
     - Indicates the number of calls received from the customer, calculated per interval defined by the "Group By" settings.
   * - **Total Call Duration (Minutes)**
     - Shows the total duration of calls received from the customer, calculated per interval based on the “Group By” settings.
   * - **Total Cost**
     - Represents the aggregated cost of calls for each interval. |br| Note: Calls are charged based on their call types (International, Origin based, Local, Emergency).

Available Filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters charts by the selected timeframe (options: 24 hours, 7 days, 30 days, 60 days, 90 days).
   * - **Destination Country**
     - Filters charts by the selected destination country.
   * - **Voice OUT Trunk**
     - Filters charts by the selected Voice OUT trunk.
   * - **Call Type**
     - Filters charts by the selected call type (options: International, Origin based, Local, Emergency).
   * - **P-Charge-Info**
     - Filter charts by the p-charge-info header. :ref:`Learn more about the P-Charge-Info header <service_termination_sip_details_p_charge_info>`.

----

.. raw:: html

   <br />

Inbound SMS
===========

To analyze your inbound SMS performance, use the various metrics and filters provided in the **Inbound SMS** tab.

.. figure:: https://doc.didww.com/_images/fig3.png
    :figclass: align-center
    :alt: Inbound SMS tab.
    :width: 80%

    **Fig. 3.** Inbound SMS tab.

Metrics
~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 10 80

   * - **Metric**
     - **Description**
   * - **Total SMS Received**
     - Represents the count of SMS messages received by the customer within the SMS IN service, calculated for each interval as defined in the “Group By” setting.
   * - **Total SMS Cost**
     - Represents the total cost of SMS messages received by the customer within the SMS IN service, calculated for each interval as defined in the “Group By” setting.
   * - **Delivery Rate (%)**
     - The percentage of successfully delivered messages out of the total messages, calculated for each interval as defined in the “Group By” setting.

Available Filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters charts by the selected timeframe (options: 24 hours, 7 days, 30 days, 60 days, 90 days).
   * - **Destination Address**
     - Filters charts by the selected destination address.
   * - **SMS IN Trunk**
     - Filters charts by the selected SMS IN trunk.
   * - **DID Country**
     - Filters charts by the selected DID country.

----

.. raw:: html

   <br />

Outbound SMS
============

To analyze your outbound SMS performance, use the various metrics and filters provided in the **Outbound SMS** tab.

.. figure:: https://doc.didww.com/_images/fig4.png
    :figclass: align-center
    :alt: Outbound SMS tab.
    :width: 80%

    **Fig. 4.** Outbound SMS tab.

Metrics
~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 13 80

   * - **Metric**
     - **Description**
   * - **Total SMS Sent**
     - Represents the count of SMS messages sent by the customer using the SMS OUT service, calculated for each interval as defined in the “Group By” setting.
   * - **Total SMS Cost**
     - Represents the cost of SMS messages sent by the customer using the SMS OUT service, calculated for each interval as defined in the “Group By” setting.
   * - **Delivery Rate (%)**
     - The percentage of successfully delivered messages out of the total messages sent, calculated for each interval as defined in the “Group By” setting.

Available Filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters charts by the selected timeframe (options: 24 hours, 7 days, 30 days, 60 days, 90 days).
   * - **Source Address**
     - Filters charts by the selected source address.
   * - **Destination Address**
     - Filters charts by the selected destination address.
   * - **SMS OUT Trunk**
     - Filters charts by the selected SMS OUT trunk.
   * - **Destination Country**
     - Filters charts by the selected destination country.
   * - **Service Type**
     - Filters charts by the selected service type (options: A2P, P2P).
   * - **SMS Campaign**
     - Filters charts by the selected SMS campaign. This filter activates if the A2P service type is selected.

----

.. raw:: html

   <br />

.. _userpanel_statistics_capacity_groups:

Capacity Groups
===============

To monitor the usage and performance of your voice services, use the metrics and visual indicators available in the **Capacity Groups** tab.

.. figure:: https://doc.didww.com/_images/fig5.png
    :figclass: align-center
    :alt: Capacity groups tab.
    :width: 80%

    **Fig. 5.** Capacity groups tab.

Metrics
~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 10 70

   * - **Metric**
     - **Description**
   * - **Total Failed Calls**
     - Indicates the total number of failed calls during the selected timeframe. Failures may occur due to capacity limits being reached or incorrect configuration.
   * - **Concurrent Calls**
     - Displays the number of simultaneous calls over time. This includes two types:
        - **Shared**: Calls utilizing shared capacity.
        - **Metered**: Calls billed or allocated per channel or unit.

       Data is sampled at one-minute intervals, providing granular visibility into usage patterns.
   * - **Capacity Exceeded**
     - Shows the number of capacity breach events where the defined channel limit was surpassed during the selected timeframe.

       A non-zero value indicates that the current capacity configuration may be insufficient for peak traffic periods.

Available Filters
~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 16 80

   * - **Filter**
     - **Description**
   * - **Timeframe**
     - Filters the data by the selected period. Options include 24 hours, 7 days, 30 days, 60 days, and 90 days.
   * - **Capacity Group**
     - Allows filtering by a specific capacity group. Only data associated with the selected group will be displayed in the charts.

.. raw:: html

   <br>


.. _user_panel_identities_addresses:

======================
Identities & Addresses
======================

Use the Identities & Addresses section to manage the end-user information required for regulatory services, such as DID number registration and A2P messaging campaigns. This feature allows you to create reusable **Personal** and **Business** identity records, add verified **Addresses**, and track the status of your **Verifications**.

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`light-bulb` **Getting Started**
      :link: user_panel_getting_started_identities
      :link-type: ref
      :text-align: left

      Set up identities and addresses, submit them at checkout, and track verification for compliance.

   .. grid-item-card:: :octicon:`person` **Identities**
      :link: user_panel_identities
      :link-type: ref
      :text-align: left

      Create and manage Personal or Business identities for service activation.

   .. grid-item-card:: :octicon:`home` **Addresses**
      :link: user_panel_addresses
      :link-type: ref
      :text-align: left

      Add and maintain verified proof of address documents for your identities.

   .. grid-item-card:: :octicon:`shield-check` **Verifications**
      :link: user_panel_verifications
      :link-type: ref
      :text-align: left

      Review verification statuses, submit and resubmit identities & addresses.



.. _user_panel_addresses:

=========
Addresses
=========

The Addresses section allows you to create and manage verified physical address records. These addresses are then linked to your identities to meet the regulatory requirements for various services.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create a New Address**
      :link: create_new_address
      :link-type: ref
      :text-align: left

      Learn the two ways to add a new address to your account.

   .. grid-item-card:: :octicon:`pencil` **Edit an Address**
      :link: edit_an_address
      :link-type: ref
      :text-align: left

      Modify the details or proof documents for an existing address.

   .. grid-item-card:: :octicon:`trash` **Delete an Address**
      :link: delete_an_address
      :link-type: ref
      :text-align: left

      Permanently remove an address that is no longer in use.

----

.. _create_new_address:

Create a New Address
====================

Use the **Addresses** tab in **Identities & Addresses** to add one or more addresses to an existing identity. You can also create a new address first and assign it to an identity during Step 2 of the identity creation wizard, either by selecting an existing identity or adding a new one.

Step 1: Add New Address
-----------------------

    1. Go to **Identities & Addresses**.
    2. Select the **Addresses** tab.
    3. Click the **Add New Address** button.

.. figure:: https://doc.didww.com/_images/add_new_address.png
   :figclass: align-center
   :alt: Add New Address Button.
   :width: 100%

   **Fig. 1** Add New Address Button.

.. raw:: html

   <br>

Step 2: Check Requirements by Service Type
------------------------------------------

For the most efficient workflow, start by checking the requirements for your use case on the **New Identity** page. This ensures you have the correct documents and information before proceeding.

    1. Use the **Requirements** checker on the right side of the page.
    2. Select the service **Type** (e.g., Registration, Porting, A2P Campaigns, or Emergency Calling) and the target **Country** (e.g., Belgium).
    3. Review the displayed list of required documents and details. If any downloadable forms are provided, download them, complete as instructed, and upload them as part of the submission.

.. note::

   Each requirement type corresponds to a specific use case:

       - **Registration** – Submit documents needed to register a DID number’s end-user.
       - **Porting** – Provide details to create a porting request from another provider to DIDWW.
       - **A2P Campaigns** – Required to register and enable SMS delivery via Long Code or Alphanumeric Sender ID for A2P messaging services.
       - **Emergency Calling** – Required to register and enable emergency calling services for your DID number.

.. figure:: https://doc.didww.com/_images/requirements.png
   :figclass: align-center
   :alt: Using the requirements checker tool.
   :width: 100%

   **Fig. 2** Checking registration requirements for Belgium.

.. raw:: html

   <br>

Step 3: Enter Address Details and Upload Documents
---------------------------------------------------

.. important::
       - Providing incorrect or insufficient documents may result in a delayed or declined registration process.
       - All file content is encrypted with AES‑256‑CBC and stored on our servers. Only authorized parties can decrypt it using private keys stored in a Hardware Security Module (HSM).
       - The maximum upload file size ``is 20 MB``. The supported file formats ``.pdf``, ``.jpg``, ``.png``.

After reviewing the requirements, fill in the Step 1: Address details and upload the required documents.

.. figure:: https://doc.didww.com/_images/new_address_form_step1.png
   :figclass: align-center
   :alt: The New Address form showing Step 1.
   :width: 100%

   **Fig. 3** The New Address form.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Field
     - Description
   * - Country
     - The country of the address.
   * - City
     - The city of the address.
   * - Postal code
     - The postal or ZIP code.
   * - Address
     - The street name and number.
   * - State/Province/Region
     - The state, province, or region.
   * - Description
     - A friendly name to help you identify this address.
   * - Proofs
     - Click **Add New** to select a proof type and upload the document. Available proof types include:

       * ``Copy of Phone Bill``
       * ``Utility Bill``
       * ``Rental Receipt``
       * ``Other``

.. raw:: html

   <br>

Step 4: Select or Add New Identity
----------------------------------

.. tab-set::
    :class: my-tabs

    .. tab-item:: **Select identity**

        Select this option to assign the new address to an **existing identity** by selecting it from the list.

        .. figure:: https://doc.didww.com/_images/select_identity_for_address.png
           :figclass: align-center
           :alt: Selecting an existing identity to assign to a new address.
           :width: 100%

           **Fig. 4** The Select identity tab.

    .. tab-item:: **Add new identity**

        Select this option to create a new identity together with the address. Fill in the identity details and upload the required documents.

        .. note:: For field descriptions and guidance, see the :ref:`Step 3: Enter Identity Details and Upload Documents <user_panel_identities_enter_details_step3>`.

        .. figure:: https://doc.didww.com/_images/add_new_identity_for_address.png
           :figclass: align-center
           :alt: Creating a new identity to assign to a new address.
           :width: 100%

           **Fig. 5** The Add new identity tab.

.. raw:: html

   <br>

Step 5: Submit Address
----------------------------------

Click **Submit** to assign the address to an existing identity or to create a new identity with the address.

----

.. raw:: html

   <br>

.. _edit_an_address:

Edit Address
===============

    1.  Navigate to the **Identities & Addresses > Addresses** tab.
    2.  Find the address you wish to update and click the actions |actions| button on the right, then select **Edit**.
    3.  In the **Edit Address** window, make the required changes.
    4.  Click **Submit** to apply the changes.

        .. figure:: https://doc.didww.com/_images/edit3.png
           :figclass: align-center
           :alt: Editing an address.
           :width: 100%

           **Fig. 6** Edit Address Button.

----

.. raw:: html

   <br>

.. _delete_an_address:

Delete Address
=================

    1.  Navigate to the **Identities & Addresses > Addresses** tab.
    2.  Find the address you wish to remove and click the actions |actions| button on the right, then select **Delete**.
    3.  A confirmation pop-up will appear. Click **Delete** to permanently remove the address.

        .. figure:: https://doc.didww.com/_images/delete3.png
           :figclass: align-center
           :alt: Delete Address Button.
           :width: 100%

           **Fig. 7** Delete Address Button.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button



.. |br| raw:: html

   <br>

.. _user_panel_getting_started_identities:

===============
Getting Started
===============

To purchase and activate DID numbers in countries with regulatory requirements
(see `Registration Required <https://www.didww.com/coverage-and-prices/regulatory-requirements/registration-required>`__),
you must provide valid identity and address information.
The **Identities & Addresses** feature simplifies this by letting you create, verify, and reuse these records for multiple services,
helping you meet compliance requirements and speed up activation.

----

.. raw:: html

    <br>

Before You Begin
================

Before starting the verification process, please ensure you have the following:

    - **An Active DIDWW Account** – You must be logged into your account to access the User Panel.
    - **Digital Copies of Documents** – Have your required proof of identity (e.g., Passport) and proof of address (e.g., Utility Bill) files ready for upload. Supported formats include ``.pdf``, ``.jpg``, and ``.png``.

----

.. raw:: html

  <br>

Step 1: Create a New Identity
=============================

    1.  Go to **Identities & Addresses** or `click here <https://my.didww.com/#/regulation_identities>`__.
    2.  Click the **Add New Identity** button.
    3.  On the **New Identity** page, use the **Requirements** checker on the right to confirm which specific documents you will need.
    4.  Fill in the **Step 1: Identity** form with your details (Personal or Business) and upload your proof of identity.
    5.  Click **Continue** to proceed to the next step in the wizard.

.. note:: For a complete guide on all available options, please see the detailed :ref:`Identities Guide <user_panel_identities>`.

.. figure:: https://doc.didww.com/_images/qsg1.png
   :figclass: align-center
   :alt: Filling in identity details.
   :width: 100%

   **Fig. 1** Example of a completed identity form.

----

.. raw:: html

  <br>

Step 2: Create a New Address
============================

After you complete the identity form in Step 1, the wizard opens the **Step 2: Address** form.

    1. Enter your **Address** details and upload a valid proof-of-address document.
    2. Check the **Requirements** panel on the right to see which documents are needed. Select **Validate** to confirm that all entered information is correct.
    3. Select **Submit** to create both the identity and address records.

.. note::
   For a complete guide on all available options, see the detailed :ref:`Addresses Guide <user_panel_addresses>`.
   |br| You can also create and assign an address to an existing identity.

.. figure:: https://doc.didww.com/_images/new_address_wizard.png
   :figclass: align-center
   :alt: The Address step in the New Identity wizard.
   :width: 100%

   **Fig. 2** The Address step in the New Identity wizard.

----

.. raw:: html

  <br>

Step 3: Submit End User Details During Number Checkout
======================================================

Once your identity and address are ready, you can assign them to a new number as you purchase it.

    1.  When :ref:`purchasing a DID number <user_panel_purchase>` that requires registration, click the **Submit End User Details** button in your cart.

        .. figure:: https://doc.didww.com/_images/checkout1.png
           :figclass: align-center
           :alt: Submit End User Details Button in the cart.
           :width: 100%

           **Fig. 3** Submit End User Details Button.

    2.  In the pop-up window, choose the identity and address you just created.
    3.  Select **Submit** to complete the DID Number purchase and start the verification process.

        .. figure:: https://doc.didww.com/_images/checkout2.png
           :figclass: align-center
           :alt: Selecting the Identity and Address for a new number.
           :width: 100%

           **Fig. 4** Selecting the Identity and Address.

.. note::
   If you already have a number that is awaiting registration, you can assign an identity to it at any time from the **Phone Numbers > My DIDs** page. Both methods are covered in the full :ref:`Verifications Guide <submitting_for_verification>`.

----

.. raw:: html

  <br>

Step 4: Track Your Verification Status
======================================

The verification process starts after you submit your request. You can track its progress in the Verifications tab and view the history of previous DID number verification requests.

    1. Go to **Identities & Addresses**, then select the **Verifications** tab.
    2. Find your request in the list.
    3. When the responsible department reviews your request, you will receive an email notification with the updated verification status and any required information.

.. note:: For a detailed look at verifications, see the full :ref:`Verifications Guide <user_panel_verifications>`

.. figure:: https://doc.didww.com/_images/verifications_tab.png
   :figclass: align-center
   :alt: The Verifications tab showing the status of requests.
   :width: 100%

   **Fig. 5** The Verifications tab.

.. |approved| image:: /img/new_user_panel/identities_and_addresses/approved_inl.png
   :class: inline-img no-shadow
   :width: 94px

.. |rejected| image:: /img/new_user_panel/identities_and_addresses/rejected_inl.png
   :class: inline-img no-shadow
   :width: 85px

.. |pending| image:: /img/new_user_panel/identities_and_addresses/pending_inl.png
   :class: inline-img no-shadow
   :width: 85px

.. _user_panel_identities:

==========
Identities
==========

An identity contains the end-user's personal or business information, along with uploaded proof documents. This information is used to meet the regulatory requirements for various services.

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`sort-desc` **Identity Hierarchy**
      :link: user_panel_identities_hierarchy
      :link-type: ref
      :text-align: left

      Learn how identities are prioritized for different services.

   .. grid-item-card:: :octicon:`plus` **Create a New Identity**
      :link: create_new_identity
      :link-type: ref
      :text-align: left

      Follow a step-by-step guide to create a new Personal or Business identity.

   .. grid-item-card:: :octicon:`pencil` **Edit an Identity**
      :link: edit_an_identity
      :link-type: ref
      :text-align: left

      Modify the details of an existing identity.

   .. grid-item-card:: :octicon:`trash` **Delete an Identity**
      :link: delete_an_identity
      :link-type: ref
      :text-align: left

      Permanently remove an identity that is no longer in use.

----

.. raw:: html

    <br>

.. _user_panel_identities_hierarchy:

Identity Hierarchy
==================

The identity hierarchy is a ranking system that determines which identity takes precedence when it is assigned to a specific service. While identities can be reused, it is important to note that once an identity is used to activate a service, it should be used for subsequent service activations for the same number to ensure consistency.

The priority is ranked as follows, from highest (1) to lowest (3):

    1.  Number Registration Identity
    2.  A2P Campaign Identity, Emergency Calling Identity, CNAM Identity
    3.  Porting Identity

The assigned identity for a number is displayed in the :ref:`Identity column <my_numbers_reference_end_user_details>` of the **Phone Numbers > My Numbers** section.

.. note::
    - A2P Campaigns can only be registered with a **Business** identity.
    - If a number registration is pending, that identity cannot be assigned to other services (A2P, Emergency, CNAM) until it is approved.

----

.. raw:: html

    <br>

.. _create_new_identity:

Create a New Identity
=====================

Follow the steps below to create a new identity in the DIDWW User Panel.

Step 1: Add New Identity
--------------------------

    1. Go to the **Identities & Addresses** section
    2. Click the **Add New Identity** button.

.. figure:: https://doc.didww.com/_images/main_identities_page.png
   :figclass: align-center
   :alt: The Identities & Addresses main page.
   :width: 100%

   **Fig. 1** The Identities & Addresses main page.

.. raw:: html

   <br>

.. _user_panel_identities_create_requirements:

Step 2: Check Requirements by Service Type
------------------------------------------

For the most efficient workflow, start by checking the requirements for your use case on the **New Identity** page. This ensures you have the correct documents and information before proceeding.

    1. Use the **Requirements** checker on the right side of the page.
    2. Select the service **Type** (e.g., Registration, Porting, A2P Campaigns, or Emergency Calling) and the target **Country** (e.g., Belgium).
    3. Review the displayed list of required documents and details. If any downloadable forms are provided, download them, complete as instructed, and upload them as part of the submission.

.. note::

   Each requirement type corresponds to a specific use case:

       - **Registration** – Submit documents needed to register a DID number’s end-user.
       - **Porting** – Provide details to create a porting request from another provider to DIDWW.
       - **A2P Campaigns** – Required to register and enable SMS delivery via Long Code or Alphanumeric Sender ID for A2P messaging services.
       - **Emergency Calling** – Required to register and enable emergency calling services for your DID number.

.. figure:: https://doc.didww.com/_images/requirements.png
   :figclass: align-center
   :alt: Using the requirements checker tool.
   :width: 100%

   **Fig. 2** Checking registration requirements for Belgium.

.. raw:: html

   <br>

.. _user_panel_identities_enter_details_step3:

Step 3: Enter Identity Details and Upload Documents
---------------------------------------------------

.. important::
       - Providing incorrect or insufficient documents may result in a delayed or declined registration process.
       - All file content is encrypted with AES‑256‑CBC and stored on our servers. Only authorized parties can decrypt it using private keys stored in a Hardware Security Module (HSM).
       - The maximum upload file size ``is 20 MB``. The supported file formats ``.pdf``, ``.jpg``, ``.png``.

After reviewing the requirements, fill in the **Step 1: Identity** details and upload the required documents.

1.  Based on the requirements, choose the appropriate identity **Type**: **Personal** or **Business**.

    .. figure:: https://doc.didww.com/_images/select_identity_type.png
       :figclass: align-center
       :alt: Selecting the identity type.
       :width: 100%

       **Fig. 3** Selecting the identity type.

2.  Fill in all required fields and upload documents by clicking **Add New** in the **Proofs** and if required **Supporting Documents** sections.

    .. tab-set::
        :class: my-tabs

        .. tab-item:: **Personal**

            .. raw:: html

                <br>

            **Identity Details**

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Description
               * - First Name
                 - The individual's legal first name.
               * - Last Name
                 - The individual's legal last name.
               * - Phone number
                 - A valid contact phone number.
               * - Contact email
                 - A valid contact email address.
               * - Personal TAX ID
                 - The individual's personal tax identification number.
               * - ID number
                 - The number from an official identification document.
               * - Country of residence
                 - The country where the individual currently resides.
               * - Place of Birth
                 - The individual's place of birth.
               * - Birth date
                 - The individual's date of birth.
               * - Description
                 - A friendly name to help you identify this record.

            **Documents**

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Description
               * - Proofs
                 - Click **Add New** to upload required documents verifying the identity or business. Accepted types include:

                   * ``Driver's License``
                   * ``National ID``
                   * ``Passport``
                   * ``Residence Permit``
                   * ``Visa``
                   * ``Other``
               * - Supporting Documents
                 - Upload any additional required files (e.g., regional forms). Download them from the **Requirements** section.

        .. tab-item:: **Business**

            .. raw:: html

                <br>

            **Company Details**

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Description
               * - Company Name
                 - The full legal name of the business.
               * - Company registration number
                 - The official registration number of the business.
               * - VAT/TAX number
                 - The Value Added Tax or other official tax number.
               * - Country of incorporation
                 - The country where the business is legally registered.
               * - Company website
                 - The official website for the business.
               * - Description
                 - A friendly name to help you identify this record.

            **Representative's Details**

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Description
               * - First Name
                 - The representative's legal first name.
               * - Last Name
                 - The representative's legal last name.
               * - Phone number
                 - A valid contact phone number for the representative.
               * - Contact email
                 - A valid contact email address for the representative.
               * - Representative's TAX ID
                 - The representative's personal tax identification number.
               * - ID number
                 - The representative's number from an official identification document.
               * - Place of Birth
                 - The representative's place of birth.
               * - Birth date
                 - The representative's date of birth.

            **Documents**

            .. list-table::
               :header-rows: 1
               :widths: 30 70

               * - Field
                 - Description
               * - Proofs
                 - Click **Add New** to upload required documents verifying the identity or business. Accepted types include:

                   * ``Business Registration Certificate / Incorporation Certificate``
                   * ``Trade License``
                   * ``Excerpt from the commercial register``
                   * ``Passport`` (of the representative)
                   * ``Driver's License`` (of the representative)
                   * ``National ID`` (of the representative)
                   * ``Other``
               * - Supporting Documents
                 - Upload any additional required files (e.g., regional forms). Download them from the **Requirements** section.

.. raw:: html

   <br>

Step 4: Validate Identity Details and Continue
----------------------------------------------

After entering your identity information, click **Validate** to check your identity input against the selected requirements. If all required fields are complete and correct, click **Continue** to proceed to the next step.

.. note:: When you click **Validate**, any missing required information will be shown in a highlighted red text. Because the address form has not been completed yet, related fields may also show as incomplete. It is recommended to validate identity details before proceeding to the next step.

.. raw:: html

   <br>

Step 5: Enter Address Details and Upload Documents
--------------------------------------------------

In the **Step 2: Address** form, fill in the address details and upload the required proof documents.

    .. list-table::
       :header-rows: 1
       :widths: 30 70

       * - Field
         - Description
       * - Add address later
         - Toggle to skip this step and finalize the identity creation without an address.

           .. note:: You can add an address to the identity later.
       * - Country
         - The country of the address.
       * - City
         - The city of the address.
       * - Postal code
         - The postal or ZIP code.
       * - Address
         - The street name and number.
       * - State/Province/Region
         - The state, province, or region.
       * - Description
         - A friendly name to help you identify this address.
       * - Proofs
         - Click **Add New** to select a proof type and upload the document. Available proof types include:

           * ``Copy of Phone Bill``
           * ``Utility Bill``
           * ``Rental Receipt``
           * ``Other``

.. raw:: html

   <br>

Step 6: Validate and Submit
-----------------------------

After entering both identity and address information, click **Validate** to confirm everything is complete. The green **Valid** text will appear in the requirements section if all required information has been provided correctly.

Click **Submit** to finalize and create your identity and address.

.. figure:: https://doc.didww.com/_images/validate-and-submit.png
   :figclass: align-center
   :alt: Validating identity and address requirements before submission
   :width: 100%

   **Fig. 4** Validating identity and address requirements before submission

----

.. raw:: html

    <br>

.. _edit_an_identity:

Edit Identity
================

1.  Navigate to the **Identities & Addresses > Identities** tab.
2.  Find the identity you wish to update and click the actions |actions| button on the right.
3.  Select **Edit** from the dropdown menu to open the edit identity window.
4.  Make your changes and click **Submit** to apply the changes.

    .. figure:: https://doc.didww.com/_images/edit1.png
       :figclass: align-center
       :alt: Edit button.
       :width: 100%

       **Fig. 5** Edit button.

----

.. raw:: html

   <br>

.. _delete_an_identity:

Delete Identity
==================

.. important::
       An identity cannot be deleted if it is currently assigned to any active services. This action cannot be undone.

1.  Navigate to the **Identities & Addresses** section and select the **Identities** tab.
2.  Find the identity you wish to remove and click the actions |actions| button on the right.
3.  Select **Delete** from the dropdown menu.
4.  A confirmation pop-up will appear. Click **Delete** to permanently delete the identity.

        .. figure:: https://doc.didww.com/_images/delete1.png
           :figclass: align-center
           :alt: Delete button.
           :width: 100%

           **Fig. 6** Delete button.

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px
   :alt: Actions button


.. |br| raw:: html

   <br>

.. _user_panel_verifications:

=============
Verifications
=============

The Verifications tab provides a centralized place to track the status of all your identity and address submissions required for services like DID number registration. Every time you assign an identity and address to a number, a new verification request is created and can be monitored here.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`eye` **Tracking Verifications**
      :link: tracking_verifications
      :link-type: ref
      :text-align: left

      Learn to interpret the statuses, filters, and columns on the Verifications page.

   .. grid-item-card:: :octicon:`device-mobile` **Submit End User Details**
      :link: submitting_for_verification
      :link-type: ref
      :text-align: left

      Learn the two ways to assign an identity to a DID number to start the verification process.

   .. grid-item-card:: :octicon:`sync` **Resubmit End User Details**
      :link: re-submit_end_user_details
      :link-type: ref
      :text-align: left

      Learn how to update and resubmit a rejected verification request with corrected identity and address information.

----

.. raw:: html

   <br>

.. _tracking_verifications:

Tracking Verifications
======================

The Verifications tab provides a searchable and filterable overview of all submitted registration requests. Each entry includes the identity type, linked address, current status (Pending, Approved, or Rejected), and timestamps for creation and last update. Use the filters to sort by reference, identity type, status, or date range to easily manage and monitor verification progress.

Verification Filters
--------------------

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Filter
     - Description
   * - Reference
     - Search for a verification request by its unique reference ID.
   * - Type
     - Filter the list to show only **Personal** or **Business** identities.
   * - Status
     - Filter by status: **Approved**, **Pending**, or **Rejected**.
   * - Created at (UTC) / Updated at (UTC)
     - Filter requests based on a specific date range for their creation or last update time.

.. figure:: https://doc.didww.com/_images/verifications_tab_filters.png
   :figclass: align-center
   :alt: The Verification Tab Filters.
   :width: 100%

   **Fig. 1** The Verification Tab Filters.

.. _tracking_verifications_verification_details:

Verification Details
--------------------

By clicking the actions |actions| button for a specific request, you can open the **Verification Details** screen. This page provides a complete breakdown of the request and lists all the numbers associated with it.

.. tab-set::
   :class: my-tabs

   .. tab-item:: **Verification Summary**

      This tab provides an overview of the verification request.

      .. list-table::
         :header-rows: 1
         :widths: 30 70

         * - Field
           - Description
         * - Status
           - The current status of the request (|approved|, |pending|, or |rejected|).

             .. hint::
                If a verification is **Rejected**, hover your mouse over the status label to see a tooltip explaining the reason for the rejection.
         * - Updated at / Created at
           - The UTC timestamps indicating when the request was created and last updated.
         * - Identity
           - The name of the :ref:`Identity <user_panel_identities>` used for the verification.
         * - Address
           - The :ref:`Address <user_panel_addresses>` used for the verification.

   .. tab-item:: **Assigned Number(s)**

      This table shows DID numbers included in the verification request.

      .. list-table::
         :header-rows: 1
         :widths: 30 70

         * - Field
           - Description
         * - DID Number
           - The phone number submitted for verification.
         * - Country / City
           - The location associated with the number.
         * - Status
           - The current registration status of the number.
         * - Time Left
           - The estimated remaining time to complete the verification process.

.. figure:: https://doc.didww.com/_images/verification_details.png
   :figclass: align-center
   :alt: The Verification Details screen.
   :width: 100%

   **Fig. 2** The Verification Details screen.

----

.. raw:: html

   <br>

.. _submitting_for_verification:

Submit End User Details
=======================

The verification process is initiated by assigning an identity and address to a DID number that requires registration. This can be done in two ways.

.. tab-set::
    :class: my-tabs

    .. tab-item:: **During Checkout**
       :name: verification-checkout-tab

        1.  When :ref:`purchasing a DID number <user_panel_purchase>` that requires registration, you will see an option to **Submit End User Details** during the checkout process.

        .. figure:: https://doc.didww.com/_images/checkout1.png
               :figclass: align-center
               :alt: Submit End User Details Button.
               :width: 100%

               **Fig. 3** Submit End User Details Button.

        2.  Clicking this opens a window where you can select a pre-configured **Identity** and **Address**.
        3.  Click **Submit** to associate the details with the number and start the verification process upon checkout.

        .. figure:: https://doc.didww.com/_images/checkout2.png
               :figclass: align-center
               :alt: Assigning an identity and address during checkout.
               :width: 100%

               **Fig. 4** Selecting an identity and address in the cart.

    .. tab-item:: **On My Numbers Page**
       :name: verification-mynumbers-tab

        You can assign or re-assign end-user details to numbers you already own that are awaiting registration, either individually or in a batch.

        .. tab-set::
            :class: my-tabs

            .. tab-item:: **For a Single DID**

                1.  Navigate to **Phone Numbers > My DIDs** and select the **Awaiting Registration** tab.
                2.  Find the desired number and click the **None** text in the `Identity` column next to the |redverification| icon.

                .. figure:: https://doc.didww.com/_images/assign_single_did_action.png
                       :figclass: align-center
                       :alt: Clicking the 'None' text to assign an identity.
                       :width: 100%

                       **Fig. 5** Assigning end-user details for a single DID.

                3.  In the **Assign End User Details** pop-up, select an **Identity** from the dropdown and click **Confirm**.

                .. figure:: https://doc.didww.com/_images/assign_single_did_popup.png
                       :figclass: align-center
                       :alt: The 'Assign End User Details' pop-up for a single DID.
                       :width: 100%

                       **Fig. 6** Selecting the Identity.

                4.  On the new page that appears, click the **Assign** button.

                .. figure:: https://doc.didww.com/_images/assign_button_page.png
                       :figclass: align-center
                       :alt: The Assign button for end-user details.
                       :width: 100%

                       **Fig. 7** The Assign button.

                5.  In the final **Assign Address** pop-up, select the corresponding **Address** and click **Confirm**. The verification process will now begin.

                .. figure:: https://doc.didww.com/_images/assign_address_popup.png
                       :figclass: align-center
                       :alt: The 'Assign Address' pop-up.
                       :width: 100%

                       **Fig. 8** Selecting the Address.

            .. tab-item:: **For Multiple DIDs (Batch Action)**

                1.  Navigate to **Phone Numbers > My DIDs** and select the **Awaiting Registration** tab.
                2.  Use the **Checkboxes** to select two or more numbers.

                .. figure:: https://doc.didww.com/_images/assign_batch_checkmarks.png
                      :figclass: align-center
                      :alt: Select a batch of numbers using checkboxes.
                      :width: 100%

                      **Fig. 9** Select a batch of numbers using checkboxes.

                3.  Click the **Batch Actions** button at the bottom of the page and select **Assign End User Details**.

                .. figure:: https://doc.didww.com/_images/assign_batch_did_action.png
                      :figclass: align-center
                      :alt: Assigning end-user details via Batch Actions.
                      :width: 100%

                      **Fig. 10** Assigning end-user details via Batch Actions.

                4.  In the **Assign End User Details** pop-up, select the **Identity** to apply to all numbers and click **Confirm**.

                .. figure:: https://doc.didww.com/_images/assign_batch_identity_popup.png
                      :figclass: align-center
                      :alt: Selecting the Identity for a batch of DIDs.
                      :width: 100%

                      **Fig. 11** Selecting the Identity for a batch of DIDs.

                5.  On the new page that appears, review the list of numbers and click the **Assign** button.

                .. figure:: https://doc.didww.com/_images/assign_batch_button_page.png
                       :figclass: align-center
                       :alt: The Assign button for a batch of DIDs.
                       :width: 100%

                       **Fig. 12** The Assign button for a batch of DIDs.

                6.  In the final **Assign Address** pop-up, select the **Address** to apply to all numbers and click **Confirm**. The verification process will now begin for all selected DIDs.

                .. figure:: https://doc.didww.com/_images/assign_batch_address_popup.png
                       :figclass: align-center
                       :alt: Selecting the Address for a batch of DIDs.
                       :width: 100%

                       **Fig. 13** Selecting the Address for a batch of DIDs.

----

.. raw:: html

   <br>

.. _re-submit_end_user_details:

Resubmit End User Details
=========================

.. Important::

   1. Resubmit in the verification details page is available only when the number is **Awaiting Registration** and still **linked** to the same verification reference.
   2. Before using **Resubmit**, make sure you update your identity and address information, and upload any required documents.
      |br| See :ref:`edit_an_identity` and :ref:`edit_an_address` for details on updating these records based on the reason your request was rejected.

If a verification request is rejected, you can update the required information and resubmit the request using the **Resubmit** option in the verification details page.

    1. Go to **Identities & Addresses** > **Verifications** tab.
    2. Locate the rejected verification in the list.
    3. Click the **Actions** menu (⋯), then click **Resubmit**, or open the verification details page and click **Resubmit**.

.. figure:: https://doc.didww.com/_images/rejected-verification-details-page-with-resubmit.png
  :figclass: align-center
  :alt: Rejected verification details with status and reason.
  :width: 100%

  **Fig. 14** Rejected verification with rejection reason and DID number status.

4. In the **Resubmit End User Details** popup, select the updated **Identity** and **Address** that now meet the requirements.

.. figure:: https://doc.didww.com/_images/resubmit-from-rejected-verification.png
  :figclass: align-center
  :alt: Selecting the Identity and Address for resubmission.
  :width: 100%

  **Fig. 15** Select updated Identity and Address for resubmission.

5. Click **Submit** to create a new verification request. The system will automatically reassign all originally assigned DID numbers to the new request.

A **new reference ID** will be created, and the request will appear in the **Verifications** list in |pending| status.

.. |approved| image:: /img/new_user_panel/identities_and_addresses/approved_inl.png
   :class: inline-img no-shadow
   :width: 94px

.. |rejected| image:: /img/new_user_panel/identities_and_addresses/rejected_inl.png
   :class: inline-img no-shadow
   :width: 85px

.. |pending| image:: /img/new_user_panel/identities_and_addresses/pending_inl.png
   :class: inline-img no-shadow
   :width: 85px

.. |actions| image:: /img/new_user_panel/trunks/voice_in/pstn/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |redverification| image:: /img/new_user_panel/did_numbers/status_timeleft_overview/redverification.png
   :class: no-shadow no-lightbox50 no-lightbox
   :width: 30px
   :height: 30px




=======
Billing
=======

The **Billing** section covers essential tools for managing your account's financial aspects, including setting up payment methods, reviewing billing history, and accessing billing and pricing information.

----

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`light-bulb` **Getting Started**
      :link: getting-started
      :link-type: doc
      :text-align: left

      Quickly set up billing, add a credit card, enable auto top-up, and configure low balance alerts to keep your services active.

   .. grid-item-card:: :octicon:`credit-card` **Payment Methods**
      :link: payment-methods/index
      :link-type: doc
      :text-align: left

      Add or manage Credit Card, PayPal, or Wire Transfer methods. Configure auto-charge, top-ups, and make instant payments.

   .. grid-item-card:: :octicon:`file` **Billing History**
      :link: billing/index
      :link-type: doc
      :text-align: left

      View transactions, filter payment history, review orders, and download invoices.

   .. grid-item-card:: :octicon:`report` **Billing and Pricing**
      :link: billing-and-prices/index
      :link-type: doc
      :text-align: left

      Learn about prepaid billing, pricing, taxes, payment methods, and service renewals.



.. |br| raw:: html

    <br>

.. _services_coverage_pricing:

=======================================
Services, Coverage, and Pricing
=======================================

DIDWW offers a comprehensive suite of telecommunication services, including global availability of virtual phone numbers (DIDs), flexible voice channel capacity options, SIP trunking, call forwarding, emergency calling, two-way SMS messaging, number porting, and a cloud-based PBX platform. Services are billed on a prepaid model, with charges varying by service type, destination, and usage model.

.. note::

   - **NRC** (Non-Recurring Charge): One-time activation fee.
   - **MRC** (Monthly Recurring Charge): Ongoing monthly fee.
   - **Per-minute usage fees**: Applicable for certain services (e.g., outbound calls or incoming call minutes).

   All rates are in **USD**. Ensure your payment method supports USD transactions. |br|
   For the most current service pricing, visit: `DID Pricing <https://www.didww.com/coverage-and-prices/did-pricing>`_

----

.. raw:: html

    <br>

Phone Numbers
=======================================

A wide range of virtual phone number types is available globally. Pricing follows a prepaid model, with costs comprising a one-time setup fee and a monthly recurring charge. Additional per-minute usage fees may apply based on the number type.

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: **Local Numbers**
      :text-align: left
      :link: https://www.didww.com/phone-numbers/local-numbers
      :shadow: sm

      |br|
      **Pricing:** NRC, MRC. |br|
      **Billing:** Caller pays for outbound calls. |br|
      |br|
      |br|
      |br|

   .. grid-item-card:: **National Numbers**
      :text-align: left
      :link: https://www.didww.com/phone-numbers/national-numbers
      :shadow: sm

      |br|
      **Pricing:** NRC, MRC. |br|
      **Billing:** Caller pays for outbound calls. |br|
      |br|
      |br|
      |br|

   .. grid-item-card:: **Mobile Numbers**
      :text-align: left
      :link: https://www.didww.com/phone-numbers/mobile-numbers
      :shadow: sm

      |br|
      **Pricing:** NRC, MRC. |br|
      **Billing:** Caller pays for outbound calls. |br|
      |br|
      |br|

   .. grid-item-card:: **Shared Cost Numbers**
      :text-align: left
      :link: https://www.didww.com/phone-numbers/shared-cost-numbers
      :shadow: sm

      |br|
      **Pricing:** NRC, MRC. Pay-per-minute for incoming calls. |br|
      **Billing:** Costs are shared between the caller and the number owner.
      |br|
      |br|

   .. grid-item-card:: **Toll-Free Numbers**
      :text-align: left
      :link: https://www.didww.com/phone-numbers/toll-free-numbers
      :shadow: sm

      |br|
      **Pricing:** NRC, MRC. Pay-per-minute for incoming calls. |br|
      **Billing:** Caller is not charged. |br| Customer pays for inbound calls.
      |br|
      |br|

   .. grid-item-card:: **UIFN Numbers**
      :text-align: left
      :link: https://www.didww.com/phone-numbers/universal-international-freephone-numbers
      :shadow: sm

      |br|
      **Pricing:** NRC, MRC (for the UIFN plus each enabled country). Pay-per-minute for incoming calls. |br|
      **Billing:** Caller is not charged. |br|
      Customer pays for inbound calls.
      |br|
      |br|

.. note::

    Capacity is either included or provided separately, depending on the selected service tier.

----

.. raw:: html

    <br>

Capacity
===========

Flexible voice channel capacity options, including flat-rate, metered, and hybrid models. These plans define the number of concurrent calls that can be handled through the DIDWW network. Capacity is billed on a prepaid basis and is available for immediate activation via the self-service web portal, API, or by contacting sales@didww.com for high-volume deployments.

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: **Flat-Rate Capacity**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/services/capacity

      |br|
      **Pricing:** NRC, MRC. |br|
      **Billing:** All channels are billed on the same monthly cycle. Charges are prorated for any channel changes during the billing period. |br|
      |br|

   .. grid-item-card:: **Metered Capacity**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/services/capacity

      |br|
      **Pricing:** Pay-per-minute. |br|
      **Billing:** No activation or recurring fees are applicable. |br|
      |br|

   .. grid-item-card:: **Hybrid Capacity**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/services/capacity

      |br|
      **Pricing:** Combined flat rate and pay-per-minute. |br|
      Uses flat-rate channels for predictable traffic and metered channels as a reliable backup for high call demands. |br|
      |br|

.. note::

   Specific country eligibility for each capacity plan may impact channel pricing and availability. |br|
   For service details, visit: `DIDWW Capacity Services <https://www.didww.com/services/capacity>`_

----

.. raw:: html

    <br>

Voice
=======================================

Outbound voice services through Local and International SIP Trunking, as well as Emergency Calling. These services are built on a secure, geo-redundant intercontinental backbone, supporting high-quality, reliable, and compliant voice communication globally.

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: **Local Outbound Termination**
      :text-align: left
      :link: https://www.didww.com/services/two-way-sip-trunking/outbound-sip-trunking/local-sip-trunking
      :shadow: sm

      |br|
      **Pricing:** Pay-per-minute. |br|
      **Billing:** Charges apply as incurred. |br| Calls are billed with an initial minimum interval and subsequent incremental intervals. |br|
      |br|

   .. grid-item-card:: **International Outbound Termination**
      :text-align: left
      :link: https://www.didww.com/services/two-way-sip-trunking/outbound-sip-trunking/international-voip-termination
      :shadow: sm

      |br|
      **Pricing:** Pay-per-minute. |br|
      **Billing:** Charges apply as incurred. |br| Calls are billed with an initial minimum interval and subsequent incremental intervals.
      |br|

   .. grid-item-card:: **Emergency Calling**
      :text-align: left
      :link: https://www.didww.com/services/emergency-calling
      :shadow: sm

      |br|
      **Pricing:** Monthly administration and setup fees apply per number. |br|
      **Billing:** Emergency calls are free of charge.
      |br|

.. note::

   For current rates, download the applicable `SIP Trunking pricing <https://www.didww.com/coverage-and-prices/sip-trunking-pricing>`_. |br|
   To activate any voice service, please contact sales@didww.com.

----

.. raw:: html

    <br>

Messaging
==========

Person-to-Person (P2P) and Application-to-Person (A2P) messaging using local, national, and mobile DIDs.

.. grid:: 1 1 1 3
   :gutter: 3

   .. grid-item-card:: **Inbound SMS**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/coverage-and-prices/did-pricing

      |br|
      **Pricing:** Pay-per-message. |br|
      **Billing:** Charged per message fragment. |br|
      |br|

   .. grid-item-card:: **Outbound P2P SMS**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/services/two-way-sms/p2p-messaging

      |br|
      **Pricing:** Pay-per-message. |br|
      **Billing:** Charged per message fragment. |br|
      |br|

   .. grid-item-card:: **Outbound A2P SMS**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/services/two-way-sms/a2p-messaging

      |br|
      **Pricing:** Pay-per-message. |br|
      **Billing:** Charged per message fragment. |br|
      |br|
      |br|

.. note::

   SMS messages may be split into multiple fragments depending on message length and encoding. Each fragment is billed separately. |br|
   For up-to-date SMS service rates, including destination-specific pricing for A2P and P2P messaging, refer to `DIDWW DID Pricing <https://www.didww.com/coverage-and-prices/did-pricing>`_.

----

.. raw:: html

    <br>

Cloud PBX phone.systems™
=======================================

A fully-featured, cloud-based PBX platform designed for businesses of all sizes. The system offers a seat-based pricing model with flexible billing options. Each seat includes a user license, SIP account, and call forwarding capabilities. There are no feature limitations across pricing tiers.

.. grid:: 1 1 1 3
   :gutter: 3

   .. grid-item-card:: **phone.systems™**
      :text-align: left
      :shadow: sm
      :link: https://www.didww.com/tools/business-phone-systems

      |br|
      **Pricing:** Monthly recurring seat-based model. |br|
      **Billing:** All seats are billed on the same monthly cycle. Charges are prorated for any seat changes during the billing period. |br|
      |br|

.. note::

   For more information, visit: `Cloud business phone.systems™  <https://www.didww.com/tools/business-phone-systems>`_.

----

.. raw:: html

    <br>

Number Porting
===============

Number porting allows businesses to retain their existing telephone numbers when migrating to the DIDWW network. This service is generally offered free of charge, subject to eligibility and approval.

.. grid:: 1 1 1 3
   :gutter: 3

   .. grid-item-card:: **Port In**
      :text-align: left
      :link: https://www.didww.com/services/phone-number-porting

      |br|
      **Pricing:** Free of charge in 41 countries (subject to approval). |br|
      Terms may be updated periodically. Please refer to the official website for the latest information. |br|
      |br|

.. note::

   For service details, visit: `DIDWW Phone Number Porting <https://www.didww.com/services/phone-number-porting>`_


====================
Billing And Pricing
====================

DIDWW primarily operates on a prepaid billing model. Customers requiring a postpaid billing arrangement should contact their sales representative at `sales@didww.com <mailto:sales@didww.com>`_ or account manager. Postpaid billing requests are subject to review and may be approved on a case-by-case basis under a separate agreement.

The minimum top-up amount is 30 USD, and a sufficient positive balance must be maintained to keep your services active.

Supported Payment Methods:
    - **Credit Card** – Real-time top-ups via the User Panel.
    - **PayPal** – Manual or automatic balance refills. To enable, contact: `billing@didww.com <mailto:billing@didww.com>`_
    - **Wire Transfer** – Manual payments only. Processing time varies depending on bank.

All payments are processed in **USD**, while **EUR** is also accepted for Wire Transfer and PayPal transactions. Customers should ensure that their chosen payment method supports transactions in their preferred currency.

.. note::

   - Third-party transaction or currency conversion fees (e.g., bank or PayPal charges) may apply and are the customer’s responsibility.
   - Only net amounts received will be credited to the DIDWW account balance.

Services are automatically renewed unless canceled by the customer. When Credit Card or PayPal is set as the preferred payment method, the prepaid balance is automatically refilled to maintain service continuity. Wire Transfers must be initiated manually and are not eligible for auto-replenishment.

----

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`globe` **Services, Coverage, and Pricing**
      :link: didww-pricing
      :link-type: doc
      :text-align: left

      Access DIDWW service pricing and coverage, and detailed cost breakdowns.

   .. grid-item-card:: :octicon:`file` **Invoices and Receipts**
      :link: invoices-and-receipts
      :link-type: doc
      :text-align: left

      View and download invoices issued monthly and receipts for successful payments.

   .. grid-item-card:: :octicon:`report` **Origin-Based Pricing**
      :link: origin-based-pricing
      :link-type: doc
      :text-align: left

      Understand how call origin impacts rates and affects your SIP trunking costs.

   .. grid-item-card:: :octicon:`organization` **VAT / Tax Identification Numbers**
      :link: vat-tax-id
      :link-type: doc
      :text-align: left

      Learn about VAT, tax ID usage, and DIDWW’s tax policies for EU and non-EU customers.

   .. grid-item-card:: :octicon:`unverified` **Wire Transfer Details**
      :link: wire-transfer-details
      :link-type: doc
      :text-align: left

      Get wire transfer instructions, payment destinations, and processing details.

.. toctree::
  :maxdepth: 1
  :hidden:

  Services, Coverage, and Pricing <didww-pricing.rst>
  Invoices and Receipts <invoices-and-receipts.rst>
  Origin-Based Pricing <origin-based-pricing.rst>
  VAT / Tax Identification Numbers <vat-tax-id.rst>
  Wire Transfer Details <wire-transfer-details.rst>


.. |br| raw:: html

    <br>

.. _billing_invoices_and_receipts:

=====================
Invoices and Receipts
=====================

Invoices are issued on the **first day of each month**, summarizing all services purchased or renewed during the previous billing cycle. Each invoice includes details such as the quantity of services, applicable **NRC** (Non-Recurring Charges), **MRC** (Monthly Recurring Charges), and any **usage-based charges** (e.g., metered calls, SMS, or other).

Receipts are generated for every successful payment made using **Credit Card**, **PayPal**, or **Wire Transfer**, and are sent to the customer's registered email address.

Invoices can also be downloaded at any time from the :ref:`Billing <user_panel_billing_invoice>` section of the User Panel. Email notifications are sent with the subject line: **"DIDWW: Invoice YYYY-MM"**.

.. note::

   All charges are processed in **USD**. Ensure your payment method supports USD transactions. |br|
   For assistance with payments or billing, contact: `billing@didww.com <mailto:billing@didww.com>`_

.. _origin_based_pricing:

====================
Origin-Based Pricing
====================

Some countries in the European Economic Area (EEA) have introduced origin-based pricing for voice services. This means that the cost of a call to certain destinations depends on the country where the call originates. Typically, calls originating from within the EEA are billed at a lower rate, while calls from non-EEA countries incur higher charges.

To comply with these regulatory changes and ensure accurate billing, DIDWW has implemented origin-based pricing for affected destinations.

----

How the Origin of a Call Affects Pricing
----------------------------------------

With origin-based pricing, the rate for a call to a specific destination depends on the origin of the call. This is determined based on the caller ID information provided during the call setup.

Origin-based pricing is currently active for the following countries:

.. list-table::
   :widths: 25 25 25

   * - Austria
     - Greece
     - Norway
   * - Belgium
     - Hungary
     - Poland
   * - Bulgaria
     - Iceland
     - Portugal
   * - Croatia
     - Ireland
     - Romania
   * - Cyprus
     - Italy
     - Slovakia
   * - Czech Republic
     - Latvia
     - Slovenia
   * - Denmark
     - Liechtenstein
     - Spain
   * - Estonia
     - Lithuania
     - Sweden
   * - Finland
     - Luxembourg
     - United Kingdom
   * - France
     - Malta
     -
   * - Germany
     - Netherlands
     -

Calls originating from within the `European Economic Area (EEA) <https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:European_Economic_Area_(EEA)>`_ are billed at reduced rates when placed to the listed countries.

----

How This Affects Your Call Rates
---------------------------------

The **per-minute rate** is automatically calculated based on the **originating caller ID**. No manual configuration is required.

DIDWW will continue to monitor regulatory developments and extend origin-based pricing to additional destinations if needed. Pricing updates will be reflected in your account as they occur.



.. _billing_vat:

VAT / Tax Identification Numbers
--------------------------------

A **Value Added Tax (VAT) Identification Number** is a unique identifier assigned to businesses registered for VAT within the European Union. This number is essential for:

    - **Cross-border B2B transactions**: Facilitates the application of the reverse charge mechanism, allowing the buyer to account for VAT in their own country.
    - **VAT compliance**: Enables businesses to reclaim VAT on eligible purchases and ensures proper reporting to tax authorities.
    - **Verification purposes**: Confirms the VAT registration status of trading partners.

Each EU Member State issues VAT numbers in a specific format, typically starting with a two-letter country code followed by a series of digits or characters. For example:

    - Germany: `DE123456789`
    - France: `FR12345678901`
    - Italy: `IT12345678901`

Businesses can verify the validity of a VAT number through the EU's official VIES (VAT Information Exchange System) portal: https://ec.europa.eu/taxation_customs/vies/

Tax Identification Number (Tax ID)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A **Tax Identification Number (Tax ID)** is a broader identifier used for general tax purposes, such as income tax, corporate tax, and other national tax obligations. Unlike the VAT ID, which is specific to VAT transactions, the Tax ID applies to a wider range of tax-related activities.

DIDWW VAT and Tax ID Policy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

DIDWW applies VAT to customers based on their VAT registration status and location:

    - **EU Businesses**: If a valid VAT ID is provided and the business is located outside of Ireland, VAT is not charged under the reverse charge mechanism.
    - **EU Individuals or Businesses without a valid VAT ID**: VAT is applied at the rate applicable in the customer's country of residence.
    - **Non-EU Customers**: VAT is not applied.

Customers with a **Business** account can manage their VAT ID and Tax ID information by navigating to **Account Settings**, then selecting the **Account Details** page in their DIDWW account.

If assistance is required, please contact the DIDWW Billing Department at `billing@didww.com <mailto:billing@didww.com>`_.

.. note::

   - Ensure that your VAT ID is valid and corresponds to your business's registered address.
   - Regularly verify the VAT IDs of your EU trading partners to maintain compliance.
   - For more information on VAT regulations and requirements, refer to the European Commission's official VAT portal: https://taxation-customs.ec.europa.eu/taxation/vat_en


.. _billing_wire_transfer:

.. |br| raw:: html

   <br />

Wire Transfer Details
=====================

.. important::

    1. Please make sure to include the **Payment Reference ID** in your wire transfer instructions to your bank. Failure to do so may result in payment delays or cancellations.
    2. Ensure that the remittance amount includes any applicable bank fees so that the full payment reaches DIDWW.
    3. If paying in **Euro**, your payment will be **converted to U.S. Dollars (USD)** automatically.
       Foreign exchange rates vary daily and are determined by financial institutions.
       No prior notification will be provided for the conversion rate applied.

Revolut Bank UAB
-----------------------------

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **USD**
      :text-align: left
      :shadow: sm

      |br|
      **Beneficiary Name:** DIDWW Ireland Limited :octicon:`copy` |br|
      **Beneficiary Bank:** Revolut Bank UAB :octicon:`copy` |br|
      **Bank Address:** 2 Dublin Landings, North Dock, D01 V4A3, DUBLIN 1, Ireland :octicon:`copy` |br|
      **SWIFT/BIC:** REVOIE23 :octicon:`copy` |br|
      **IBAN:** IE79REVO99036021219519 :octicon:`copy` |br|
      |br|

   .. grid-item-card:: **EUR**
      :text-align: left
      :shadow: sm

      |br|
      **Beneficiary Name:** DIDWW Ireland Limited :octicon:`copy` |br|
      **Beneficiary Bank:** Revolut Bank UAB :octicon:`copy` |br|
      **Bank Address:** 2 Dublin Landings, North Dock, D01 V4A3, DUBLIN 1, Ireland :octicon:`copy` |br|
      **SWIFT/BIC:** REVOIE23 :octicon:`copy` |br|
      **IBAN:** IE23REVO99036030212330 :octicon:`copy` |br|
      |br|

Allied Irish Bank, p.l.c.
-----------------------------

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **USD**
      :text-align: left
      :shadow: sm

      |br|
      **Beneficiary Name:** DIDWW Ireland Ltd :octicon:`copy` |br|
      **Beneficiary Bank:** Allied Irish Bank, p.l.c. :octicon:`copy` |br|
      **Bank Address:** Currency Account Services, 1 Adelaide Road, Dublin 2, Ireland :octicon:`copy` |br|
      **SWIFT/BIC:** AIBKIE2D :octicon:`copy` |br|
      **IBAN:** IE79AIBK93006727976719 :octicon:`copy` |br|
      **NSC & Account Number:** 930067 27976719 :octicon:`copy` |br|
      |br|

   .. grid-item-card:: **EUR**
      :text-align: left
      :shadow: sm

      |br|
      **Beneficiary Name:** DIDWW Ireland Ltd :octicon:`copy` |br|
      **Beneficiary Bank:** Allied Irish Bank, p.l.c. :octicon:`copy` |br|
      **Bank Address:** Lisduggan, Paddy Brownes Road, Co Waterford, Ireland :octicon:`copy` |br|
      **SWIFT/BIC:** AIBKIE2D :octicon:`copy` |br|
      **IBAN:** IE82AIBK93411908569038 :octicon:`copy` |br|
      **NSC & Account Number:** 934119 08569038 :octicon:`copy` |br|
      |br|

----

.. raw:: html

   <br>

Wire Transfer Instructions
------------------------------------------------

Step 1: Initiate Payment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. `Sign in to your DIDWW account <https://my.didww.com/#/users/sign_in>`_
    2. Navigate to **Billing > Payment Methods**
    3. Open the `Wire Transfer <https://my.didww.com/#/payment_methods/wire_transfers>`_ tab, click **Create New**, and create the payment
    4. Log in to your online banking system and initiate the wire transfer

.. important::

   Ensure that all transfer details (bank name, SWIFT/BIC, IBAN, beneficiary name, and payment reference ID) are entered exactly as shown above. Any discrepancies may delay or invalidate the payment.

Step 2: Submit Proof of Payment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After completing the wire transfer, submit proof of payment:

    1. Take a **screenshot** or **download the receipt** that confirms the payment.
    2. Ensure the document includes the following details:

       - Your full name
       - Your bank’s name
       - Your account number
       - Payment date and amount

    3. Upload the document through the `DIDWW User Panel <https://my.didww.com/#/payment_methods/wire_transfers>`_ under the **Wire Transfer Details** page.

.. note::

   Supported file formats: **PNG**, **JPG**, **JPEG**, and **PDF** only.

After the payment is processed and credited to your prepaid balance, a confirmation receipt will be sent to your registered email address.

.. raw:: html

   <style>
     .copy-btn {
       background: none;
       border: none;
       cursor: pointer;
       padding: 0 .25em;
       vertical-align: middle;
     }
     .copy-btn svg {
       width: 1.0em;
       height: 1.0em;
       vertical-align: middle;
     }
     .copied-text {
       color: green;
       font-weight: bold;
       margin-left: .3em;

     }

    @media (min-width: 992px) {
        .sd-row-cols-md-2 {
            display: flex;
            justify-content: left !important;
            flex-wrap: wrap;
            min-width: 30rem !important;
        }
    }

   </style>

   <script>
     document.addEventListener('DOMContentLoaded', function() {
       // Find every copy-icon SVG inside card bodies
       const icons = document.querySelectorAll('.sd-card-body.docutils .sd-octicon.sd-octicon-copy');
       icons.forEach(svg => {
         // Wrap the SVG in a button
         const btn = document.createElement('button');
         btn.className = 'copy-btn';
         const svgClone = svg.cloneNode(true);
         btn.appendChild(svgClone);
         svg.parentNode.replaceChild(btn, svg);

         // Store original SVG markup for later restoration
         const originalInner = btn.innerHTML;

         btn.addEventListener('click', function() {
           // Determine text to copy:
           // if there's a <code> immediately preceding, use its text;
           // otherwise use the raw text node just before the button.
           let text = '';
           const prevElem = btn.previousElementSibling;
           if (prevElem && prevElem.tagName.toLowerCase() === 'code') {
             text = prevElem.textContent.trim();
           } else {
             // include text of preceding text node or element
             text = btn.previousSibling.textContent.trim();
           }

           navigator.clipboard.writeText(text).then(function() {
             // show “Copied!” then revert after 1.5s
             btn.innerHTML = '<span class="copied-text">Copied!</span>';
             setTimeout(function() {
               btn.innerHTML = originalInner;
             }, 1500);
           });
         });
       });
     });
   </script>

.. raw:: html

   <style>
    @media (min-width: 992px) {
      .sd-row-cols-lg-2 > * { max-width: 36rem; }
    }

    @media (min-width: 576px) {
        .sd-row-cols-sm-2 {
            justify-content: left !important;
        }
    }

    .rst-content .section ul li,
    .rst-content .toctree-wrapper ul li,
    .rst-content section ul li,
    .wy-plain-list-disc li,
    article ul li {
        margin-left: 1px;
    }

    .rst-content .section ol li>*,
    .rst-content .section ul li>*,
    .rst-content .toctree-wrapper ol li>*,
    .rst-content .toctree-wrapper ul li>*,
    .rst-content section ol li>*,
    .rst-content section ul li>* {
        margin-top: 12px;
        margin-bottom: 0px;
    }

    .detail-list { list-style: none; margin: 0; padding: 0; }
    .row__cjH5p {
      display: grid;
      grid-template-columns: auto 271px;
      column-gap: 1rem;
      row-gap: 0.25rem;
      align-items: center;
      margin: 0.25em 0;
    }
    .label___SUfx {
      font-weight: bold;
      white-space: nowrap;
      text-align: left;
      margin-top: 12px !important;
    }
    .value__eRzvr {
      display: flex;
      justify-content: flex-start;
      align-items: center;
      text-align: left;
      overflow-wrap: anywhere;
      word-break: break-word;  /* allow wrapping */
    }
    .copyableText__Sj8Jf { display: flex; align-items: center; }
    .button__Tnm_Q { background: none; border: none; padding: 0; margin-right: 0.5em; cursor: pointer; }
    .inline__LYdsT { width: 16px; height: 16px; }
    .text__XTKyF { line-height: 1.3; white-space: normal; }

    .copied-text {
      color: green;
      font-weight: normal;
      opacity: 0;
      transition: opacity 0.2s ease-out;
      margin-left: 0;
      text-align: left;
    }
    .copied-text.show { opacity: 1; }

    /* MOBILE: stack label above value, allow wrapping */
    @media (max-width: 600px) {
      .row__cjH5p {
        display: block;
        margin-bottom: 15px;
      }
      .row__cjH5p .label___SUfx,
      .row__cjH5p .value__eRzvr {
        display: block;
        width: 100%;
        text-align: left;
        margin: 0;
      }
      .row__cjH5p .value__eRzvr {
        margin-top: 0.25rem;
      }
    }
   </style>

   <script>
     document.addEventListener('DOMContentLoaded', () => {
       document.querySelectorAll('.sd-card-body.docutils').forEach(card => {
         const p = card.querySelector('.sd-card-text');
         if (!p) return;

         const lines = p.innerHTML
           .split(/<br\s*\/?>/i)
           .map(l => l.replace(/\s+/g,' ').trim())
           .filter(Boolean);

         const ul = document.createElement('ul');
         ul.className = 'detail-list';

         lines.forEach(htmlLine => {
           const tmp = document.createElement('div');
           tmp.innerHTML = htmlLine;

           const strong = tmp.querySelector('strong');
           const label = strong
             ? strong.textContent.trim()
             : (htmlLine.match(/^(.*?:)/) || ['',''])[1];

           let value = '';
           const codes = tmp.querySelectorAll('code');
           if (codes.length) {
             value = Array.from(codes).map(c=>c.textContent.trim()).join(' ');
           } else {
             value = Array.from(tmp.childNodes)
               .filter(n=>n.nodeType===Node.TEXT_NODE)
               .map(n=>n.textContent.trim())
               .join(' ');
           }
           if (!label||!value) return;

           const li = document.createElement('li');
           li.className = 'row__cjH5p';

           const spanLabel = document.createElement('span');
           spanLabel.className = 'label___SUfx';
           spanLabel.textContent = label;

           const divValue = document.createElement('div');
           divValue.className = 'value__eRzvr';
           const inner = document.createElement('div');
           inner.className = 'copyableText__Sj8Jf';

           const btn = document.createElement('button');
           btn.type = 'button';
           btn.className = 'button__Tnm_Q';
           btn.innerHTML = `
             <svg viewBox="0 0 16 16" class="inline__LYdsT" aria-hidden="true">
               <path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"/>
               <path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"/>
             </svg>`;

           btn.addEventListener('click', () => {
             navigator.clipboard.writeText(value).then(() => {
               const original = btn.innerHTML;
               btn.innerHTML = '<span class="copied-text">Copied!</span>';
               requestAnimationFrame(() => {
                 const fb = btn.querySelector('.copied-text');
                 fb.classList.add('show');
               });
               setTimeout(() => {
                 const fb = btn.querySelector('.copied-text');
                 fb.classList.remove('show');
                 fb.addEventListener('transitionend', () => {
                   btn.innerHTML = original;
                 }, { once: true });
               }, 1000);
             });
           });

           const spanText = document.createElement('span');
           spanText.className = 'text__XTKyF';
           spanText.textContent = value;

           inner.appendChild(btn);
           inner.appendChild(spanText);
           divValue.appendChild(inner);
           li.appendChild(spanLabel);
           li.appendChild(divValue);
           ul.appendChild(li);
         });

         p.parentNode.replaceChild(ul, p);
       });
     });
   </script>

.. raw:: html

    <style>

    img.inline-img.no-shadow.black-end-white-monday {
        height: 25px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.black-end-white-zoho {
        filter: invert(1);
        height: 37px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.no-border {
        border-radius: 0px !important;
    }

    img.inline-img.no-shadow.no-top-margin.wide-img {
        height: 74px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
        max-height: 74px;                 /* Prevent vertical expansion */
        margin-top: 0 !important;         /* Remove top margin */
        padding-top: 0 !important;        /* Remove top padding */
        line-height: 0;                   /* Prevents line-height gaps */
        vertical-align: middle;           /* Align inline properly */
        object-fit: contain;              /* Ensures no distortion */
    }

        /* Make sure the parent container has a relative position if needed */
    .section-container {
      position: relative;
    }

    /* Light mode: show the SVG as a background element */
    html.light .styles_waves__tcfLl {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;    /* Adjust width as necessary */
      height: auto;   /* If needed you can set a fixed height */
      z-index: -1;    /* Place it behind all other content */
      pointer-events: none; /* Ensure it won't capture mouse events */
    }

    /* Dark mode: hide the SVG background */
    html.dark .styles_waves__tcfLl {
      display: none;
    }

        .styles_title__pmgeW {
            font-size: 64px;
            line-height: 76.8px;
            color: #023f7f
        }

      :root {
        /* LIGHT THEME */
        --sd-color-primary: #005fcc;
        --sd-color-card-background: var(--sd-color-card-background);
        --sd-color-card-text: #1e1e1e;
        --sd-color-card-border: #d1d5db;
        /* Shadow variable removed from use */

        --sy-c-border: #d1d5db;
        --sy-c-bold: #374151;
        --gray-1: #e5e7eb;
        --sd-gutter-x: 1rem;
        --sd-gutter-y: 1rem;
        --page-background: #ffffff;
      }

      [data-theme="dark"],
      html.dark {
        /* DARK THEME */
        --sd-color-card-background: #111111;
        --sd-color-card-text: #f9f9f9;
        /* No shadow is applied */

        --sy-c-border: #4b5563;
        --sy-c-bold: #fff;
        --page-background: #000000;
      }

      html, body {
        background-color: var(--page-background);
        color: var(--sd-color-card-text);
        transition: background-color 0.3s ease, color 0.3s ease;
      }

      /* This style mirrors your .sd-card and .sd-text-center rules without any box-shadow.
         It uses the theme colors and spacing, and includes a small hover scale effect */
      .surface {
        background-color: var(--sd-color-card-background);
        color: var(--sd-color-card-text);
        border: 1px solid var(--sd-color-card-border);
        border-radius: 15px;
        padding: var(--sd-gutter-y) var(--sd-gutter-x);
        transition: background-color 0.3s ease, color 0.3s ease, transform 0.15s ease-in-out;
        width: 100%;
        box-sizing: border-box;
      }

      .surface:hover {
        transform: scale(1.02);
      }

      /* Optional grid layout to display items in a row */
      .surface-grid {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: var(--sd-gutter-x);
        width: 100%;
      }

      @media (max-width: 991.98px) {
        .surface-grid {
          grid-template-columns: 1fr;
        }
      }

        /* Responsive Columns: Four */
    @media (min-width: 1728px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1532px) and (max-width: 1727.98px),
           (min-width: 992px) and (max-width: 1127.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1128px) and (max-width: 1531.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 24rem;
      }
    }

    @media (min-width: 768px) and (max-width: 991.98px),
           (min-width: 576px) and (max-width: 767.98px),
           (max-width: 575.98px) {
      .sd-row-cols-md-3 > *,
      .sd-row-cols-sm-3 > * {
        min-width: 100%;
      }
    }

    .sd-card-body {
        -ms-flex: 1 1 auto;
        flex: 1 1 auto;
        padding: 2rem 2rem 2rem 2rem;
    }

    .. .sd-row {
        margin-top: calc(var(--sd-gutter-y) * 3);
    }

    </style>



.. _billing_history_index:

===============
Billing History
===============

The Billing section provides a centralized view of all account-related financial activity. It includes access to detailed reports, payment history, service orders, and monthly invoices.

----

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`report` **Reports**
      :link: reports
      :link-type: doc

      Access detailed financial reports to analyze account activity and trends.

   .. grid-item-card:: :octicon:`credit-card` **Payments**
      :link: payments
      :link-type: doc

      Track and export payments, view details, download receipts, and manage pending transactions.

   .. grid-item-card:: :octicon:`file` **Orders**
      :link: orders
      :link-type: doc

      Track orders, view details, check status, and download confirmations.

   .. grid-item-card:: :octicon:`book` **Invoices**
      :link: monthly-invoices
      :link-type: doc

      View, download, and manage your monthly invoices and billing statements.

.. toctree::
   :maxdepth: 1
   :hidden:

   Reports <reports.rst>
   Payments <payments.rst>
   Orders <orders.rst>
   Invoices <monthly-invoices.rst>

.. raw:: html

    <style>

    img.inline-img.no-shadow.black-end-white-monday {
        height: 25px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.black-end-white-zoho {
        filter: invert(1);
        height: 37px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.no-border {
        border-radius: 0px !important;
    }

    img.inline-img.no-shadow.no-top-margin.wide-img {
        height: 74px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
        max-height: 74px;                 /* Prevent vertical expansion */
        margin-top: 0 !important;         /* Remove top margin */
        padding-top: 0 !important;        /* Remove top padding */
        line-height: 0;                   /* Prevents line-height gaps */
        vertical-align: middle;           /* Align inline properly */
        object-fit: contain;              /* Ensures no distortion */
    }

        /* Make sure the parent container has a relative position if needed */
    .section-container {
      position: relative;
    }

    /* Light mode: show the SVG as a background element */
    html.light .styles_waves__tcfLl {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;    /* Adjust width as necessary */
      height: auto;   /* If needed you can set a fixed height */
      z-index: -1;    /* Place it behind all other content */
      pointer-events: none; /* Ensure it won't capture mouse events */
    }

    /* Dark mode: hide the SVG background */
    html.dark .styles_waves__tcfLl {
      display: none;
    }

        .styles_title__pmgeW {
            font-size: 64px;
            line-height: 76.8px;
            color: #023f7f
        }

      :root {
        /* LIGHT THEME */
        --sd-color-primary: #005fcc;
        --sd-color-card-background: var(--sd-color-card-background);
        --sd-color-card-text: #1e1e1e;
        --sd-color-card-border: #d1d5db;
        /* Shadow variable removed from use */

        --sy-c-border: #d1d5db;
        --sy-c-bold: #374151;
        --gray-1: #e5e7eb;
        --sd-gutter-x: 1rem;
        --sd-gutter-y: 1rem;
        --page-background: #ffffff;
      }

      [data-theme="dark"],
      html.dark {
        /* DARK THEME */
        --sd-color-card-background: #111111;
        --sd-color-card-text: #f9f9f9;
        /* No shadow is applied */

        --sy-c-border: #4b5563;
        --sy-c-bold: #fff;
        --page-background: #000000;
      }

      html, body {
        background-color: var(--page-background);
        color: var(--sd-color-card-text);
        transition: background-color 0.3s ease, color 0.3s ease;
      }

      /* This style mirrors your .sd-card and .sd-text-center rules without any box-shadow.
         It uses the theme colors and spacing, and includes a small hover scale effect */
      .surface {
        background-color: var(--sd-color-card-background);
        color: var(--sd-color-card-text);
        border: 1px solid var(--sd-color-card-border);
        border-radius: 15px;
        padding: var(--sd-gutter-y) var(--sd-gutter-x);
        transition: background-color 0.3s ease, color 0.3s ease, transform 0.15s ease-in-out;
        width: 100%;
        box-sizing: border-box;
      }

      .surface:hover {
        transform: scale(1.02);
      }

      /* Optional grid layout to display items in a row */
      .surface-grid {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: var(--sd-gutter-x);
        width: 100%;
      }

      @media (max-width: 991.98px) {
        .surface-grid {
          grid-template-columns: 1fr;
        }
      }

        /* Responsive Columns: Four */
    @media (min-width: 1728px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1532px) and (max-width: 1727.98px),
           (min-width: 992px) and (max-width: 1127.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1128px) and (max-width: 1531.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 24rem;
      }
    }

    @media (min-width: 768px) and (max-width: 991.98px),
           (min-width: 576px) and (max-width: 767.98px),
           (max-width: 575.98px) {
      .sd-row-cols-md-3 > *,
      .sd-row-cols-sm-3 > * {
        min-width: 100%;
      }
    }

    .sd-card-body {
        -ms-flex: 1 1 auto;
        flex: 1 1 auto;
        padding: 2rem 2rem 2rem 2rem;
    }

    .. .sd-row {
        margin-top: calc(var(--sd-gutter-y) * 3);
    }

    </style>



.. _billing_history_reports:

Reports
=======

The **Reports** tab provides a high-level overview of your account’s recent billing activity. It consolidates key metrics, recent transactions, and graphical summaries into a single dashboard view for easy monitoring.

    - View summaries of your most recent payments, orders, and invoices.
    - Analyze your monthly billing structure using the invoice breakdown chart.
    - Monitor balance fluctuations over the last month.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Billing Reports Tab

   **Fig. 1.** Reports Tab Overview.

----

.. raw:: html

   <br>

Recent Activity Panels
----------------------

The upper portion of the Reports tab displays panels summarizing the latest transactions on your account:

    - **Last Payments** – Shows the most recent payment date, type, and amount.
    - **Last Orders** – Lists the latest orders including the date, service type, and amount.
    - **Last Invoices** – Displays the latest issued invoices with billing month and total amount including VAT.

Each panel includes a **View All** link for quick navigation to the full list in the corresponding section (Payments, Orders, Invoices).

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Recent Activity Panels

   **Fig. 2.** Recent Activity Panels.

----

.. raw:: html

   <br>

Invoice Breakdown by Month
---------------------------

This stacked bar chart provides a visual breakdown of invoice totals by service category across recent months. It helps you analyze which services contribute the most to your monthly expenses.
This stacked bar chart shows a monthly breakdown of invoice totals by service category over the past six months. It helps you analyze which services contribute most to your recurring costs.

Service categories include:

    - DIDs
    - Capacity
    - VAT
    - Origination and Termination
    - Messaging, A2P SMS and P2P SMS
    - phone.systems™
    - CNAM IN
    - Refunds
    - Others

Each bar represents one month and is color-coded by category. Hover over a segment to view detailed service-level spending.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Invoice Breakdown by Month Chart

   **Fig. 3.** Monthly Invoice Breakdown Chart.

----

.. raw:: html

   <br>

Balance History
---------------

The Balance History chart displays all changes to your account balance over the past month. It includes deposits, charges, refunds, and other transactions that affect your account credit.

Use this chart to track financial activity and ensure sufficient funds for uninterrupted service.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Balance History Chart

   **Fig. 4.** Balance History Chart.


.. |br| raw:: html

   <br/>

.. _billing_history_payments:

Payments
=========

The Payments tab provides a comprehensive history of all financial transactions on your account. Use this section to track your payment history, and manage any pending payments.

    - View key details for each payment: reference number, date, status, amount, and payment method.
    - Sort the list by clicking on any column header.
    - Filter payments by a specific date range or status.
    - Review transaction details, download receipts, and confirm or cancel payments.
    - Export your payment history to a CSV file for offline analysis.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Payments Tab

   **Fig. 1.** Payments Tab.

----

.. raw:: html

   <br>

Filters
-------

Use the filter controls to narrow down the list and find specific payments quickly.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Filter**
     - **Description**
   * - **Date**
     - Filter transactions based on their creation date using predefined ranges:

       * Today
       * Last 24 hours
       * This week
       * This month
       * Last 3 months
       * Custom range
   * - **Status**
     - Filter payments by their current processing state:

       * Completed
       * Action Required
       * Pending
       * Canceled

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Payments Filters

   **Fig. 2.** Payments Filters.

----

.. raw:: html

   <br>

Status and Actions
------------------------------------

Each payment has a status that determines the available actions you can take:

.. tab-set::
   :class: my-tabs

   .. tab-item:: Status

      Each payment has a status that indicates its current state in the billing process:

      .. list-table::
         :header-rows: 1
         :widths: 20 80

         * - **Status**
           - **Description**
         * - **Completed**
           - The payment was successfully processed and applied to your account.
         * - **Pending**
           - The payment is awaiting confirmation from the payment provider or staff.
         * - **Canceled**
           - The payment was canceled before completion and will not be applied.
         * - **Action Required**
           - Additional authentication is required to complete the payment.

   .. tab-item:: Actions

      Available actions depend on the current status of the payment:

      .. list-table::
         :header-rows: 1
         :widths: 20 80

         * - **Status**
           - **Available Actions**
         * - **Completed**
           -
             **Payment details** – View full transaction information |br|
             **Download payment receipt** – Download a PDF receipt
         * - **Pending**
           -
             **Payment details** – View full transaction information |br|
             **Cancel payment** – Cancel before processing
         * - **Canceled**
           -
             **Payment details** – View full transaction information
         * - **Action Required**
           -
             **Confirm payment** – Authenticate and complete the payment |br|
             **Payment details** – View full transaction information |br|
             **Cancel payment** – Cancel the payment request

      .. note::
         For **Action Required** payments, hover over the icon and click **Confirm Payment** to complete the authentication process.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Payments Status and Actions

   **Fig. 3.** Payments Status and Actions.

----

.. raw:: html

   <br>

Export
------

Click the |export| button to access the **Export Payments** section. You can specify a date range and apply filters to generate a customized export file.

For detailed instructions, see :ref:`Export Payments <userpanel_exports_payments>`.

    .. figure:: https://doc.didww.com/_images/fig4.png
       :figclass: align-center
       :alt: Payments Export Button

       **Fig. 4.** Payments Export Button.

.. |export| image:: /img/new_user_panel/billing/orders/export.png
   :class: inline-img no-shadow

.. _billing_history_orders:

Orders
======

The Orders tab provides a complete overview of all service orders associated with your account. You can track the status of each order, view detailed information, download confirmations, and export order history.

    - View essential details for each order: reference number, date, status, amount, and type.
    - Sort the list by clicking on any column header.
    - Filter orders by a specific date range, reference number, status, or refund status.
    - Access order details and download confirmation documents.
    - Export your order history to a file for offline analysis.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Orders Tab

   **Fig. 1.** Orders Tab.

----

.. raw:: html

   <br>

Filters
-------

Use the filter and export options to narrow down and customize the list of orders based on specific criteria.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - **Filter**
     - **Description**
   * - **Date**
     - Filter orders based on their creation date using predefined ranges:

       * Today
       * Last 24 hours
       * This week
       * This month
       * Last 3 months
       * Custom range
   * - **Reference**
     - Filter by the order's reference number.
   * - **Status**
     - Filter orders by their current processing state:

       * Completed
       * Canceled
       * Pending
   * - **Refunded**
     - Filter orders by refund status:

       * Yes
       * No

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Orders Filters

   **Fig. 2.** Orders Filters.

----

.. raw:: html

   <br>

Status and Actions
------------------

Each order includes a status that determines what actions are available.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Status

      .. list-table::
         :header-rows: 1
         :widths: 25 75

         * - **Status**
           - **Description**
         * - **Completed**
           - The order was successfully fulfilled.
         * - **Pending**
           - The order is being processed.
         * - **Canceled**
           - The order was canceled and will not be processed.

   .. tab-item:: Actions

      .. list-table::
         :header-rows: 1
         :widths: 10 20

         * - **Action**
           - **Description**
         * - **Order Details**
           - View full order information.
         * - **Download Order Confirmation**
           - Download a confirmation PDF for a completed order.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Orders Status and Actions

   **Fig. 3.** Orders Status and Actions.

----

.. raw:: html

   <br>

Export
------

Click the |export| button to open the **Export Orders** section. From there, you can define a date range and apply filters to generate a customized export file.

For more details, see the :ref:`Export Orders <userpanel_exports_orders>` documentation.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Orders Export Button

   **Fig. 4.** Orders Export Button.

.. |actions| image:: /img/new_user_panel/billing/orders/actions.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 15px

.. |export| image:: /img/new_user_panel/billing/orders/export.png
   :class: inline-img no-shadow


.. _billing_history_invoices:

.. _user_panel_billing_invoice:

Invoices
========

The Invoices tab provides a monthly summary of charges for your account. Each entry represents the invoice for a specific month, including subtotal, VAT, and total amounts. You can access detailed invoice information and download invoice files directly from this tab.

    - View invoices grouped by **year** and **month**, with their corresponding **subtotal**, **VAT**, and **total** values.
    - Open detailed invoice information.
    - Download a copy of the invoice in PDF format.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center
   :alt: Invoices Tab

   **Fig. 1.** Invoices Tab.

----

.. raw:: html

   <br>

Actions
-------

Each invoice includes available actions for accessing more details or downloading a copy of the invoice.

.. list-table::
   :header-rows: 1
   :widths: 1 5

   * - **Action**
     - **Description**
   * - **Invoice Details**
     - Opens a page displaying full invoice information, including line items such as services, quantities, and pricing.
   * - **Download Invoice**
     - Downloads the invoice as a PDF document.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Invoices Actions Menu

   **Fig. 2.** Invoices Actions Menu.

.. raw:: html

   <br>

Invoice Details View
^^^^^^^^^^^^^^^^^^^^

Select **Invoice Details** to view a breakdown of charges for the billing period.

.. note:: Invoices are also automatically delivered to the customer's email address each month.

The Amount Info section shows:

    - **Service** – The billed product or service (e.g., DID service, phone.systems™ Seats)
    - **Quantity** – Number of billed units
    - **Setup** – One-time setup fee
    - **Monthly** – Recurring monthly charge
    - **Subtotal** – Amount per line item before tax

At the bottom of the page:

    - **Subtotal** – Total before VAT
    - **VAT** – Tax amount and rate
    - **Total** – Final amount with tax included

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Invoice Details View

   **Fig. 3.** Invoice Details View.


.. _billing_quickstart:

===============
Getting Started
===============

This guide provides a step-by-step walkthrough to help you quickly set up and configure your billing and payment methods on the DIDWW user panel. By following these steps, you can ensure your account is always funded, your services remain active, and your billing is managed efficiently.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item-card:: **1. Add a Credit Card**
      :link: billing_qs_add_card
      :link-type: ref
      :text-align: center

      Securely add your primary payment method to the platform.

   .. grid-item-card:: **2. Configure Auto Balance Top-Up**
      :link: billing_qs_auto_topup
      :link-type: ref
      :text-align: center

      Configure rules to automatically refill your balance when it runs low.

   .. grid-item-card:: **3. Configure Low Balance Notifications**
      :link: billing_qs_email_notification
      :link-type: ref
      :text-align: center

      Get email alerts before an auto top-up is performed.

----

.. raw:: html

    <br>

.. _billing_qs_before_you_begin:

Before You Begin
----------------

Before you start, make sure you have the following:

    - **A DIDWW Account:**  You’ll need an active DIDWW account. If you don’t have one yet, `Sign up here <https://my.didww.com/#/users/sign_up>`_.
    - **Payment Method:** Prepare a valid payment method.
    - **Access Permissions:** Confirm that you have the necessary permissions. If you’re unsure about your access level, review the available :ref:`User Roles <user_panel_roles>`.

----

.. raw:: html

    <br>

.. _billing_qs_add_card:

Step 1: Add a Credit Card
-------------------------

    1.  Sign in to the `DIDWW User Panel <https://my.didww.com/>`_.
    2.  Go to **Billing > Payment Methods** or `click here <https://my.didww.com/#/payment_methods>`_.
    3.  Click the **Add Payment Method** and select **Credit Card**.
    4.  Enter your card details in the form and click **Submit**.
    5.  Complete the **3-D Secure authentication** to finish.

.. note::
   The first card you add will have **Auto-charge** enabled by default.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: The form for adding credit card and billing details.

   **Fig. 1.** The form for adding credit card and billing details.

.. raw:: html

    <br>

----

.. _billing_qs_auto_topup:

Step 2: Configure Auto Balance Top-Up
-------------------------------------

Once you have a card added, you can configure the system to automatically top up your balance when it runs low. This is the recommended way to ensure uninterrupted service.

    1.  On the **Payment Methods** page, locate the **Low Balance Settings** panel on the right.
    2.  Enable the **Automatically refill when threshold is reached** toggle.
    3.  Enter the **Threshold amount** (when top-up should trigger) and the **Refill amount**.
    4.  Click **Apply Changes** to save your settings.

.. figure:: https://doc.didww.com/_images/low-balance.png
   :figclass: align-center
   :alt: Configuring automatic balance top-up.

   **Fig. 2.** Configuring automatic balance top-up.

.. raw:: html

    <br>

----

.. _billing_qs_email_notification:

Step 3: Set Up Low Balance Notifications
----------------------------------------

Enable email notifications to get notified when your account balance falls below a defined threshold.

    1.  In the **Low Balance Settings** panel, enable the **Low balance notification** toggle.
    2.  Enter the minimum balance that will trigger the email alert.
    3.  Click **Apply Changes**.

.. figure:: https://doc.didww.com/_images/low-balance-notification.png
   :figclass: align-center
   :alt: Low balance notification configuration.

   **Fig. 3.** Low balance notification configuration.

.. raw:: html

    <br>

----

Additional Resources
---------------------

.. card:: **Purchase Your First Number**
   :link: user_panel_purchase
   :link-type: ref

   Now that your billing is ready, explore and purchase DID numbers.

.. card:: **Payment Automation and Notifications**
   :link: billing_payment_methods_actions
   :link-type: ref

   Learn how to automate payments, manage charge priorities, and retry failed payment methods.

.. |br| raw:: html

    <br>

.. _billing_payment_methods_credit_cards:

============
Credit Card
============

This section explains how to manage credit cards as a payment method for your account. Keeping an active credit card on file ensures uninterrupted service and makes it easy to add funds to your account balance.

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Add Credit Card**
      :link: billing_add_credit_card
      :link-type: ref
      :text-align: center

      Learn how to add a new credit card to your account.

   .. grid-item-card:: **Manage Credit Cards**
      :link: billing_manage_credit_cards
      :link-type: ref
      :text-align: center

      Learn how to configure and manage credit card payment methods.

.. raw:: html

    <br>

----

.. _billing_add_credit_card:

Add a Credit Card
------------------

    1.  Navigate to the **Billing** section in the left-hand menu and select **Payment Methods**.
    2.  Click the **Add Payment Method** button.
    3.  Select **Credit Card** from the dropdown list.

        .. figure:: https://doc.didww.com/_images/fig2.png
           :figclass: align-center
           :alt: Selecting Credit Card as a payment method.

           **Fig. 1.** Choosing the Credit Card option.

    4.  Fill in the required fields in the **Add New Credit Card** form:

         - Card number
         - Expiry date
         - Security code (CVV)
         - Cardholder name and billing address details
    5.  Click **Submit** to save the new credit card.

    6. A pop-up window will appear for **3-D Secure authentication** provided by the issuing bank. Complete this verification to successfully add your credit card to DIDWW.

.. note:: By default, your first payment method will have Auto-charge enabled. You can disable this feature at any time. See :ref:`Auto-charge Settings<billing_manage_autocharge>` to manage this.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Add New Credit Card form.

   **Fig. 2.** The form for adding credit card and billing details.

.. raw:: html

    <br>

----

.. _billing_manage_credit_cards:

Manage Credit Cards
------------------------

After adding one or more credit cards, they will be listed under your payment methods. From this interface, you can set a primary card, configure auto-charge options, add funds, or remove a card.

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **Set Credit Card Auto-charge Priority**
      :link: billing_manage_priority
      :link-type: ref
      :text-align: center

      Set the priority order of your credit cards for automatic payments.

   .. grid-item-card:: **Manage Auto-Charge Settings**
      :link: billing_manage_autocharge
      :link-type: ref
      :text-align: center

      Enable or disable automatic payments.

   .. grid-item-card:: **Add Funds Using Credit Card**
      :link: billing_manage_add_funds
      :link-type: ref
      :text-align: center

      Manually add funds to your account prepaid balance.

   .. grid-item-card:: **Remove Credit Card**
      :link: billing_manage_remove_card
      :link-type: ref
      :text-align: center

      Remove a credit card from your payment methods.

----

.. raw:: html

    <br>

.. _billing_manage_priority:

Set Credit Card Auto-charge Priority
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When you have multiple cards, you can set one as the primary card for auto-charging. This card is marked with a star icon in the **Priority** column.

    1.  Click and hold the handle icon (☰) for the card you wish to prioritize.
    2.  Drag the card to the top of the list and release.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Set Card Priority.

   **Fig. 3.** Set Card Priority.

----

.. raw:: html

    <br>

.. _billing_manage_autocharge:

Manage Auto-Charge Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The **Auto-charge** feature automatically adds funds from your primary credit card when your account balance drops below a predefined threshold.

    1.  Find the card in the **Payment Methods** list.
    2.  Toggle the switch in the **Auto-charge** column.

.. note:: The card marked with a star icon in the **Priority** column will be used for automatic payments.

.. figure:: https://doc.didww.com/_images/fig4.1.png
   :figclass: align-center
   :alt: Automatic Payments.

   **Fig. 4.** Automatic Payments.

----

.. raw:: html

    <br>

.. _billing_manage_add_funds:

Add Funds Using Credit Card
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To manually add funds to your account balance, click the **Add Funds** button and choose one of the available options from the top of the modal window.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item-card:: **Auto-Charge**
      :link: billing_payment_methods_credit_cards_autocharge
      :link-type: ref
      :text-align: center

      Automatically top up your balance using the primary credit card with auto-charge enabled.

   .. grid-item-card:: **Credit Card**
      :link: billing_payment_methods_credit_cards_saved_card
      :link-type: ref
      :text-align: center

      Add funds using a saved credit card or choose Instant Payment for a one-time top-up.

   .. grid-item-card:: **Instant Payment**
      :link: billing_add_funds_instant_payment
      :link-type: ref
      :text-align: center

      Make a one-time payment using new credit card details without saving them to your account.

.. raw:: html

    <br>

.. _billing_payment_methods_credit_cards_autocharge:

Top Up Using Auto-Charge Enabled Credit Card
""""""""""""""""""""""""""""""""""""""""""""""

Use this option to top up your account using the credit card that has auto-charge enabled. If multiple cards have auto-charge active, the top-priority card (i.e., the first in the list) will be used for the transaction.

    1.  Click **Add Funds**.
    2.  Select the **Auto-charge** tab.
    3.  Click **Confirm** to add the specified amount to your balance.

.. important::
    - Auto-Charge will always utilize the :ref:`prioritized payment method first <billing_manage_priority>`.
    - The minimum payment amount is 30 USD.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: The Add Funds modal showing the Auto-charge option.

   **Fig. 5.** Topping up using the auto-charge amount.

.. raw:: html

    <br>

.. _billing_payment_methods_credit_cards_saved_card:

Top Up Using Saved Credit Card
"""""""""""""""""""""""""""""""""""

This option allows you to specify a custom amount and choose the credit card.

    1.  Click **Add Funds**.
    2.  Select the **Credit Card** tab.
    3.  Enter the amount you wish to add in the **Top up amount (USD)** field.
    4.  Select your saved credit card from the **Choose payment option** dropdown menu.
    5.  Click **Confirm** to complete the payment.

.. note:: The minimum payment amount is 30 USD.

.. figure:: https://doc.didww.com/_images/fig6.png
   :figclass: align-center
   :alt: Selecting a credit card to complete the payment.

   **Fig. 6.** Topping up with a specific credit card.

.. raw:: html

    <br>

.. _billing_add_funds_instant_payment:

Top Up Using Instant Payment
""""""""""""""""""""""""""""""

The Instant Payment option allows you to perform a one-time, manual payment at any time.

    1.  Click the **Add Funds** button from the Payment Methods screen.
    2.  From the **Choose payment option** dropdown menu, select the **Instant Payment** option.
    3.  Enter your desired top-up amount.
    4.  Click **Confirm** to proceed to the secure window for a one-time transaction.
    5.  On the secure page, provide your contact and credit card details, then click **Pay** to complete the transaction.

.. important::
       - For European Economic Area (EEA) cardholders, this process uses **3D Secure 2 authorization** as required by PSD2 regulations. |br|
       - The minimum payment amount is 30 USD.

.. figure:: https://doc.didww.com/_images/instant-payment.png
   :figclass: align-center
   :alt: Performing a manual payment.

   **Fig. 6.** Performing a manual payment.

----

.. raw:: html

    <br>

.. _billing_manage_remove_card:

Remove Credit Card
^^^^^^^^^^^^^^^^^^^^^

    1.  Navigate to the **Payment Methods** screen.
    2.  Find the credit card you wish to remove in the list.
    3.  Click the **Delete** icon **x** in the corresponding row.
    4.  Confirm the removal in the confirmation dialog.

    .. figure:: https://doc.didww.com/_images/fig7.png
       :figclass: align-center
       :alt: Remove a credit card.

       **Fig.7.** Remove a credit card.

----

.. raw:: html

    <br>

Additional Information
----------------------

.. card:: **Wire Transfer**
    :link: billing_payment_methods_wire_transfer
    :link-type: ref

    Learn how to add and manage wire transfer payments.

.. card:: **Billing History**
    :link: billing_history_index
    :link-type: ref

    View your transaction history, download invoices, and check your current balance.

.. card:: **Payment Actions**
    :link: billing_payment_methods_actions
    :link-type: ref

    Manage auto-charge, set payment priority, configure automatic top-ups, and receive low balance alerts.

.. raw:: html

    <style>
        .rst-content .section ul, .rst-content .toctree-wrapper ul, .rst-content section ul, .wy-plain-list-disc, article ul {
            margin-bottom: 0px;
            vertical-align: middle;
        }

    .sd-tab-content {
        box-shadow: none;
    }
    .sd-tab-set>label {
        border-color: var(--sd-color-tabs-underline);
        color: inherit;
    }

    /* Green check-circle /
    .sd-octicon-x-circle {
        color: #d73a49;
        fill: currentColor;
    }

    / Red x-circle /
    .sd-octicon-check-circle {
        color: #28a745;
        fill: currentColor;
    }

    .hide-table {
        display: none;
    }

    </style>

.. raw:: html

   <style>
     em {
       font-size: 115%;
       font-weight: 700 !important;
       font-style: normal !important; / Removes italic if desired */
       font-family: Roobert-semibold !important;
     }
   </style>

.. _billing_payment_methods:

===============
Payment Methods
===============

Manage your billing setup with flexible, prepaid payment options:

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`credit-card` **Credit Cards**
      :link: billing_payment_methods_credit_cards
      :link-type: ref
      :text-align: left

      Manage credit card payments and securely add or update cards for your prepaid account.

   .. grid-item-card:: :iconify:`ic:baseline-paypal` **PayPal**
      :link: billing_payment_methods_paypal
      :link-type: ref
      :text-align: left

      Set up PayPal for manual or automatic prepaid balance refills.

   .. grid-item-card:: :fa:`university` **Wire Transfers**
      :link: billing_payment_methods_wire_transfer
      :link-type: ref
      :text-align: left

      Configure manual wire transfers for funding your prepaid balance.

Customize your payment behavior with:

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`sync` **Auto-charge Settings**
      :link: billing_actions_autocharge
      :link-type: ref
      :text-align: left

      Automate balance top-ups when your account reaches a low threshold.

   .. grid-item-card:: :octicon:`list-ordered` **Auto-charge Priority**
      :link: billing_actions_priority
      :link-type: ref
      :text-align: left

      Set the order of payment methods used for automated top-ups.

   .. grid-item-card:: :octicon:`bell` **Low Balance Settings**
      :link: billing_actions_low_balance_settings
      :link-type: ref
      :text-align: left

      Receive notifications or trigger auto top-ups when your balance runs low.

   .. grid-item-card:: :fa:`bolt` **Instant Payments**
      :link: billing_add_funds_instant_payment
      :link-type: ref
      :text-align: left

      Instantly add funds manually or retry failed payments with one click.

.. toctree::
  :maxdepth: 1
  :hidden:

  Credit Cards <credit-card.rst>
  Wire Transfer <wire-transfer.rst>
  Paypal <paypal.rst>
  Payment Automation and Notifications <payment-actions.rst>


.. _billing_payment_methods_wire_transfer:

=============
Wire Transfer
=============

This section explains how to add funds to your account using a wire transfer. This is a manual process that requires creating a transfer request in the DIDWW system and then completing the payment through your bank.

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Create a Wire Transfer**
      :link: billing_create_wire_transfer
      :link-type: ref
      :text-align: center

      Learn how to initiate a new wire transfer request.

   .. grid-item-card:: **Manage Wire Transfers**
      :link: billing_manage_wire_transfers
      :link-type: ref
      :text-align: center

      View details, upload proof of payment, and track statuses.

.. raw:: html

    <br>

----

.. _billing_create_wire_transfer:

Create a Wire Transfer
----------------------

Follow these steps to create a new wire transfer request. This will generate the necessary payment details, including a unique reference ID required to process your payment.

    1.  Navigate to the **Billing** section in the left-hand menu and select **Payment Methods**.
    2.  Click the **Wire Transfer** tab. This screen displays the bank details for making payments in USD or EUR.

        .. figure:: https://doc.didww.com/_images/fig1.png
           :figclass: align-center
           :alt: The Wire Transfer tab showing bank details.

           **Fig. 1.** The Wire Transfer screen.

    .. raw:: html

        <br>

    3.  Click the **Create New** button.
    4.  In the **Add Funds** modal, enter the **Amount** you intend to transfer and select the **Currency**.

        .. note:: The minimum payment amount is 30 USD.

        .. figure:: https://doc.didww.com/_images/fig2.png
           :figclass: align-center
           :alt: Add Funds modal for wire transfer.

           **Fig. 2.** Specifying the transfer amount and currency.

    .. raw:: html

        <br>

    5.  Click **Confirm**. A new wire transfer record will be created with the status **New**.

        .. figure:: https://doc.didww.com/_images/fig3.png
           :figclass: align-center
           :alt: The list of wire transfers with a new request.

           **Fig. 3.** The new wire transfer request added to the list.

.. raw:: html

    <br>

----

.. _billing_manage_wire_transfers:

Manage Wire Transfers
------------------------

After creating a request, you must complete the payment through your bank and upload proof of payment to DIDWW for processing.

Processing Your Transfer Request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Step 1: Make the Bank Transfer
""""""""""""""""""""""""""""""

    1.  In the list of wire transfers, find your new request and click the **Details** (|details|) icon in the corresponding row.
    2.  On the **Wire Transfer Details** page, carefully note the bank details and the unique **Payment Reference ID**.
    3.  Log in to your bank's online portal and make the wire transfer using the details provided.

        .. important::
           You **must** include the **Payment Reference ID** in your wire transfer instructions with your bank. Failure to do so may result in significant delays or the payment not being applied to your account.

        .. figure:: https://doc.didww.com/_images/fig4.png
           :figclass: align-center
           :alt: Wire transfer details page with reference ID.

           **Fig. 4.** Payment details and the unique reference ID.

Step 2: Upload Proof of Payment
"""""""""""""""""""""""""""""""

    1.  Save a screenshot or download a receipt of the completed transaction from your bank.
    2.  Return to the **Wire Transfer Details** page in the DIDWW portal and click **Select file** to upload your proof of payment.

        .. figure:: https://doc.didww.com/_images/fig4.1.png
           :figclass: align-center
           :alt: Uploading proof of payment.

           **Fig. 5.** A proof of payment file selected for upload.

    3.  Click **Confirm** to submit the proof for review. The status of your transfer will change to **Pending**.

        .. figure:: https://doc.didww.com/_images/fig5.png
           :figclass: align-center
           :alt: Submit the proof for review.

           **Fig. 6.** Submit the proof for review.

Statuses
^^^^^^^^

The status of your wire transfer indicates its stage in the payment process.

    .. list-table::
       :widths: 15 85
       :header-rows: 1

       * - Status
         - Description
       * - |new|
         - The wire transfer request has been created, but proof of payment has not yet been uploaded.
       * - |pending|
         - Proof of payment has been uploaded and is awaiting review.
       * - |completed|
         - The payment has been approved, the funds have been added to your account balance, and a receipt has been sent to your email.

    .. figure:: https://doc.didww.com/_images/fig6.png
       :figclass: align-center
       :alt: A completed wire transfer.

       **Fig. 7.** A completed wire transfer with its status updated in the list.

----

.. raw:: html

    <br>

Additional Information
----------------------

.. card:: **Credit Card Payments**
    :link: billing_payment_methods_credit_cards
    :link-type: ref

    Learn how to add and manage credit cards for automatic and manual payments.

.. card:: **Billing History**
    :link: billing_history_index
    :link-type: ref

    View your transaction history, download invoices, and check your current balance.

.. card:: **Payment Actions**
    :link: billing_payment_methods_actions
    :link-type: ref

    Manage auto-charge, set payment priority, configure automatic top-ups, and receive low balance alerts.

.. |details| image:: /img/new_user_panel/payment_methods/wire_transfer/details.png
   :class: inline-img no-shadow
   :width: 20px
   :height: 22px

.. |new| image:: /img/new_user_panel/payment_methods/wire_transfer/new.png
   :class: inline-img no-shadow
   :width: 51px
   :height: 20px

.. |pending| image:: /img/new_user_panel/payment_methods/wire_transfer/pending.png
   :class: inline-img no-shadow
   :width: 72px
   :height: 20px

.. |completed| image:: /img/new_user_panel/payment_methods/wire_transfer/completed.png
   :class: inline-img no-shadow
   :width: 86px
   :height: 20px



.. _billing_payment_methods_paypal:

======
PayPal
======

This section explains how to add and manage PayPal as a payment method. Linking your PayPal account allows for seamless manual payments and is ideal for setting up automatic, recurring payments to ensure your services are never interrupted.

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Add PayPal Account**
      :link: billing_add_paypal
      :link-type: ref
      :text-align: center

      Learn how to add your PayPal account to DIDWW payment methods.

   .. grid-item-card:: **Manage PayPal Payment Method**
      :link: billing_manage_paypal
      :link-type: ref
      :text-align: center

      Manage auto-charge, add funds, and remove the PayPal payment method.

.. raw:: html

    <br>

----

.. _billing_add_paypal:

Add PayPal Account
--------------------------

.. note::
   PayPal Payment Method is not enabled by default. Contact your account manager or our billing department at `billing@didww.com <mailto:billing@didww.com>`_ to request access.

Follow these steps to link your PayPal account. This process creates a billing agreement that authorizes DIDWW to charge your PayPal account for future payments.

    1.  Navigate to the **Billing** section in the left-hand menu and select **Payment Methods**.
    2.  Click **Add Payment Method**, then select **PayPal** from the dropdown.

        .. figure:: https://doc.didww.com/_images/fig1.png
           :figclass: align-center
           :alt: Selecting PayPal as a payment method.

           **Fig. 1.** Choosing the PayPal option.

    .. raw:: html

        <br>

    3.  In the confirmation window, click **Confirm** to proceed to PayPal’s secure website.

        .. figure:: https://doc.didww.com/_images/fig2.png
           :figclass: align-center
           :alt: Add PayPal confirmation modal.

           **Fig. 2.** Confirmation to proceed to the PayPal website.

    .. raw:: html

        <br>

    4.  Log in to your PayPal account and authorize the billing agreement with DIDWW.

        .. figure:: https://doc.didww.com/_images/fig3.png
           :figclass: align-center
           :alt: The PayPal login screen.

           **Fig. 3.** Authorizing the payment agreement on the PayPal website.

    .. raw:: html

        <br>

    5.  After authorization, you will be redirected back to DIDWW. PayPal will now appear in your list of payment methods.

        .. note:: Auto-charge is enabled by default for your first payment method. You can disable it at any time. See :ref:`Auto-charge Settings <billing_paypal_autocharge>`.

        .. figure:: https://doc.didww.com/_images/fig4.png
           :figclass: align-center
           :alt: A linked PayPal payment method.

           **Fig. 4.** A successfully linked PayPal payment method in the list.

.. raw:: html

    <br>

----

.. _billing_manage_paypal:

Manage PayPal Payment Method
-----------------------------

After adding PayPal Account, you can manage its settings, add funds manually, or remove it from your account.

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **Set PayPal Account Auto-charge Priority**
      :link: billing_paypal_priority
      :link-type: ref
      :text-align: center

      Choose PayPal as your default method for auto-charging.

   .. grid-item-card:: **Manage Auto-charge Settings**
      :link: billing_paypal_autocharge
      :link-type: ref
      :text-align: center

      Enable or disable automatic payments.

   .. grid-item-card:: **Add Funds Using PayPal**
      :link: billing_paypal_add_funds
      :link-type: ref
      :text-align: center

      Top up your balance using your PayPal account.

   .. grid-item-card:: **Remove PayPal Account**
      :link: billing_paypal_remove
      :link-type: ref
      :text-align: center

      Unlink your PayPal account from DIDWW payment methods.

----

.. raw:: html

    <br>

.. _billing_paypal_priority:

Set PayPal Account Priority
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When you have multiple payment methods, you can set one as the primary method for auto-charging. This is marked with a star icon in the **Priority** column.

    1.  Click and hold the handle icon (☰) for the payment method you wish to prioritize.
    2.  Drag it to the top of the list and release.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Set Payment Method Priority.

   **Fig. 5.** Setting Payment Method Priority.

----

.. raw:: html

    <br>

.. _billing_paypal_autocharge:

Manage PayPal Auto-charge Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The **Auto-charge** feature is the primary use for a linked PayPal account, automatically adding funds when your balance is low.

    1.  Find your PayPal payment method in the **Payment Methods** list.
    2.  Toggle the switch in the **Auto-charge** column.

    .. figure:: https://doc.didww.com/_images/fig4.1.png
       :figclass: align-center
       :alt: Auto-charge settings.

       **Fig. 6.** Auto-charge settings.

----

.. raw:: html

    <br>

.. _billing_paypal_add_funds:

Add Funds Using PayPal
^^^^^^^^^^^^^^^^^^^^^^^

To manually add funds to your account balance, click the **Add Funds** button and choose one of the available options from the top of the modal window.

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Auto-Charge**
      :link: billing_paypal_add_funds_autocharge
      :link-type: ref
      :text-align: center

      Top up using your pre-configured auto-charge amount.

   .. grid-item-card:: **PayPal**
      :link: billing_paypal_add_funds_manual
      :link-type: ref
      :text-align: center

      Top up with a custom amount via PayPal.

.. raw:: html

    <br>

.. _billing_paypal_add_funds_autocharge:

Top Up Using Auto-Charge Enabled PayPal Account
""""""""""""""""""""""""""""""""""""""""""""""""

This option uses your pre-configured auto-charge amount to top up your account.

    1.  Click **Add Funds**.
    2.  Select the **Auto-charge** tab.
    3.  Click **Confirm** to add the specified amount to your balance.

.. important::
    - Auto-Charge will always utilize the :ref:`prioritized payment method first <billing_manage_priority>`.
    - The minimum payment amount is 30 USD.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: The Add Funds modal showing the Auto-charge option.

   **Fig. 7.** Topping up using the auto-charge amount.

.. raw:: html

    <br>

.. _billing_paypal_add_funds_manual:

Top Up Using Linked PayPal Account
"""""""""""""""""""""""""""""""""""

This option allows you to specify a custom amount to pay with your linked PayPal account.

    1.  Click **Add Funds**.
    2.  Select the **PayPal** tab.
    3.  Enter the amount you wish to add in the **Top up amount (USD)** field. The minimum payment amount is 30 USD.
    4.  Select your linked PayPal account from the **Choose payment option** dropdown menu.
    5.  Click **Confirm** to complete the payment.

    .. note::
           A transaction fee may be applied to payments made with PayPal.

.. figure:: https://doc.didww.com/_images/fig6.png
   :figclass: align-center
   :alt: Selecting PayPal to complete the payment.

   **Fig. 8.** Topping up with a specific amount via PayPal.

----

.. raw:: html

    <br>

.. _billing_paypal_remove:

Remove PayPal Account
^^^^^^^^^^^^^^^^^^^^^^

    1.  Navigate to the **Payment Methods** screen.
    2.  Find the PayPal payment method you wish to remove.
    3.  Click the **Delete** icon **x** in the corresponding row.
    4.  Confirm the removal in the confirmation dialog.

.. figure:: https://doc.didww.com/_images/fig7.png
   :figclass: align-center
   :alt: Remove PayPal Payment Method.

   **Fig. 9.** Remove PayPal Payment Method.

.. raw:: html

    <br>

----

Additional Information
----------------------

.. card:: **Credit Card Payments**
    :link: billing_payment_methods_credit_cards
    :link-type: ref

    Learn how to add and manage credit cards for payments.

.. card:: **Wire Transfer**
    :link: billing_payment_methods_wire_transfer
    :link-type: ref

    Find instructions for funding your account via bank transfer.

.. card:: **Payment Actions**
    :link: billing_payment_methods_actions
    :link-type: ref

    Manage auto-charge, set payment priority, configure automatic top-ups, and receive low balance alerts.


.. _billing_payment_methods_actions:

====================================
Payment Automation and Notifications
====================================

This section outlines the tools available to help you manage your account balance efficiently and ensure uninterrupted service. By combining features such as auto-charge, payment prioritization, automatic top-ups, and low balance alerts, you can create a reliable and flexible billing strategy.

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **Enable Auto-Charge Payments**
      :link: billing_actions_autocharge
      :link-type: ref
      :text-align: center

      Authorize payment methods for automated billing.

   .. grid-item-card:: **Set Auto-charge Priority**
      :link: billing_actions_priority
      :link-type: ref
      :text-align: center

      Set the priority order of your payment methods for automatic payments.

   .. grid-item-card:: **Configure Low Balance Settings**
      :link: billing_actions_low_balance_settings
      :link-type: ref
      :text-align: center

      Configure automatic balance top-ups and receive email alerts when your balance is low.

   .. grid-item-card:: **Retry Failed Payment Method**
      :link: billing_actions_retry
      :link-type: ref
      :text-align: center

      Manually retry a failed payment and restore auto-charge for temporarily disabled payment methods.

----

.. raw:: html

    <br>

.. _billing_actions_autocharge:

Enable Auto-charge Payments
------------------------------

Auto-charge is a setting that authorizes a payment method (e.g., credit card or PayPal) to be used for automatic transactions. It is required for features like :ref:`Top Up Using Auto-Charge Enabled Credit Card <billing_payment_methods_credit_cards_autocharge>` and :ref:`Auto Balance Top-Up <billing_actions_autotopup>`.

    1.  Navigate to **Billing > Payment Methods**.
    2.  Find the desired payment method in the list.
    3.  Use the **Auto-charge** toggle in the corresponding row to enable or disable the feature.

.. important::

   The :ref:`Auto Balance Top-Up <billing_actions_autotopup>` feature only works if Auto-charge is enabled on your **primary** payment method. If disabled, no automatic payments will be processed, even if the low balance threshold is reached.

.. figure:: https://doc.didww.com/_images/fig4.1.png
   :figclass: align-center
   :alt: Auto-charge Toggle.

   **Fig. 1.** Auto-charge Toggle.

----

.. raw:: html

    <br>

.. _billing_actions_priority:

Set Auto-charge Priority
-------------------------

When multiple payment methods have :ref:`auto-charge <billing_actions_autocharge>` enabled, you can define the order in which they are used by setting their **priority**. The method at the top of the list, marked with a star icon, is treated as the **primary method** for all automated transactions.

    1.  Go to **Billing > Payment Methods**.
    2.  Click and hold the ☰ icon next to the payment method you wish to prioritize.
    3.  Drag it to the top of the list and release. The star icon will move to indicate the new primary method.

.. note::
      If a charge to the primary payment method fails (e.g., due to insufficient funds or a bank decline), the system will automatically attempt to charge the next available method that has the auto-charge toggle enabled.

.. figure:: https://doc.didww.com/_images/gif1.gif
   :figclass: align-center
   :alt: Set payment priority

   **Fig. 3.** Reordering methods to set priority.

----

.. raw:: html

    <br>

.. _billing_actions_low_balance_settings:

Configure Low Balance Settings
------------------------------

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Auto Balance Top-Up**
      :link: billing_actions_autotopup
      :link-type: ref
      :text-align: center

      Automatically refill your balance when it drops below a set threshold.

   .. grid-item-card:: **Low Balance Notification**
      :link: billing_actions_lowbalance
      :link-type: ref
      :text-align: center

      Receive an email alert as a reminder about your balance reaching a set threshold.

----

.. raw:: html

    <br>

.. _billing_actions_autotopup:

Auto Balance Top-Up
^^^^^^^^^^^^^^^^^^^

The **Automatically refill when threshold is reached** setting ensures that your balance is replenished automatically whenever it falls below the specified threshold.

    1. Go to **Billing > Payment Methods**.
    2. Enable **Automatically refill when threshold is reached** toggle.
    3. Set the following values:
         - **Threshold amount** – the balance trigger point.
         - **Refill amount** – how much to add when triggered.
    4. Click **Apply Changes**.

.. warning:: This feature requires at least one of your payment methods to have :ref:`auto-charge <billing_actions_autocharge>` enabled.

.. hint:: If your account has active calls, the final charge is only calculated after the call ends. The top-up trigger will only activate once the balance is updated. To avoid service disruption in such cases, it is strongly recommended to set a higher minimum threshold (e.g., 50 USD) to ensure sufficient buffer for active call costs.

.. figure:: https://doc.didww.com/_images/low-balance.png
   :figclass: align-center
   :alt: Configure auto top-up

   **Fig. 4.** Configure automatic balance top-up.

----

.. raw:: html

    <br>

.. _billing_actions_lowbalance:

Low Balance Notification
^^^^^^^^^^^^^^^^^^^^^^^^

Configure a Low Balance Notification to receive an email alert when your account balance drops below a specified threshold. This option is useful if you prefer to manage payments manually or want a warning before automatic top-ups occur.

    1. Navigate to **Payments > Payment Methods**.
    2. Toggle **Low Balance Notification** to enabled.
    3. Enter your desired threshold amount.
    4. Click **Apply Changes**.

.. important::
   - Combine this with :ref:`Auto Balance Top-Up <billing_actions_autotopup>` for layered protection (e.g., set a higher notification threshold than the auto-top-up trigger).
   - This feature only sends notifications—it does not trigger any payment action.

.. figure:: https://doc.didww.com/_images/low-balance-notification.png
   :figclass: align-center
   :alt: Low balance notification

   **Fig. 5.** Configure low balance notification.

----

.. raw:: html

    <br>

.. _billing_actions_retry:

Retry Failed Payment Method
------------------------------

If an auto-charge or manual payment fails, the associated payment method (e.g., credit card or PayPal) becomes temporarily unavailable for further automatic billing for **48 hours**. Common reasons include:

    - Insufficient funds
    - Card expired or invalid
    - Bank declines the transaction
    - Authentication failure (e.g., 3D Secure verification)

When this happens, a **Retry** button appears next to the failed transaction. Click **Retry** to manually attempt the payment and restore the payment method.

    .. figure:: https://doc.didww.com/_images/autocharge.png
       :figclass: align-center
       :alt: Retry a failed auto-charge.

       **Fig. 2.** Retry a failed auto-charge.

----

.. raw:: html

    <br>

Additional Information
----------------------

.. card:: **Credit Card Payments**
    :link: billing_payment_methods_credit_cards
    :link-type: ref

    Learn how to add and manage credit cards for payments.

.. card:: **PayPal Payments**
    :link: billing_payment_methods_paypal
    :link-type: ref

    Learn how to add and manage PayPal as a payment method.

.. card:: **Wire Transfer**
    :link: billing_payment_methods_wire_transfer
    :link-type: ref

    Find instructions for funding your account via bank transfer.


.. _user_panel_account_settings_index:

================
Account Settings
================

The **Account Settings** page is where you manage your personal information, security settings, user roles, multi-accounts, notifications, and more.

To access it, select the account switcher button in the top-right corner of the page, then choose **Account Settings** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig1_new.png
   :figclass: align-center
   :alt: Account settings
   :width: 80%

   **Fig. 1.** Account Settings interface.

----

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`person` **Register an Account with DIDWW**
      :link: creating-an-account
      :link-type: doc
      :text-align: left

      Sign up for a DIDWW account by completing the registration form, confirming your email, and setting a secure password.

   .. grid-item-card:: :octicon:`verified` **Account Setup**
      :link: account-setup
      :link-type: doc
      :text-align: left

      Verify your DIDWW account to get access to buy DIDs, capacity, phone.systems™ plans, and add payment methods.

   .. grid-item-card:: :octicon:`id-badge` **User Details**
      :link: user-details
      :link-type: doc
      :text-align: left

      Manage your profile information, update your email, change your password, and keep your account secure.

   .. grid-item-card:: :octicon:`gear` **Account Details**
      :link: account-details
      :link-type: doc
      :text-align: left

      Manage your account identity, contact information, address details, and delete your account if needed.

   .. grid-item-card:: :octicon:`lock` **Security**
      :link: two-factor-auth
      :link-type: doc
      :text-align: left

      Enable and manage Two-Factor Authentication (2FA) using an authenticator app, email, or web authentication to secure your account.

   .. grid-item-card:: :octicon:`people` **Users**
      :link: adding-new-roles
      :link-type: doc
      :text-align: left

      Invite team members, assign roles, and manage permissions with role-based access control.

   .. grid-item-card:: :octicon:`organization` **Accounts**
      :link: multi-account
      :link-type: doc
      :text-align: left

      Create and manage multi-accounts, switch between owned and managed accounts, and control access.

   .. grid-item-card:: :octicon:`bell` **Notifications**
      :link: notifications
      :link-type: doc
      :text-align: left

      Configure email alerts for key account events, manage role-based recipients, and add custom trusted addresses.

.. |acc_switcher| image:: /img/new_user_panel/account_settings/acc_switcher1.png
   :class: inline-img no-shadow
   :width: 100px


.. _user_panel_create_account:

==============================
Register an account with DIDWW
==============================

Register a DIDWW production account for live operations or a Sandbox account for testing. Choose your environment, complete the registration form, confirm your email address, and set a password.

Step 1: Choose your environment
----------------------------------

Choose whether to create a production or Sandbox account.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Production account

      Use a production account for live operations involving actual number inventory and billing.

      Open the `DIDWW production registration page <https://my.didww.com/#/users/sign_up>`_ to begin registration.

   .. tab-item:: Sandbox account

      Use a Sandbox account to test API requests, application logic, or workflow integration without affecting production data or incurring real charges. For more information about the Sandbox environment, see :ref:`API Environments <api-environments>`.

      Open the `DIDWW Sandbox registration page <https://my-sandbox.didww.com/#/users/sign_up>`_ to begin registration.

      .. important::

         Identity verification is unavailable in the Sandbox environment.
         After you complete :ref:`Step 4: Set your account password
         <user-panel-create-account-set-password>` and your Sandbox account is
         registered, contact `DIDWW Customer Support <mailto:support@didww.com>`_ to
         request the initial test balance. After the initial balance is added,
         use `Stripe test payment details
         <https://docs.stripe.com/testing>`_ instead of real payment-card
         information when testing payment methods or the :ref:`Add Funds
         <billing_manage_add_funds>` flow.

The remaining steps are the same for both environments.

Step 2: Complete the registration form
----------------------------------------

You can register either a Business or a Personal account.
The account type depends on the information you provide in the registration form.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Business account

      A Business account is intended for companies and organizations.

      1. Enter the following details:

         - **Company name**
         - **Contact name**
         - **Corporate business email address**
         - **Phone number**
         - **Country**

      2. Review the DIDWW `Terms & Agreements`_ and `Privacy Notice`_.
      3. Accept the **Terms & Agreements** and **Privacy Notice**.
      4. Complete the **reCAPTCHA**.
      5. Select **Register**.

      .. figure:: https://doc.didww.com/_images/business.png
         :figclass: align-center
         :alt: Business account registration form

         **Fig. 1.** Business account registration form.

   .. tab-item:: Personal account

      A Personal account is intended for individual use.

      1. Enter the following details:

         - **Contact name**
         - **Email address**
         - **Phone number**
         - **Country**

      .. important::

         To register a Personal account, leave the **Company name** field empty.
         If you enter a company name, the account may be treated as a Business account.

      2. Review the DIDWW `Terms & Agreements`_ and `Privacy Notice`_.
      3. Accept the **Terms & Agreements** and **Privacy Notice**.
      4. Complete the **reCAPTCHA**.
      5. Select **Register**.

      .. figure:: https://doc.didww.com/_images/personal.png
         :figclass: align-center
         :alt: Personal account registration form

         **Fig. 2.** Personal account registration form.

Step 3: Confirm your email address
--------------------------------------------

1. Check your email inbox for a confirmation message from DIDWW.
2. Open the email and select **Confirm my account**.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Confirm my account link in the DIDWW confirmation email
   :width: 40%

   **Fig. 3.** Confirm your email address.

.. warning::

   The account confirmation link expires after 7 days. When it expires, DIDWW
   permanently deletes all information related to your registration.

.. _user-panel-create-account-set-password:

Step 4: Set your account password
--------------------------------------

After you select **Confirm my account** in the confirmation email, the **Set password for your account** page opens.

1. Enter a strong password in both the **Password** and **Confirm password** fields.
2. Select **Submit**.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Password and Confirm password fields on the account setup page

   **Fig. 4.** Set your account password.

Your DIDWW account is now created.

If you experience any issues during registration, contact DIDWW Customer Support
through live chat on the DIDWW website or by email at
`support@didww.com <mailto:support@didww.com>`_.

----

Related resources
-----------------------

.. card:: **Phone numbers**
   :link: user_panel_phone_numbers
   :link-type: ref

   Learn what DID numbers are and how to purchase and manage them.

.. card:: **Voice**
   :link: user_panel_voice
   :link-type: ref

   Manage voice services, including Inbound and Outbound Trunks, Emergency Calling, and CNAM.

.. card:: **Cloud PBX**
   :link: ps3_getting_started
   :link-type: ref

   Configure and manage phone.systems™, including call flows, number assignments, and users.

.. _Terms & Agreements: https://www.didww.com/DIDWW-Terms-and-Agreements
.. _Privacy Notice: https://www.didww.com/privacy-notice


.. |br| raw:: html

   <br />

.. _user_panel_account_verification:

=============
Account Setup
=============

Account setup prepares your account for service usage by verifying identity information and configuring security settings.
Completing this process helps ensure that services can be purchased, activated, and managed without interruption.

The procedure starts automatically when an account initiates an action related to
payment or service activation, such as:

    -  Purchase a :ref:`DID number <user_panel_purchase>`.
    -  Purchase additional :ref:`Capacity <flexible_capacity>`.
    -  Subscribe to a :ref:`phone.systems™ plan <ps3_getting_started>`.
    -  Add a :ref:`credit card payment method <billing_payment_methods_credit_cards>`.

.. .. figure:: /img/new_user_panel/account_settings/account_verification/complete_account_setup.png
   :alt: Complete Account Setup Button
   :figclass: align-center

   **Fig. 1.** Complete Account Setup Button

Follow the steps below to complete the account setup process:

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`person` **1. Account Details**
      :link: user_panel_account_verification_1
      :link-type: ref
      :text-align: left

      Provide your personal or organization’s details, including contact information and address.

   .. grid-item-card:: :octicon:`verified` **2. Identity Verification**
      :link: user_panel_account_verification_2
      :link-type: ref
      :text-align: left

      Verify your identity through a secure service by submitting your ID and a selfie.

   .. grid-item-card:: :octicon:`lock` **3. Account Security**
      :link: user_panel_account_verification_3
      :link-type: ref
      :text-align: left

      Protect your DIDWW account by enabling Two-Factor Authentication (2FA).

----

.. raw:: html

   <br>

.. _user_panel_account_verification_1:

1. Account Details
==================

When the **Identity Verification** pop-up appears, click **Complete Account Setup** to be redirected to the **Account Setup** page.
The first step is to review or complete your **Account Details**.

This section may already be prefilled with your information.
Verify that all details are accurate, fill in any missing fields if needed, and click **Continue** to proceed.

.. figure:: https://doc.didww.com/_images/account-verification-details.png
   :alt: Account details form
   :figclass: align-center

   **Fig. 1.** Account details form in the User Panel.

After submitting your details, a confirmation window will appear prompting you to continue with identity verification.
Click **Continue** to start the verification process.

.. figure:: https://doc.didww.com/_images/account-verification-confirmation.png
   :alt: Identity verification confirmation prompt
   :figclass: align-center

   **Fig. 2.** Identity verification confirmation window.

----

.. raw:: html

   <br>

.. _user_panel_account_verification_2:

2. Identity Verification
========================

Verify your identity to confirm account ownership by submitting your documents.
You will be redirected to a secure external page to complete the verification process. Follow the on-screen instructions to verify your identity.

.. note::
   If the verification process is interrupted or canceled, you’ll be returned to **Step 2: Identity Verification**.
   Click **Try again** to restart the process from the beginning.

Step 1: Switch to a Mobile Device
---------------------------------

Identity verification can only be completed on a mobile device. Choose **Switch device**, then scan the QR code or click **Copy link** to open the verification page on your mobile device. Once opened, the message **“Process is moved to another device”** will appear on your computer screen.

.. grid:: 1 1 1 2
   :gutter: 4
   :padding: 0

   .. grid-item::

      .. figure:: https://doc.didww.com/_images/account-verification-qr.png
         :alt: Switch identity verification to a mobile device using a QR code
         :figclass: align-center

         **Fig. 3.** Switching verification to a mobile device.

   .. grid-item::

      .. figure:: https://doc.didww.com/_images/account-verification-qr-move-to-phone.png
         :alt: Identity verification process moved to a mobile device
         :figclass: align-center

         **Fig. 4.** Process moved to a mobile device. Keep this window open.

.. note::
   - After opening the verification process on your mobile device, a **Consent for Personal Data Processing** message will appear.
   - Review the information carefully and click **I Agree** to continue.
   - Selecting **Disagree** will cancel the verification process.

Step 2: Select Your Document
-------------------------------

Choose a document for verification: **Identity card**, **Passport**, or **Driver's license**.

.. figure:: https://doc.didww.com/_images/account-verification-document.png
   :alt: Document selection
   :figclass: align-center
   :width: 35%

   **Fig. 5.** Selecting the document type for verification.

Step 3: Capture the Front & Back of Your Document
-------------------------------------------------

Follow the on-screen prompts to capture clear images of your identification document.

.. admonition:: Requirements:
    :class: Important

    - The image is sharp and well-lit.
    - All text and details are clearly visible.
    - The entire document fits within the frame.

Capture the Front of Your Document
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use your device’s camera to take a clear photo of the front side of your document. Click **Capture photo** to begin the process.

.. figure:: https://doc.didww.com/_images/account-verification-id-front.png
   :alt: Capture front of ID
   :figclass: align-center
   :width: 35%

   **Fig. 6.** Front side capture of an identity document.

Capture the Back of Your Document
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use your device’s camera to take a clear photo of the back side of your document. Click **Capture photo** to begin the process.

.. figure:: https://doc.didww.com/_images/account-verification-id-back.png
   :alt: Capture back of ID
   :figclass: align-center
   :width: 35%

   **Fig. 7.** Back side capture of an identity document.

Step 4: Take a Selfie
---------------------------

Click **Start** and follow the on-screen instructions to take a selfie for identity verification.
Position your face within the frame and ensure the image is clear.

.. admonition:: Requirements:
    :class: Important

    - The face is well-lit and clearly visible.
    - A neutral expression is maintained.
    - The image is sharp and not blurry.

.. figure:: https://doc.didww.com/_images/account-verification-selfie.png
   :alt: Taking a selfie for identity verification.
   :figclass: align-center
   :width: 35%

   **Fig. 8.** Taking a selfie for identity verification.

Step 5: Verification Successful
-------------------------------

Once verification is complete, a **Success** screen will appear.
Click **Finish** to return to the DIDWW User Panel.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/account-verification-success.png
           :alt: Successful identity verification confirmation screen.
           :figclass: align-center

           **Fig. 9.** Verification success message.

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/account-verification-done.png
           :alt: Final identity verification completion screen.
           :figclass: align-center

           **Fig. 10.** Final completion confirmation.

----

.. raw:: html

   <br>

.. _user_panel_account_verification_3:

3. Account Security
===================

.. note::

   - The **Account Security** step appears only when Two-Factor Authentication (2FA) has not been configured.
   - Setting up Two-Factor Authentication (2FA) is strongly recommended for better protection and is **required** for all accounts with active orders.

Set up Two-Factor Authentication (2FA) methods to protect your DIDWW account.
Choose from multiple verification methods to add an extra layer of security when signing in.

.. tab-set::

   .. tab-item:: Authenticator App

      Use a mobile application, such as **Google Authenticator** or **Microsoft Authenticator**, to generate a verification code each time you sign in. For the full step-by-step guide and authenticator app download links, see :ref:`Security <user_panel_2fa>`.

      1. Enable the **Authenticator App** option.
      2. Scan the QR code using your authentication app.
      3. Enter the 6-digit code generated by the app and click **Submit** to complete setup.

      .. figure:: https://doc.didww.com/_images/account-security-overview-app.png
         :alt: Account Security overview
         :figclass: align-center

         **Fig. 11.** Setting up 2FA using an Authenticator App.

   .. tab-item:: Email Verification

      Receive a one-time verification code by email each time you log in.

      1. Enable the **Email Verification** option.
      2. Confirm your email address and click **Submit**.
      3. Enter the 6-digit code sent to your email to finalize setup.

      .. figure:: https://doc.didww.com/_images/account-security-overview-email.png
         :alt: Account Security overview
         :figclass: align-center

         **Fig. 12.** Setting up 2FA using Email Verification.

   .. tab-item:: Web Authentication

      Use a hardware-based or built-in authentication method, such as **Face ID**, **Touch ID**, or **Windows Hello**, for quick and secure login.

      1. Click **Add New** and give your device a name.
      2. Follow your browser’s instructions to register the device.
      3. Once registered, the device will appear in your authentication list.

      .. figure:: https://doc.didww.com/_images/account-security-overview-webauth.png
         :alt: Account Security overview
         :figclass: align-center

         **Fig. 13.** Setting up 2FA using Web Authentication.

.. raw:: html

    <style>
        .rst-content .section ul, .rst-content .toctree-wrapper ul, .rst-content section ul, .wy-plain-list-disc, article ul {
            margin-bottom: 0px;
            vertical-align: middle;
        }

    .sd-tab-content {
        box-shadow: none;
    }
    .sd-tab-set>label {
        border-color: var(--sd-color-tabs-underline);
        color: inherit;
    }

    /* Green check-circle */
    .sd-octicon-x-circle {
        color: #d73a49;
        fill: currentColor;
    }

    /* Red x-circle */
    .sd-octicon-check-circle {
        color: #28a745;
        fill: currentColor;
    }

    .hide-table {
        display: none;
    }

    </style>

.. raw:: html

   <style>
     em {
       font-size: 115%;
       font-weight: 700 !important;
       font-style: normal !important;
       font-family: Roobert-semibold !important;
     }
   </style>


.. _user_panel_account_user_details:

============
User Details
============

The **User Details** page allows you to manage your personal information. You can view and update your profile credentials to ensure your account remains accurate and secure.

.. note::

   If an individual has been invited to manage an account with a specific role, they can manage their own personal information on the User Details page.

----

.. raw:: html

   <br>

Change Your Contact Email
--------------------------

To change the **Contact Email**, follow these steps:

Step 1: Initiate the Change
'''''''''''''''''''''''''''

To update your contact email address click **Change Email**.

.. figure:: https://doc.didww.com/_images/fig2.1.png
   :figclass: align-center
   :alt: Change Email Button.

   **Fig. 1.** Change Email Button.

A notification will confirm that a verification link has been sent to your new email address.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Change Email Notification.

   **Fig. 2.** Change Email Notification.

Step 2: Verify the Email
''''''''''''''''''''''''

Open the verification email and click **Verify** email. You will be redirected to the **Change Email** page to complete the change.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Change Email Verification.
   :width: 40%

   **Fig. 3.** Change Email Verification.

.. note::

   The verification link is valid for 30 minutes. If it expires, you will need to request a new one.

Step 3: Change the Email
''''''''''''''''''''''''

To update your email address, follow these steps on the **Change Email** page:

    1. Enter your new email address and current password.
    2. Click **Submit**.

A confirmation message will be sent to your new email address. Follow the instructions in that message to confirm and complete the update.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Change Email.

   **Fig. 4.** Change Email.

----

.. raw:: html

   <br>

Change Your First and Last Name
--------------------------------

To update your first or last name:

    1. Edit the **First name** or **Last name** fields.
    2. Click **Update** to save your changes.

.. figure:: https://doc.didww.com/_images/fig6.png
   :figclass: align-center
   :alt: Update Name Information.

   **Fig. 5.** Update Name Information.

----

.. raw:: html

   <br>

Change Your Password
--------------------

To change your password, follow these steps:

Step 1: Open the Password Change Request
''''''''''''''''''''''''''''''''''''''''''

Click **Change Password** button.

.. figure:: https://doc.didww.com/_images/fig5.1.png
   :figclass: align-center
   :alt: Change Password Button.

   **Fig. 6.** Change Password Button.

Step 2: Enter and Confirm the New Password
''''''''''''''''''''''''''''''''''''''''''

    1. Enter your current password.
    2. Enter your new password, then re-enter it to confirm.
    3. Click **Confirm** to save your changes.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: Change Password.

   **Fig. 7.** Change Password.

----

.. raw:: html

   <br>

Additional Information
=======================

.. card:: **Security Settings**
    :link: user_panel_2fa
    :link-type: ref

    Learn how to enable two-factor authentication (2FA), manage active sessions, and strengthen account security.

.. card:: **Account Details**
    :link: user_panel_account_details
    :link-type: ref

    View and manage company-wide account settings, including identity and address information.

.. card:: **User Roles and Access Management**
    :link: user_panel_accepting_user_invite
    :link-type: ref

    Learn how to invite team members, assign roles, and manage user access to shared resources.

.. card:: **Notification Settings**
    :link: user_panel_notifications
    :link-type: ref

    Learn how to configure notification delivery. Define default recipients based on user roles, add custom email addresses, and manage how alerts are distributed for key account events.



.. _user_panel_account_details:

===============
Account Details
===============

The **Account Details** page allows you to manage your personal or organization’s identity, contact information, and address details.

----

.. raw:: html

   <br>

Update Your Account Identity & Address
--------------------------------------------

Use this section to update your personal or organization's identity and address details.

The identity section allows you to modify general company information, contact details, and physical address.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Update Account Identity and Address.
   :width: 80%

   **Fig. 1.** Update Account Identity and Address.

The address section allows you to ensure your personal or organization's location information is up to date.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Update Address Information.
   :width: 80%

   **Fig. 2.** Update Address Information.

After making your changes, select **Update** to save them.

----

.. raw:: html

   <br>

Delete Your Account
--------------------

.. important::

   Deleting your account is a **permanent action**. All active services and any remaining balance will be **permanently removed** along with the account.

To delete your DIDWW account, follow these steps:

Step 1: Initiate Account Deletion
''''''''''''''''''''''''''''''''''

Expand the **More Options** section and select **Delete Account**.

    .. figure:: https://doc.didww.com/_images/fig4.png
       :figclass: align-center
       :alt: Delete Account Button.

       **Fig. 3.** Delete Account Button.

Step 2: Confirm Account Deletion
''''''''''''''''''''''''''''''''''

In the confirmation popup, enter your reason for closing the account, then select **Confirm** to proceed.

    .. figure:: https://doc.didww.com/_images/fig4.1.png
       :figclass: align-center
       :alt: Delete Account Confirmation.

       **Fig. 4.** Delete Account Confirmation.

Step 3: Confirm Account Deletion via Email
'''''''''''''''''''''''''''''''''''''''''''''

You will receive an email with the subject **Account Deletion Confirmation**.

    .. figure:: https://doc.didww.com/_images/fig4.2.png
       :figclass: align-center
       :alt: Email Notification for Deletion.

       **Fig. 5.** Email Notification for Deletion.

Open the email and select the confirmation link to complete the account deletion process.

    .. figure:: https://doc.didww.com/_images/fig4.3.png
       :figclass: align-center
       :alt: Final Confirmation Email.
       :width: 40%

       **Fig. 6.** Final Confirmation Email.

----

.. raw:: html

   <br>

Additional Information
-----------------------

.. card:: **User Details**
    :link: user_panel_account_user_details
    :link-type: ref

    Learn how users can update their name, contact email, and password.

.. card:: **Security Settings**
    :link: user_panel_2fa
    :link-type: ref

    Learn how to enable two-factor authentication (2FA), manage active sessions, and strengthen account security.

.. card:: **Users**
    :link: user_panel_roles
    :link-type: ref

    Learn about user roles, how to invite team members, assign access levels, and manage users.

.. card:: **Accounts**
    :link: user_panel_accounts
    :link-type: ref

    Learn how to manage multi-accounts and access accounts you've been invited to, based on assigned roles.

.. card:: **Notification Settings**
    :link: user_panel_notifications
    :link-type: ref

    Learn how to configure notifications, set role-based recipients, and add custom email addresses for account alerts.



.. _user_panel_2fa:

========
Security
========

The **Security** section helps you protect your account with Two-Factor Authentication (2FA). You can enable one or more of the following methods:

.. attention::

    - Two-Factor Authentication (2FA) **is required** for all accounts that have created orders.
    - We recommend setting up **at least two authentication methods**, such as an authenticator app and email verification, to help ensure you can access your account if one method becomes unavailable.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item-card:: :octicon:`device-mobile` **Authenticator App**
      :link: user_panel_2fa_app
      :link-type: ref
      :text-align: center

      Use a mobile authenticator app to generate a verification code each time you sign in.

   .. grid-item-card:: :octicon:`mail` **Email Verification**
      :link: user_panel_2fa_email
      :link-type: ref
      :text-align: center

      Receive a unique verification code by email to complete your sign-in process.

   .. grid-item-card:: :octicon:`shield-lock` **Web Authentication**
      :link: user_panel_2fa_web
      :link-type: ref
      :text-align: center

      Use device-based authentication methods like biometrics or PIN for secure sign-in.

----

.. raw:: html

   <br>

.. _user_panel_2fa_app:

Authenticator App
-----------------

The **Authenticator App** Two-Factor Authentication (2FA) method uses time-based one-time passwords (TOTP) generated by a compatible app, such as Google Authenticator or Microsoft Authenticator.

To set it up, follow these steps:

Step 1: Download an authenticator app
''''''''''''''''''''''''''''''''''''''''''

Before you enable this method, install an authenticator app on your phone. Choose your platform below:

.. grid:: 1 1 1 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :iconify:`mdi:apple` **Download it for iOS**
      :link: https://apps.apple.com/lt/app/authenticator-app/id1538761576
      :link-type: url
      :text-align: left

      Open the App Store and install an authenticator app before continuing.

   .. grid-item-card:: :iconify:`mdi:android` **Download it for Android**
      :link: https://play.google.com/store/apps/details?id=com.smmservice.authenticator
      :link-type: url
      :text-align: left

      Open Google Play and install an authenticator app before continuing.

Step 2: Enable the Authenticator App
''''''''''''''''''''''''''''''''''''''''''

In the `User Panel Security tab <https://my.didww.com/#/security>`_, enable the **Authenticator App** toggle to activate this authentication method.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Enable Authenticator App.

   **Fig. 1.** Enable Authenticator App.

Step 3: Scan the QR Code and Enter the Code
''''''''''''''''''''''''''''''''''''''''''''

Scan the displayed QR code using your authentication app. Then enter the verification code generated by the app and click **Submit**.

.. figure:: https://doc.didww.com/_images/fig2.1.png
   :figclass: align-center
   :alt: Scan QR Code and Submit Code.

   **Fig. 2.** Scan the QR code and submit the generated code.

Step 4: Sign in Using the Authenticator App
'''''''''''''''''''''''''''''''''''''''''''''

Once **Authenticator App (2FA)** is successfully enabled, you will use your authentication app to generate a unique verification code each time you sign in. To complete the authentication process, open your app and enter the current code displayed for your account.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Login with Authenticator App Code.

   **Fig. 3.** Enter the app-generated verification code during login.

----

.. raw:: html

   <br>

.. _user_panel_2fa_email:

Email Verification
------------------

The **Email Verification** Two-Factor Authentication (2FA) method sends a one-time code to your email address each time you sign in.

To set it up, follow these steps:

Step 1: Enable Email Verification
'''''''''''''''''''''''''''''''''

In the `User Panel Security tab <https://my.didww.com/#/security>`_, toggle the **Email Verification** option to activate this authentication method, enter your email address, and select **Submit**.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Enable Email Verification.

   **Fig. 4.** Enter the email address for receiving verification codes.

Step 2: Enter the Verification Code
''''''''''''''''''''''''''''''''''''''''

A 6-digit verification code will be sent to the contact email address you provided on the **User Details** page.

.. figure:: https://doc.didww.com/_images/fig4.1.png
   :figclass: align-center
   :alt: Email Verification Code.
   :width: 40%

   **Fig. 5.** Email message containing the authentication code.

Enter the code into the verification field and select **Submit**.

.. figure:: https://doc.didww.com/_images/fig4.2.png
   :figclass: align-center
   :alt: Submit Email Verification Code.

   **Fig. 6.** Submit the verification code to complete setup.

Step 3: Sign in Using Email Verification
''''''''''''''''''''''''''''''''''''''''

Once **Email Verification** (2FA) is successfully enabled, you will receive a unique verification code via email each time you sign in. To complete the authentication process, enter the code sent to your registered email address.

.. figure:: https://doc.didww.com/_images/fig4.3.png
   :figclass: align-center
   :alt: Login with Email Verification.

   **Fig. 7.** Enter the email-based verification code during login.

----

.. raw:: html

   <br>

.. _user_panel_2fa_web:

Web Authentication
------------------

The **Web Authentication** Two-Factor Authentication (2FA) method allows secure sign-in using device-based credentials such as **Touch ID**, **Face ID**, or **Windows Hello**.

To set it up, follow these steps:

Step 1: Add New Web Authentication Method
''''''''''''''''''''''''''''''''''''''''''''

Click **Add New**, enter a friendly name for your device, and select **Submit** to begin registration process on your device.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: Add Web Authentication.

   **Fig. 8.** Web Authentication Two Factor Authentication Method.

Step 2: Authenticate with Device
''''''''''''''''''''''''''''''''

Follow the prompts from your browser to register a supported method such as biometrics, password, or PIN. Complete the registration using your selected method.

.. figure:: https://doc.didww.com/_images/fig5.2.png
   :figclass: align-center
   :alt: Confirm Registration.

   **Fig. 9.** Confirm credential creation with your system.

Complete the authentication with your selected device method.

.. figure:: https://doc.didww.com/_images/fig5.3.png
   :figclass: align-center
   :alt: Authenticate Identity.

   **Fig. 10.** Authenticate with biometric or password to complete registration.

Once registered, your device will appear in the list of active authentication methods, and a confirmation email will be sent.

.. figure:: https://doc.didww.com/_images/fig5.4.png
   :figclass: align-center
   :alt: Registered WebAuth Device.

   **Fig. 11.** Device successfully added for Web Authentication.

Step 3: Sign in Using Web Authentication
''''''''''''''''''''''''''''''''''''''''

Once **Web Authentication (2FA)** is successfully enabled, your registered device will prompt you to verify your identity each time you sign in. If you are using the same device and browser that were originally registered, you can authenticate using your selected method, such as biometrics (e.g., fingerprint or facial recognition) or a PIN.

.. note::

   Web Authentication works only on the device and browser where it was initially registered.
   If you're signing in from a different device or browser, we recommend using an alternative 2FA method to access your account.

.. figure:: https://doc.didww.com/_images/fig5.6.png
   :figclass: align-center
   :alt: Confirmation Email.

   **Fig. 12.** Web Authentication During Login.

----

.. raw:: html

   <br>

Additional Information
----------------------

.. card:: **User Details**
    :link: user_panel_account_user_details
    :link-type: ref

    Learn how users can update their name, contact email, and password.

.. card:: **Account Details**
    :link: user_panel_account_details
    :link-type: ref

    Learn how to manage company identity, contact information, and address.

.. card:: **Notifications**
    :link: user_panel_notifications
    :link-type: ref

    Learn how to configure notifications, set role-based recipients, and add custom email addresses for account alerts.

.. card:: **Users**
    :link: user_panel_roles
    :link-type: ref

    Learn about user roles, how to invite team members, assign access levels, and manage users.

.. card:: **Accounts**
    :link: user_panel_accounts
    :link-type: ref

    Learn how to manage multi-accounts and access accounts you've been invited to, based on assigned roles.


.. _user_panel_roles:

=====
Users
=====

The **Users** section lets account owners and administrators manage who can access the account and what they can do.
Through role-based permissions, you can define what each user is allowed to view or modify.

Each role includes a defined set of permissions and restrictions that help you control access to account features securely.
You can invite users, assign one or more roles, and adjust their access as needed.

----

.. raw:: html

   <br>

.. _user_panel_admin_role:

.. _user_roles:

User Role Permissions and Restrictions
----------------------------------------

..    .. csv-table:: Role Permissions Matrix
      :file: role_permissions_matrix.csv
      :header-rows: 1
      :widths: 35, 10, 10, 10, 10, 10, 10

..    .. list-table::
       :widths: 35 10 10 10 10 10 10
       :header-rows: 1
       :class: hide-table
..
       * - **Permission**
         - **Admin**
         - **Commercial**
         - **Billing**
         - **Technical**
         - **Porting**
         - **Compliance**
       * - Removing the account owner
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Buying and cancelling any services
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Configuring the account services
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Creating and managing all porting projects
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Creating and managing Identities & Addresses
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
       * - Creating and managing SMS Campaigns
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Creating and managing Emergency Calling services
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Creating all exports
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Creating Voice and SMS exports
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Creating, removing and editing trunks and all technical information
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Creating and managing the account’s roles and permissions
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Assigning regulatory bundles to end user registration required DIDs
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
       * - Managing the account’s funds (payment methods)
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Managing Configuration Profiles
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Managing CNAM OUT
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Managing number porting
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Managing general account settings
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Managing trunks for SMS Campaigns
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Configuration of existing numbers and capacity
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Configuration of capacity and capacity groups
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Accessing API information
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Accessing the Messaging Platform
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Accessing the Cloud Phone System
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Viewing existing SMS Campaigns
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Viewing existing Emergency Calling services
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Viewing existing CNAM OUT
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Viewing existing Phone Numbers
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Viewing Statistics & Reports
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Viewing billing history reports
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Viewing the purchasing activity on the account
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Viewing SMS and Call Logs
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Viewing pricelists
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
       * - Viewing account invoices
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Downloading invoices
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`
       * - Removing any existing technical configurations
         - :octicon:`check-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`check-circle`
         - :octicon:`x-circle`
         - :octicon:`x-circle`

.. tab-set::
    :class: my-tabs

    .. tab-item:: *Owner*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Full access to manage the account
           * - :octicon:`x-circle` **Prohibited Access**
             - - None. The Owner is not an assigned role and cannot be
                 removed from the account.

    .. tab-item:: *Admin*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Full access to manage the account.
           * - :octicon:`x-circle` **Prohibited Access**
             - - Removing the account owner.
               - Completing the account's Identity verification.
               - Creating an Outbound Trunk access request.
               - Join and manage the Referral Program.

    .. tab-item:: *Commercial*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Buying and cancelling any services.
               - Managing the account’s funds (payment methods).
               - Creating, removing and editing trunks and all technical information.
               - Configuring the account services.
               - Examining SMS and call logs.
               - Accessing the account’s cloud phone systems and softphone settings.
               - Editing the general account settings.
               - Creating and managing SMS Campaigns.
               - Creating and managing Emergency Calling services.
               - Managing CNAM OUT.
               - Viewing Statistics & Reports.
               - Creating Exports.
           * - :octicon:`x-circle` **Prohibited Access**
             - - Accessing API information.
               - Creating and managing the account’s roles and permissions.
               - Managing number porting.
               - Completing the account's Identity verification.
               - Creating an Outbound Trunk access request.
               - Join and manage the Referral Program.

    .. tab-item:: *Billing*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Managing the account’s funds (payment methods).
               - Downloading invoices.
               - Viewing reports.
               - Viewing the purchasing activity on the account.
               - Examining pricelists, SMS and call logs.
               - Viewing existing numbers.
               - Managing existing porting projects.
               - Viewing existing SMS Campaigns.
               - Viewing existing Emergency Calling services.
               - Viewing Statistics & Reports.
               - Creating Exports.
           * - :octicon:`x-circle` **Prohibited Access**
             - - Buying or removing any services including numbers, trunks, porting projects, etc.
               - Adding, removing or modifying trunk information or any technical configurations.
               - Accessing API information.
               - Managing CNAM OUT.
               - Completing the account's Identity verification.
               - Creating an Outbound Trunk access request.
               - Join and manage the Referral Program.

    .. tab-item:: *Technical*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Full management of the account’s technical configuration.
               - Configuration of number and capacity groups.
               - Creating, editing and removing trunks.
               - Viewing and exporting SMS and Call Logs.
               - Accessing API information.
               - Accessing the account’s cloud phone systems and softphone settings.
               - Managing the general account settings.
               - Managing trunks for SMS Campaigns.
               - Viewing existing Emergency Calling services.
               - Viewing existing CNAM OUT.
               - Viewing Statistics & Reports.
           * - :octicon:`x-circle` **Prohibited Access**
             - - Buying and cancelling any services.
               - Managing the account payments.
               - Examining the account invoices and price lists.
               - Managing number porting.
               - Viewing the purchasing activity on the account.
               - Completing the account's Identity verification.
               - Creating an Outbound Trunk access request.
               - Join and manage the Referral Program.

    .. tab-item:: *Porting*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Creating and managing all porting projects.
               - Setting of the account’s Configuration Profiles.
               - Creating and managing Identities & Addresses.
               - Configuration of existing numbers and capacity.
               - Managing general account settings.
               - Examining pricelists.
               - Viewing existing CNAM OUT.
               - Creating DID Number exports.
           * - :octicon:`x-circle` **Prohibited Access**
             - - Buying and cancelling any services.
               - Managing account payments.
               - Managing SMS Campaigns.
               - Managing Emergency Calling services.
               - Viewing Statistics & Reports.
               - Viewing account invoices.
               - Removing any existing technical configurations.
               - Accessing the account’s cloud phone systems and softphone settings.
               - Examining SMS and call logs.
               - Accessing API information.
               - Completing the account's Identity verification.
               - Creating an Outbound Trunk access request.
               - Join and manage the Referral Program.

    .. tab-item:: *Compliance*

        .. list-table::
           :widths: 20 70
           :header-rows: 1

           * -
             -
           * - :octicon:`check-circle` **Permitted Access**
             - - Creating and managing all Identities and Addresses.
               - Assigning regulatory bundles to end user registration required DIDs.
           * - :octicon:`x-circle` **Prohibited Access**
             - - Buying and canceling any services.
               - Managing account payments.
               - Managing SMS Campaigns.
               - Managing Emergency Calling services.
               - Managing CNAM OUT.
               - Viewing Statistics & Reports.
               - Creating Exports.
               - Viewing account invoices.
               - Removing any existing technical configuration.
               - Accessing account’s cloud phone systems and softphone settings.
               - Examining SMS and call logs.
               - Accessing API information.
               - Completing the account's Identity verification.
               - Creating an Outbound Trunk access request.
               - Join and manage the Referral Program.

----

.. raw:: html

   <br>

.. _user_panel_invite_users:

Invite Users
---------------

Follow these steps to invite someone responsible for managing your account.

Step 1: Initiate the Invite
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

To get started, complete the following steps:

    1. Open **Account Settings** by selecting your name or company name in the top-right corner
    2. Go to the **Users** section.
    3. Select **Invite User**.

.. figure:: https://doc.didww.com/_images/inv2fig0.png
   :figclass: align-center
   :alt: Invite User Button.

   **Fig. 1.** Invite User Button.

Step 2: Enter User Details and Send the Invitation
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

    1. Enter the user's full name and email address.
    2. Assign one or more roles. To learn what each role includes, see the :ref:`User Role Permissions and Restrictions <user_roles>` section.
    3. Select **Submit** to send the invitation email.

.. figure:: https://doc.didww.com/_images/inv2fig1.png
   :figclass: align-center
   :alt: Invite User Page.

   **Fig. 2.** Invite User Page.

----

.. raw:: html

   <br>

.. _user_panel_accepting_user_invite:

Accepting User Invitation
---------------------------------

To accept an invitation, the user must either **sign in** with an existing account (as an account owner) or **register** a new one directly from the invitation (as a role-based user).

.. note::

   There are two ways to accept a user invitation, and each has different implications:

   1. **Sign in with an existing account (as an account owner):**
      If you already have a DIDWW account and accept the invitation while signed in, you will gain access to manage the invited account from within your own account. You can switch between your personal account and the managed account using the account switcher. If your access is later removed, your personal account remains active.

   2. **Register directly from the invitation (as a role-based user):**
      If you follow the invitation link and register a new user account, the new user is created specifically to manage the invited account. This user does not own any account and exists only to manage the assigned account. If access is removed, the user account is deleted as well.

   Choose the option that best fits your needs:
       - If you want to have your own standalone account (e.g., to own services or accept future invitations), sign in or register separately, then accept the invitation.
       - If you only need access to manage someone else’s account, and don’t need your own separate account, register directly from the invitation link.

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Accepting as a New Role-Based User**
      :link: accepting_an_invitation_as_a_new_role_based_user
      :link-type: ref
      :text-align: center

      Learn how to accept an invitation by registering directly from the invitation email.

   .. grid-item-card:: **Accepting as an Existing Account Owner**
      :link: user_panel_accepting_user_invite_existing
      :link-type: ref
      :text-align: center

      Learn how to accept a user invitation by signing in with your existing account.

----

.. raw:: html

   <br>

.. _accepting_an_invitation_as_a_new_role_based_user:

Accepting Invitation as a New Role-Based User
------------------------------------------------

This process creates a user account specifically for managing the invited account. The new user does not own any services and exists only for assigned access. If your access is later removed, the user account will be deleted as well.

Follow the steps below to complete the registration:

Step 1: Accept the Invitation
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Open the invitation email and select **Accept the invitation** to begin the registration process.

.. figure:: https://doc.didww.com/_images/inv2fig2.png
   :figclass: align-center
   :alt: Invitation email for new users.
   :width: 40%

   **Fig. 3.** Invitation email for new users.

Step 2: Register a New Role-Based User
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

    1. Fill out the registration form with your personal details.
    2. Review the `Terms & Agreements`_ and `Privacy Notice`_. If you agree, accept them and complete the **reCAPTCHA**.
    3. Select **Register** to continue.

.. figure:: https://doc.didww.com/_images/inv1fig1.png
   :figclass: align-center
   :alt: Register account.

   **Fig. 4.** Register a new DIDWW account.

Step 3: Confirm Your Email
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Check your email inbox for a confirmation email. Select **Confirm my account** to verify your email address and activate the user.

.. figure:: https://doc.didww.com/_images/inv1fig3.png
   :figclass: align-center
   :alt: Confirm your DIDWW registration via email.
   :width: 40%

   **Fig. 5.** Confirm your DIDWW registration via email.

Step 4: Set a Password
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

    1. Enter your password and confirm it.
    2. Select **Submit** to complete your registration.

.. figure:: https://doc.didww.com/_images/inv1fig4.png
   :figclass: align-center
   :alt: Set a Password for Your Account.

   **Fig. 6.** Set a Password for Your Account.

Step 5: View the Managed Account
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

After completing registration and signing in, the invited managed account will appear in the **Account Settings > Accounts** section with the assigned role(s).

For more details, see the :ref:`Accounts <user_panel_accounts>` page.

.. figure:: https://doc.didww.com/_images/inv1fig5.png
   :figclass: align-center
   :alt: Account successfully added for existing user.

   **Fig. 7.** Account successfully added for existing user.

----

.. raw:: html

   <br>

.. _user_panel_accepting_user_invite_existing:

Accepting Invitation as an Existing Account Owner
-------------------------------------------------------

This option allows you to access and manage the invited account from your own personal account using the account switcher. Your personal account remains active even if access to the invited account is later removed.

Follow the steps below to complete the process:

Step 1: Accept the Invitation
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Open the invitation email and select **Accept the invitation** to begin the process.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: Invitation email for existing users.
   :width: 40%

   **Fig. 8.** Invitation email for existing users.

Step 2: Sign In to Your Existing Account
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

By default, when you select **Accept the invitation** in the email, you will be redirected to the registration page with the **Register** tab open. To proceed, you can either select **Sign in** to log in to your existing DIDWW account or choose **Register** to create a new one.

.. note::

   If you choose to register a new account separately, follow the guide at :ref:`How to Register an Account with DIDWW <user_panel_create_account>` first, and then accept the invitation.

.. figure:: https://doc.didww.com/_images/step2_sign_in_accept_the_invitation.png
   :figclass: align-center
   :alt: Log in.
   :width: 80%

   **Fig. 9.** Sign in to your existing account.

Step 3: Confirm the Invitation
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

After signing in to your existing account, you’ll be redirected to the **Account Settings > Accounts** section, where a banner will prompt you to confirm the invitation.

    - If the account shown is the one you want to use to accept the invitation, select **Accept**.
    - If it’s not the correct account, sign out and log in to the account you want to use.

.. figure:: https://doc.didww.com/_images/inv2fig4.png
   :figclass: align-center
   :alt: Banner with invitation details and role information.
   :width: 80%

   **Fig. 10.** Invitation banner with role information.

Step 4: Sign In to the Managed Account
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

After accepting the invitation, the managed account will appear in the **Account Settings > Accounts** section with the assigned role(s).

To access the account, select **Sign in** or use the account switcher in the top-right corner and choose the name of the managed account.

For more information, see the :ref:`Accounts <user_panel_accounts>` page.

.. figure:: https://doc.didww.com/_images/inv2fig6.png
   :figclass: align-center
   :alt: Invitation accepted and account listed.
   :width: 80%

   **Fig. 11.** Account successfully added for existing user.

----

.. raw:: html

   <br>

Edit Users and Roles
----------------------

You can update a user's assigned roles and access permissions at any time.

Step 1: Open the Edit Action Menu
'''''''''''''''''''''''''''''''''''''

    1. In the **Users** section under **Account Settings**, locate the user whose roles you want to update.
    2. Select the |actions| button and choose **Edit**.

    .. figure:: https://doc.didww.com/_images/editfig1.png
       :figclass: align-center
       :alt: Actions Button.

       **Fig. 12.** Actions Button.

Step 2: Change Assigned Roles
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

    1. Enable or disable roles as needed to update the user's permissions.
    2. Select **Submit** to save your changes.

    .. figure:: https://doc.didww.com/_images/editfig2.png
       :figclass: align-center
       :alt: Edit the User.

       **Fig. 13.** Edit User.

----

.. raw:: html

   <br>

Delete Users
-------------

You can remove a user from your account if access is no longer needed.

.. warning::

   If the user registered directly from the invitation as a role-based user, their account was created solely to manage the invited account. This type of user does not have a standalone account. If their access is removed, the user account will also be deleted, and they will no longer be able to sign in.

Step 1: Open the Delete Action Menu
'''''''''''''''''''''''''''''''''''''''''

    1. In the **Users** section under **Account Settings**, locate the user you want to remove.
    2. Select the |actions| button next to the user.
    3. Choose **Delete** from the menu.

    .. figure:: https://doc.didww.com/_images/delfig1.png
       :figclass: align-center
       :alt: Actions Button.

       **Fig. 14.** Actions Button.

Step 2: Confirm and Delete the User
''''''''''''''''''''''''''''''''''''''''''''

On the confirmation screen, select **Delete** to remove the user from the account.

.. warning::

   The user will be removed **immediately** and lose access to the account.

.. figure:: https://doc.didww.com/_images/delfig2.png
   :figclass: align-center
   :alt: Delete the User.

   **Fig. 15.** Delete User.

----

.. raw:: html

   <br>

Additional Information
-----------------------

.. card:: **User Details**
    :link: user_panel_account_user_details
    :link-type: ref

    Learn how users can update their name, contact email, and password.

.. card:: **Account Details**
    :link: user_panel_account_details
    :link-type: ref

    Learn how to manage company identity, contact information, and address.

.. card:: **Security**
    :link: user_panel_2fa
    :link-type: ref

    Learn how to enable Two-Factor Authentication (2FA) for user accounts.

.. card:: **Accounts**
    :link: user_panel_accounts
    :link-type: ref

    Learn how to manage multi-accounts and access accounts you've been invited to, based on assigned roles.

.. card:: **Notifications**
    :link: user_panel_notifications
    :link-type: ref

    Learn how to configure notifications, set role-based recipients, and add custom email addresses for account alerts.

.. |actions| image:: /img/new_user_panel/account_settings/roles/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. _Terms & Agreements: https://www.didww.com/DIDWW-Terms-and-Agreements
.. _Privacy Notice: https://www.didww.com/privacy-notice

.. raw:: html

    <style>
        .rst-content .section ul, .rst-content .toctree-wrapper ul, .rst-content section ul, .wy-plain-list-disc, article ul {
            margin-bottom: 0px;
            vertical-align: middle;
        }
    </style>

.. _user_panel_accounts:

========
Accounts
========

The **Accounts** section provides access to all accounts you own, as well as accounts you've been invited and accepted to manage as a role-based user.

    - You can view, create, and access additional accounts, referred to as sub-accounts or multi-accounts.
    - You can also view, access, or leave any managed accounts you’ve been invited to.

.. figure:: https://doc.didww.com/_images/fig1.png
    :figclass: align-center
    :alt: Accounts tab.

    **Fig. 1.** Accounts tab.

----

.. raw:: html

   <br>

Create Multi-Accounts
----------------------

You can create additional accounts from the **Accounts** section. These are known as sub-accounts or multi-accounts. Each functions independently from your main account and includes its own services, orders, and invoices. While these accounts provide the same features as your main account, they do not require a separate login. Access is managed through your main (parent) account using your primary credentials.

To create a new sub-account, follow these steps:

Step 1: Select Create New
''''''''''''''''''''''''''

In the **Accounts** tab, select the **Create New** button in the top-right corner.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Create New Account Button.

   **Fig. 2.** Create New Account

Step 2: Enter Account Details
''''''''''''''''''''''''''''''''

Fill in the required fields. If you are creating a business account, provide the business name, contact email, address, and other relevant information.

After entering all required information, click **Create**.

.. note::

   To create a personal account instead of a business account, turn off the **Business account** toggle.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Account creation form.

   **Fig. 3.** Account creation form

Step 3: View and Access the Multi-Accounts
'''''''''''''''''''''''''''''''''''''''''''''

Once submitted, the new account will appear in the **Accounts** section as an **Owned** account type labeled **Owned**. You can access it from this page or by using the account switcher in the top-right corner.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: Completed form.

   **Fig. 4.** Multi-Accounts List.

----

.. raw:: html

   <br>

Switch Between Accounts
-----------------------

If you manage multiple accounts, you can easily switch between them using the account switcher located in the top-right corner of the interface.

    - The switcher displays a list of recently accessed accounts for quick access.
    - If the account you want is not visible in the recent list, select **All accounts** from the dropdown. Then, locate the account by type, such as **Owned** or **Managed**, and select **Sign In**.

.. note::

   Use the account switcher to navigate between your main account, owned multi-accounts, and accounts you've been invited to manage. Switching does not require logging out. All features remain available based on your assigned role in each account.

To switch accounts:

    1. Select the account switcher button in the top-right corner.
    2. In the dropdown list, find the account you want to access and select the title name to sign in.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Account selection dropdown for switching between accounts.

   **Fig. 5.** Account selection dropdown for switching between accounts.

----

.. raw:: html

   <br>

Edit Account Title
------------------------

You can modify the title of your accounts as needed by following these steps:

Step 1: Open the Edit Menu
''''''''''''''''''''''''''

    1. In the **Accounts** tab under **Account Settings**, locate the account you want to edit.
    2. Select the |actions| button and choose **Edit**.

.. figure:: https://doc.didww.com/_images/fig6.png
    :figclass: align-center
    :alt: Actions Button.

    **Fig. 6.** Actions Button.

Step 2: Edit the Account Name
'''''''''''''''''''''''''''''

    1. In the edit menu, change the account title as needed.
    2. Select **Submit** to save your changes.

.. figure:: https://doc.didww.com/_images/fig7.png
    :figclass: align-center
    :alt: Edit Account Name.

    **Fig. 7.** Edit Account.

----

.. raw:: html

   <br>

Leave Managed Account
-----------------------

If you’ve accepted an invitation to manage someone else’s account, you can leave that account at any time. This option is useful when access is no longer needed or your assigned role is no longer required.

.. warning::

   If you registered directly from the invitation as a role-based user, your account was created solely to manage the invited account and does not exist independently. If you leave the managed account, your access is removed immediately, and your user account will also be deleted. You will no longer be able to sign in unless you have a separate owner account.

.. important::

   Leaving a managed account will **permanently** revoke your access. To regain access, you must be re-invited by the account owner.

To leave a managed account, follow the steps below.

Step 1: Open Leave Managed Account
'''''''''''''''''''''''''''''''''''''''''''''

    1. In the **Accounts** tab under **Account Settings**, locate the managed account you want to leave.
    2. Select the |actions| button next to the account and choose **Leave**.

.. figure:: https://doc.didww.com/_images/fig9.png
   :figclass: align-center
   :alt: Leave action.

   **Fig. 8.** Selecting the leave option.

Step 2: Confirm Leave Managed Account
'''''''''''''''''''''''''''''''''''''''

In the confirmation window, select **Confirm** to leave the account permanently.

.. figure:: https://doc.didww.com/_images/fig10.png
   :figclass: align-center
   :alt: Confirm leave.

   **Fig. 9.** Confirmation dialog for leaving a managed account.

----

.. raw:: html

   <br>

Additional Information
-----------------------

.. card:: **User Details**
    :link: user_panel_account_user_details
    :link-type: ref

    Learn how users can update their name, contact email, and password.

.. card:: **Account Details**
    :link: user_panel_account_details
    :link-type: ref

    Learn how to manage company identity, contact information, and address.

.. card:: **Security**
    :link: user_panel_2fa
    :link-type: ref

    Learn how to enable Two-Factor Authentication (2FA) for user accounts.

.. card:: **Notifications**
    :link: user_panel_notifications
    :link-type: ref

    Learn how to configure notifications, set role-based recipients, and add custom email addresses for account alerts.

.. card:: **Users**
    :link: user_panel_roles
    :link-type: ref

    Learn about user roles, how to invite team members, assign access levels, and manage users.

.. |actions| image:: /img/new_user_panel/account_settings/roles/three_dots_action_button.png
   :class: inline-img no-shadow test-class
   :width: 30px
   :height: 30px

.. |acc_switcher| image:: /img/new_user_panel/account_settings/accounts/account_switcher.png
   :class: inline-img no-shadow
   :width: 100px

.. |br| raw:: html

   <br />

.. _user_panel_notifications:

=============
Notifications
=============

The **Notifications** section allows account owners and :ref:`administrators <user_panel_admin_role>` to manage how automatic account alerts are delivered. Each notification is tied to specific :ref:`user roles <user_panel_roles>`, and notification emails are sent by default to users assigned to those roles.

.. note::

   You can also add additional recipients who are not associated with specific roles.
   Keep in mind that notifications may contain sensitive account information.
   Only add trusted email addresses and verify them carefully.

----

.. raw:: html

   <br>

Notification Descriptions and Recipients
----------------------------------------

.. list-table::
   :widths: 15 25 15
   :header-rows: 1

   * - **Notification**
     - **Description**
     - **Default Recipients (User Roles)**
   * - API Key Changes
     - Notifies a user about a new/changed API Key.
     - Admin, Technical
   * - Chargeback Notifications
     - Notifies a user about a cancelled or settled chargeback.
     - Admin
   * - CNAM Notifications
     - Notifies a user about any CNAM-related actions.
     - Admin, Commercial
   * - Declined or Missing Payment Method
     - Notifies a user about a cancelled, declined, |br| or missing payment method.
     - Admin, Billing, Commercial
   * - Emergency Calling
     - Notifies a user about any emergency calling-related actions.
     - Admin, Commercial
   * - End User ID/Address Verifications
     - Notifies a user about missing, approved, |br| or rejected End User ID/Address verification.
     - Admin, Commercial, Compliance
   * - Invoice Notifications
     - Notifies a user about new or void invoices |br| and any changes to invoicing terms.
     - Admin, Billing
   * - Low Balance Notifications
     - Notifies a user about a reached account balance threshold or |br| insufficient funds to complete pending orders.
     - Admin, Billing, Commercial
   * - New and Pending Orders
     - Notifies a user about new and pending orders.
     - Admin, Billing, Commercial
   * - Payment Receipts, |br| Blocked Service Notifications |br| and Cancellations
     - Notifies a user about completed orders, |br| balance changes, and cancelled payments.
     - Admin, Billing, Commercial
   * - Porting Notifications
     - Notifies a user about any porting-related actions.
     - Admin, Porting
   * - Rate Changes
     - Notifies a user about upcoming rate changes.
     - Admin, Commercial
   * - Refund Notifications
     - Notifies a user about refunds.
     - Admin, Billing
   * - SMS Campaign
     - Notifies a user about any SMS campaign-related actions.
     - Admin, Commercial
   * - SMS Rate Changes
     - Notifies a user about upcoming sms rate changes.
     - Admin, Commercial
   * - User Deleted
     - Notifies a user about a terminated user access.
     - Admin
   * - VAT Validation Notifications
     - Notifies a user about an invalid VAT ID.
     - Admin, Billing
   * - Voice OUT Balance Limit Reached
     - Notifies a user about a reached 24-hour balance limit |br| for outbound calls.
     - Admin, Commercial, Technical
   * - Voice Rate Changes
     - Notifies a user about upcoming voice rate changes.
     - Admin, Commercial
   * - Wire Transfer Details
     - Notifies a user about events related to wire transfers.
     - Admin, Billing, Commercial

----

.. raw:: html

   <br>

Edit Notification
-----------------

You can control who receives email alerts for each notification type. Enable or disable default role-based recipients, or add additional trusted recipients as needed.

.. note::

   If you add additional recipients outside of assigned roles, be sure to include only trusted email addresses, as notifications may contain sensitive information.

To edit a notification, follow these steps:

Step 1: Open Edit Notification Page
''''''''''''''''''''''''''''''''''''

    1. In the **Notifications** tab under **Account Settings**, locate the notification you want to edit.
    2. Click the |actions| button and select **Edit**.

    .. figure:: https://doc.didww.com/_images/fig2.png
      :figclass: align-center
      :alt: Actions Button.

      **Fig. 1.** Actions Button.

Step 2: Update Notification
''''''''''''''''''''''''''''''

In the **Edit Notification** page, you can modify the following settings:

    1. **Recipients** — Manage role-based recipients by enabling or disabling specific user roles using the checkboxes.
    2. **Additional Recipients** — Enter up to 10 email addresses that are not tied to roles.

    .. note::

       You can add up to 10 email addresses to each notification group.

    .. figure:: https://doc.didww.com/_images/fig3.png
      :figclass: align-center
      :alt: Edit Notification Screen.

      **Fig. 2.** Edit Notification Page.

Step 3: Submit and Apply Changes
'''''''''''''''''''''''''''''''''

Click **Submit** to apply your changes.

The updated notification settings will appear in the notification list.

    .. figure:: https://doc.didww.com/_images/fig4.png
      :figclass: align-center
      :alt: Changes Reflected in Notification Tab.

      **Fig. 3.** Changes in Notification Tab.

----

.. raw:: html

   <br>

Additional Information
-----------------------

.. card:: **User Details**
    :link: user_panel_account_user_details
    :link-type: ref

    Learn how users can update their name, contact email, and password.

.. card:: **Account Details**
    :link: user_panel_account_details
    :link-type: ref

    Learn how to manage company identity, contact information, and address.

.. card:: **Security**
    :link: user_panel_2fa
    :link-type: ref

    Learn how to enable Two-Factor Authentication (2FA) for user accounts.

.. card:: **Users**
    :link: user_panel_roles
    :link-type: ref

    Learn about user roles, how to invite team members, assign access levels, and manage users.

.. card:: **Accounts**
    :link: user_panel_accounts
    :link-type: ref

    Learn how to manage multi-accounts and access accounts you've been invited to, based on assigned roles.

.. |actions| image:: /img/new_user_panel/account_settings/roles/three_dots_action_button.png
   :class: inline-img no-shadow test-class
   :width: 30px
   :height: 30px

.. _user_panel_referral_program:

================
Referral program
================

The DIDWW Referral Program lets eligible DIDWW customers earn commission by inviting new business customers to DIDWW. After you join, you receive a unique referral link to share with your network. When a referred business customer qualifies and generates eligible invoice activity, you can earn referral commission.

Start with **How the referral program works**, then use **Join the referral program** to activate it and get your referral link.

Get started
===========

Learn how the referral program works and activate it for your account.

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **How referral program works**
      :link: how-referral-program-works
      :link-type: doc
      :text-align: left

      Learn how referrals are tracked and how commissions, earnings, and withdrawals work.

   .. grid-item-card:: **Join referral program**
      :link: how-to-guides/join-referral-program
      :link-type: doc
      :text-align: left

      Activate the referral program, get your referral link, and verify your enrollment.

Manage the referral program
===========================

Review your earnings, request withdrawals, and look up referral program statuses and fields.

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Withdraw referral commissions**
      :link: how-to-guides/withdraw-referral-earnings
      :link-type: doc
      :text-align: left

      Review available earnings, request a bank transfer, and track the withdrawal status.

   .. grid-item-card:: **Referral program reference**
      :link: referral-program-reference
      :link-type: doc
      :text-align: left

      Review program terms, account and commission statuses, withdrawal statuses, balances, and User Panel fields.


.. _user_panel_referral_program_how_it_works:

==============================
How the referral program works
==============================

The Referral Program works by connecting your DIDWW account to new business customers who register through your referral link. When a referred customer qualifies and generates invoice activity, DIDWW creates commission records that can later become available for withdrawal.

The flow starts when the account owner joins the program and shares the referral link. The referred customer then registers and verifies their account, eligible invoices create commissions, and approved earnings can be withdrawn when the withdrawal requirements are met.

.. mermaid::

   ---
   config:
     layout: dagre
   ---
   flowchart LR
       classDef decision stroke:#fb923c,fill:#fef3c7,color:#111827,stroke-width:2px
       classDef action stroke:#22c55e,fill:#dcfce7,color:#111827,stroke-width:2px
       classDef outcome stroke:#ef4444,fill:#fee2e2,color:#111827,stroke-width:2px
       classDef input stroke:#38bdf8,fill:#e0f2fe,color:#111827,stroke-width:2px

       subgraph S1[Join the program]
           direction TB
           A[Join Referral Program]:::input
           B[Share referral link]:::action

           A --> B
       end

       subgraph S2[Invite customers]
           direction TB
           C[Referred customer registers a business account and verifies their identity]:::input
           D[Referral created]:::action

           C --> D
       end

       subgraph S3[Earn commissions]
           direction TB
           E[Referred customer generates invoices]:::input
           F[Referral status changes from pending to active]:::action
           I[Commission earned]:::outcome

           E --> F
           F --> I
       end

       subgraph S4[Withdraw commissions]
           direction TB
           G{"Minimum withdrawal threshold reached?"}:::decision
           H[Withdraw commissions]:::action
           J[Withdrawal not yet available]:::outcome

           G -->|YES| H
           G -->|NO| J
       end

       B --> C
       D -->|Referral remains active for 12 months| E
       I -->|Commission remains pending for 90 days| G

       style S1 fill:#ffffff,stroke:#d1d5db,color:#111827,stroke-width:1px
       style S2 fill:#ffffff,stroke:#d1d5db,color:#111827,stroke-width:1px
       style S3 fill:#ffffff,stroke:#d1d5db,color:#111827,stroke-width:1px
       style S4 fill:#ffffff,stroke:#d1d5db,color:#111827,stroke-width:1px

Referral participants
=====================

The Referral Program involves two customer roles:

- **Referrer** - The DIDWW customer account that joins the Referral Program and receives a referral link.
- **Referred customer** - The customer account that registers through the referrer's link and qualifies as a referral.

Only the account owner can join the Referral Program or submit withdrawal requests. A business account is required to join. If an account is personal or not yet verified, the join flow can ask the account owner to complete the required account updates before enrollment is completed.

Referred customers must register as business accounts to qualify as referrals. Personal accounts can register through a referral link, but they do not appear in the **My referrals** table or generate commissions. Self-referrals do not qualify.

Referral link
=============

After enrollment, DIDWW generates a unique referral link for the referrer. The link contains a referral code that identifies which account shared the link.

When a new customer opens the registration page through a referral link, DIDWW captures the referral code during registration. If the new customer completes registration as a qualifying business account, DIDWW creates a referral relationship between the referrer and the referred customer.

The referral link is the tracking mechanism. The referred customer still completes the normal DIDWW registration and verification process.

Referral lifecycle
==================

A referral is the relationship between a referrer and a referred customer. The lifecycle starts when a qualifying business account registers through the referral link.

Referrals can move through different account status values as the referred customer's activity changes. For example, a referral can be pending before qualifying invoice activity starts, active while it can generate commissions, expired after the referral validity period, closed if the referred account is closed, or terminated if the referral relationship is ended early.

For exact account status values and table fields, see :ref:`referral_program_account_status_values`.

Program terms
=============

Referral Program terms shown in the User Panel are authoritative for your account. The default terms are:

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Term
     - Description
   * - Commission rate
     - Percentage applied to qualifying invoice amounts before VAT. The default commission rate is 10%.
   * - Referral validity
     - Period during which a referred customer can generate commissions for the referrer. The default referral validity period is 12 months from the referred customer's registration date.
   * - Commissions pending period
     - Period before a commission becomes available for withdrawal. The standard pending period is 90 days.
   * - Minimum withdrawal amount
     - Minimum available earnings required before a withdrawal request can be submitted. The default minimum withdrawal amount is 500 USD.
   * - Payout method
     - Referral commissions are paid by bank transfer.

Commissions
===========

Referral commissions are created from qualifying invoices generated by referred customers. The commission is calculated from the invoice amount before VAT, using the commission rate assigned to the referrer.

A commission is created when a referred customer generates a qualifying invoice, and it becomes eligible for withdrawal once it completes the pending period. If the related invoice is corrected, refunded, voided, or recalculated before that happens, the commission is adjusted accordingly rather than counted as final.

Referral commission balances are shown as pending earnings and available earnings in the User Panel. Pending earnings represent commissions that are still within the pending period. Available earnings represent approved commissions that can be withdrawn when the available balance reaches the minimum withdrawal amount shown in the User Panel.

These balance views are separate from commission status values. Commission statuses describe the state of each commission entry in the commission ledger, including whether it is still pending, approved, canceled, or already included in a withdrawal. For exact status descriptions, see :ref:`referral_program_commission_status_values`.

The **Referrals** tab shows referral-oriented balances, including pending earnings and available earnings. The **Commissions** tab shows the commission ledger, including pending totals and total approved commission earned since joining the Referral Program. For exact field definitions, see :ref:`referral_program_reference_referrals_tab` and :ref:`referral_program_reference_commissions_tab`.

Withdrawals
===========

Withdrawals are payout requests for available approved referral commissions.

When a withdrawal request is submitted, it is created for the full available approved balance. The amount cannot be edited in the withdrawal form.

While a withdrawal is being processed, the included commissions are reserved and excluded from available earnings. If the request does not complete successfully, those commissions are returned to available earnings and can be included in a future withdrawal.

For the withdrawal procedure, see :doc:`how-to-guides/withdraw-referral-earnings`. For withdrawal fields and status values, see :ref:`referral_program_reference_withdrawals_tab`.

Related resources
=================

- :doc:`Join the Referral Program <how-to-guides/join-referral-program>` - Join the program and get your referral link.
- :doc:`Withdraw referral commissions <how-to-guides/withdraw-referral-earnings>` - Request a bank transfer payout for approved commissions.
- :doc:`Referral Program reference <referral-program-reference>` - Review User Panel fields, balances, filters, and status values.


.. _user_panel_join_referral_program:

=========================
Join the referral program
=========================

Join the DIDWW Referral Program to receive a unique referral link that you can share with potential business customers to earn commission.

For background on commission rate, referral validity, referral lifecycle, and other concepts, see :doc:`../how-referral-program-works` and :doc:`../referral-program-reference`.

Before you begin
================

- An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- You must sign in as the account owner. Users with other :ref:`roles <user_panel_roles>` cannot join the Referral Program.

.. - A business account is required. If you currently have a personal account, you can upgrade it during the join process.
.. - :ref:`Identity verification <user_panel_account_verification>` is required. If your account is not yet verified, you can complete the verification process during enrollment.

Step 1: Open the referral program page
======================================

1. In the DIDWW User Panel, open the account dropdown menu.
2. Click **Referral program**.

.. figure:: https://doc.didww.com/_images/fig1.png
   :alt: Account menu with Referral program item
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Referral Program from the account menu

Step 2: Join the referral program
=================================

1. On the Referral Program page, review the commission rate and program details.
2. Click **Join Program**.

.. note::
   - You will be asked to complete :ref:`identity verification <user_panel_account_verification>` if your account is not yet verified.
   - You will be asked to upgrade your account to a business account if your account is currently personal.

.. figure:: https://doc.didww.com/_images/fig2.png
   :alt: Referral Program page before enrollment with Join Program button
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Referral Program page before enrollment

Step 3: Accept the terms & conditions
=====================================

1. In the **Partner Referral Programme — Key Commercial Terms** modal, review the program terms and conditions. `See Partner Referral Programme Agreement <https://www.didww.com/Partner-Referral-Programme-Agreement>`_.
2. If you agree, select the confirmation checkbox and click **Agree & Continue**.

.. figure:: https://doc.didww.com/_images/fig3.png
   :alt: Referral Program Terms and Conditions modal
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Referral Program Terms & Conditions

Step 4: Copy and share your referral link
=========================================

After enrollment, the Referral Program page opens the **Referrals** tab, where your referral link is shown.

1. Find **Your referral link**.
2. Click the copy icon next to the link.
3. Share the copied link with potential business customers.

.. figure:: https://doc.didww.com/_images/fig4.png
   :alt: Referral Program Referrals tab with referral link and referral table
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Referral link after enrollment

Related resources
=================

- :doc:`How the Referral Program works <../how-referral-program-works>` - Understand referral tracking and commission concepts.
- :doc:`Withdraw referral commissions <withdraw-referral-earnings>` - Request a payout after referral commissions become available.
- :doc:`Referral Program reference <../referral-program-reference>` - Review statuses, terms, and User Panel fields.


.. _user_panel_withdraw_referral_earnings:

=============================
Withdraw referral commissions
=============================

Withdraw approved referral commissions by submitting a bank transfer withdrawal request from the Referral Program page.

For background on pending and available earnings, withdrawal requirements, and other concepts, see :doc:`../how-referral-program-works` and :doc:`../referral-program-reference`.

Before you begin
================

- `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ as the account owner to submit a withdrawal request. Other :ref:`roles <user_panel_roles>` do not have access to this action.
- Make sure your account is enrolled in the Referral Program. If you have not joined, see :doc:`join-referral-program`.
- Make sure your available earnings are at least the minimum withdrawal amount shown in the User Panel.

Step 1: Open the referral program page
======================================

1. In the DIDWW User Panel, open the account dropdown menu.
2. Click **Referral program**.

.. figure:: https://doc.didww.com/_images/fig5.png
   :alt: Account menu with Referral program item
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Open Referral Program from the account menu

Step 2: Open the withdrawal modal
=================================

Review the **Available earnings** tile and click **Withdraw Now**.

.. note::
   - Pending earnings are not included in available earnings and cannot be withdrawn until they become available. For additional information, see :doc:`../how-referral-program-works`.
   - Referral withdrawal requests are created for your full available approved balance and cannot be adjusted.

.. figure:: https://doc.didww.com/_images/fig6.png
   :alt: Referral Program Referrals tab with Available earnings tile and Withdraw Now button
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Available earnings and Withdraw Now button

Step 3: Input your bank details
===============================

Fill in the fields that apply to your bank.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Bank location
     - Recommended bank details to provide
   * - EU, UK, and most international banks
     - **IBAN** is usually sufficient. If your UK bank does not issue an IBAN, use **Account number** and **Routing number / Short code** instead.
   * - United States
     - **Account number** and **Routing number / Short code** are usually required.
   * - Other non-IBAN countries
     - **Account number** is usually required. Add **SWIFT / BIC** when available.
   * - International transfers that require additional bank details
     - Provide **IBAN** or **Account number**, then add **SWIFT / BIC**, **Bank name**, and **Bank address** when your bank uses them for incoming transfers.

.. note::
   - **Beneficiary name** and **Bank country** are pre-filled and read-only.

      - Beneficiary name is taken from your DIDWW account identity. To change it, :ref:`edit_an_identity`.
      - Bank country is determined by your billing address. To change it, contact our billing team at `billing@didww.com <mailto:billing@didww.com>`_.
   - For descriptions and examples of each withdrawal modal field, see :ref:`referral_program_reference_referrals_tab_withdrawal_form`.

.. figure:: https://doc.didww.com/_images/fig7.png
   :alt: Withdraw commissions to bank account modal showing beneficiary and bank detail fields
   :figclass: align-center
   :width: 100%

   **Fig. 3.** Withdrawal form with bank details

Step 4: Confirm withdrawal
==========================

Click **Confirm Withdrawal** to initiate the withdrawal.

.. note:: Withdrawals typically take 3-5 business days to process. Our team will contact you if any required bank details are missing.

.. figure:: https://doc.didww.com/_images/fig8.png
   :alt: Withdraw commissions to bank account modal showing bank transfer fields
   :figclass: align-center
   :width: 100%

   **Fig. 4.** Bank transfer details in the withdrawal form

Step 5: Review withdrawal status
================================

After submitting a withdrawal request, review its status from the Withdrawals tab.

1. Go to **Referral Program > Withdrawals**.
2. Find the new withdrawal request in the withdrawal history.
3. Review the **Status** column.

.. note:: If the withdrawal gets rejected, review the reject reason by hovering your cursor on the comment icon next to the **Rejected** status. For status details, see :ref:`referral_program_withdrawal_status_values`.

.. figure:: https://doc.didww.com/_images/fig9.png
   :alt: Referral Program Withdrawals tab showing withdrawal history and statuses
   :figclass: align-center
   :width: 100%

   **Fig. 5.** Withdrawal history

Related resources
=================

- :doc:`How the Referral Program works <../how-referral-program-works>` - Understand pending and available earnings.
- :doc:`Join the Referral Program <join-referral-program>` - Join the program and get your referral link.
- :doc:`Referral Program reference <../referral-program-reference>` - Review withdrawal fields, statuses, and validation rules.


.. _user_panel_referral_program_reference:

==========================
Referral program reference
==========================

Referral Program reference explains program terms, User Panel fields, account status values, commission statuses, withdrawal statuses, and payout requirements.

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Tab
     - Description
   * - :ref:`Referrals <referral_program_reference_referrals_tab>`
     - Shows the referral link, referral totals, pending earnings, available earnings, and My referrals table.
   * - :ref:`Commissions <referral_program_reference_commissions_tab>`
     - Shows commission totals and a commission log with one row per earned commission.
   * - :ref:`Withdrawals <referral_program_reference_withdrawals_tab>`
     - Shows withdrawal history, bank transfer method details, amount, and withdrawal status.

.. _referral_program_reference_referrals_tab:

Referrals
=========

The Referral Program page is organized into three tabs. The Referrals tab focuses on the referral link, referral activity, and the balances tied to each referred account.

Summary tiles
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Total referrals
     - Total number of referred accounts linked to your referral activity.
   * - Pending earnings
     - Referral commissions currently in the 90-day pending period before they become available for withdrawal.
   * - Available earnings
     - Approved referral commissions available for withdrawal when the minimum withdrawal amount of $500 is reached.
   * - Referral link
     - Your unique public link for inviting new customers to DIDWW.

My referrals table fields
-------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Referral ID
     - A reference ID for a referred account relationship.
   * - Registered At
     - Date and time when the referred account registered. By default, the referral validity period starts on this date and lasts 12 months.
   * - :ref:`Account Status <referral_program_account_status_values>`
     - Current status of the referral relationship.
   * - Pending
     - Pending commission amount associated with the referral during the 90-day pending period.
   * - Approved
     - Approved commission amount associated with the referral.
   * - Last Activity
     - Most recent qualifying invoice activity for the referred account, when available.
   * - Expires At
     - Date and time when the referral validity period ends. By default, this is 12 months after ``Registered At``.

.. _referral_program_account_status_values:

Account status values
---------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Pending
     - The referred account is linked to your referral, but has not yet generated qualifying invoice activity.
   * - Active
     - The referral is currently eligible to generate commissions from qualifying invoices.
   * - Expired
     - The referral validity period has ended. The referral no longer generates new commissions under normal referral activity.
   * - Closed
     - The referred account has been closed. The referral is no longer active and remains visible in your history.
   * - Terminated
     - The referral was ended before its normal expiry and no longer generates commissions.

.. _referral_program_reference_referrals_tab_withdrawal_form:

Withdraw commissions to bank account window fields
--------------------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Available balance
     - Approved referral commissions included in the withdrawal request. This value is read-only. Once your available earnings reach the minimum withdrawal amount, you can :doc:`withdraw referral commissions <how-to-guides/withdraw-referral-earnings>` for the full available balance only.
   * - Beneficiary name
     - Read-only beneficiary name taken from your DIDWW account identity.
   * - Bank country
     - Read-only bank country determined from your billing address.
   * - IBAN
     - Bank account identifier used for IBAN-supported bank transfers (e.g., ``SK90 1100 0000 0026 1500 1234``).
   * - Account number
     - Bank account number used for non-IBAN bank transfers (e.g., ``1234567890``).
   * - Routing number / Short code
     - Additional routing identifier used when required by the destination bank or country (e.g., ``021000021`` or ``12-34-56``).
   * - SWIFT / BIC
     - Bank identifier commonly used for international bank transfers (e.g., ``AIBKIE2D``).
   * - Bank name
     - Name of the receiving bank (e.g., ``Example Bank``).
   * - Bank address
     - Registered address of the receiving bank, when required (e.g., ``1 Example Street, London EC1A 1AA, United Kingdom``).

.. _referral_program_reference_commissions_tab:

Commissions
===========

The Commissions tab focuses on earned commission records, approval timing, commission rates, and commission status tracking.

Summary tiles
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Total commissions
     - Number of commission rows in the commission log.
   * - Pending total
     - Total commission amount currently in the 90-day pending period.
   * - Total earned
     - Total approved commission amount earned since joining the Referral Program.

Commission log filters
----------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Filter
     - Filter condition
     - Description
   * - Commission ID
     - Equals text input
     - Filters commission logs by commission reference ID.
   * - Referral ID
     - Equals text input
     - Filters commission logs by referral reference ID.
   * - :ref:`Status <referral_program_commission_status_values>`
     - Searchable single-select filter
     - Filters commission logs by commission status.

Commission log fields
---------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Commission ID
     - Reference ID for a commission entry.
   * - Date
     - Date and time when the commission was created.
   * - Referral ID
     - Referral reference ID associated with the commission.
   * - Commission
     - Net commission amount after eligible corrections.
   * - Commission Rate
     - Rate used to calculate that commission.
   * - :ref:`Status <referral_program_commission_status_values>`
     - Current commission status.
   * - Approves On
     - Projected approval date for a pending commission.

.. _referral_program_commission_status_values:

Commission status values
------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Pending
     - The commission was created but is still within the pending period.
   * - Approved
     - The commission completed the pending period and is included in available earnings.
   * - Canceled
     - The pending commission was canceled and is not included in available earnings.
   * - Withdrawn
     - The approved commission has been included in a completed withdrawal payout.

.. _referral_program_reference_withdrawals_tab:

Withdrawals
===========

The Withdrawals tab focuses on payout requests, bank transfer details, and withdrawal history.

Filters
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Filter
     - Filter condition
     - Description
   * - Withdrawal ID
     - Equals text input
     - Filters withdrawal history rows by withdrawal reference.
   * - :ref:`Status <referral_program_withdrawal_status_values>`
     - Searchable single-select filter
     - Filters withdrawal history rows by withdrawal status.

Withdrawal history fields
-------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Field
     - Description
   * - Withdrawal ID
     - Reference ID for the withdrawal request.
   * - Date
     - Date and time when the withdrawal request was created.
   * - Method
     - Payout method and bank identifier.
   * - Amount
     - Approved balance included in the withdrawal request.
   * - :ref:`Status <referral_program_withdrawal_status_values>`
     - Current withdrawal status.

.. _referral_program_withdrawal_status_values:

Withdrawal statuses
-------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80
   :width: 100%

   * - Status
     - Description
   * - Pending
     - The withdrawal request was submitted and is awaiting processing.
   * - Completed
     - The withdrawal was processed and completed.
   * - Rejected
     - The withdrawal was rejected. The status may include a rejection reason and comment, and the reserved approved commissions are returned to available earnings.

Related resources
-----------------

- :doc:`How the Referral Program works <how-referral-program-works>` - Understand the program model and payout concepts.
- :doc:`Join the Referral Program <how-to-guides/join-referral-program>` - Enroll and get your referral link.
- :doc:`Withdraw referral commissions <how-to-guides/withdraw-referral-earnings>` - Submit and review withdrawal requests.



.. |br| raw:: html

   <br />

.. _presence:

=======================
Network Infrastructure
=======================

DIDWW operates a globally distributed voice network designed for high availability, low latency, and geographic redundancy. Our Points of Presence (PoPs) are strategically located in major interconnection hubs worldwide to ensure optimal routing and service quality.

.. raw:: html

   <br>

Points of Presence (PoPs)
=============================

North America
-----------------

.. grid:: 1 1 1 3
   :gutter: 3

   .. grid-item-card::  🇺🇸 **New York, USA**
      :text-align: left
      :shadow: sm

      |br|
      **Location:** 111 8th Avenue, Digital Realty |br|
      **Region:** North America |br|
      |br|

   .. grid-item-card:: 🇺🇸 **Los Angeles, USA**
      :text-align: left
      :shadow: sm

      |br|
      **Location:** One Wilshire, CoreSite |br|
      **Region:** North America |br|
      |br|

   .. grid-item-card:: 🇺🇸 **Miami, USA**
      :text-align: left
      :shadow: sm
      :class-card: sd-border-success

      |br|
      **Location:** 50 NE 9th Street, Equinix MI1 |br|
      **Region:** North America |br|
      |br|

Europe
-----------------

.. grid:: 1 1 1 3
   :gutter: 3

   .. grid-item-card:: 🇩🇪 **Frankfurt, Germany**
      :text-align: left
      :shadow: sm
      :class-card: sd-border-info

      |br|
      **Location:** Kleyerstraße 90, ITENOS |br|
      **Region:** Europe
      |br|

   .. grid-item-card:: 🇳🇱 **Amsterdam, Netherlands**
      :text-align: left
      :shadow: sm
      :class-card: sd-border-info

      |br|
      **Location:** Kuiperbergweg 13, Equinix AM7 |br|
      **Region:** Europe |br|
      |br|

Asia-Pacific
-----------------

.. grid:: 1 1 1 3
   :gutter: 3

   .. grid-item-card:: 🇸🇬 **Singapore**
      :text-align: left
      :shadow: sm
      :class-card: sd-border-warning

      |br|
      **Location:** 26A Ayer Rajah Crescent, Equinix SG3 |br|
      **Region:** Asia-Pacific |br|
      |br|

   .. grid-item-card:: 🇭🇰 **Hong Kong**
      :text-align: left
      :shadow: sm
      :class-card: sd-border-warning

      |br|
      **Location:** 17/F Global Gateway, Equinix HK1 |br|
      **Region:** Asia-Pacific |br|
      |br|

.. note::

   For IP configuration details, refer to the :ref:`Inbound Trunks SIP Information <service_did_sip>` and :ref:`Outbound Trunks Signaling Endpoints <voice-out-signaling-endpoints>`.

----

.. raw:: html

   <br>

.. _network_interconnection:

Interconnections
================

DIDWW supports several methods of interconnecting with its global voice infrastructure to enhance call quality, reliability, and security. These include private physical connections, public Internet Exchange peering, and encrypted VPN tunnels.

.. note::

   For a full overview of our network footprint, visit our `PeeringDB profile <https://www.peeringdb.com/org/26616>`_. |br| To discuss interconnection options, please contact your account manager or email sales@didww.com.

.. raw:: html

   <br>

Private Interconnection
-------------------------

Connect directly to DIDWW's infrastructure at one or more global Points of Presence (PoPs). This is the most secure and performance-optimized interconnection method. Physical connectivity requires coordination and infrastructure setup at the selected PoP.

.. figure:: https://doc.didww.com/_images/Private_Interconnection_v2.svg
   :figclass: align-center
   :class: no-shadow
   :width: 90%
   :alt: Private physical interconnection scheme

   **Fig. 1.** Private physical interconnection scheme

.. raw:: html

   <br>

Public Peering Facilities
----------------------------------

DIDWW supports peering via major Internet Exchange platforms. This allows for flexible and scalable interconnection across multiple geographic locations using public VLANs or virtual private interconnects.

      - **DE-CIX** – Present at New York and Frankfurt. Peering via `DE-CIX <https://www.de-cix.net>`_, or use `Virtual PNI <https://www.de-cix.net/en/services/virtualpni>`_.
      - **AMS-IX** – Connected in Amsterdam via `AMS-IX <https://www.ams-ix.net/ams>`_. Supports `AMS-IX Private Interconnect <https://www.ams-ix.net/ams/service/private-interconnect>`_.
      - **Equinix IX** – Available in Amsterdam via `Equinix IX <https://ix.equinix.com/home/>`_.
      - **Equinix Fabric** – Supported in Frankfurt and Amsterdam via `Equinix Fabric <https://www.equinix.com/products/digital-infrastructure-services/equinix-fabric>`_.
      - **PCCW Console Connect** – Accessible through `Console Connect <https://www.consoleconnect.com>`_ SDN platform in Hong Kong.

.. figure:: https://doc.didww.com/_images/Public_Peering_Facilities_v2.svg
   :figclass: align-center
   :class: no-shadow
   :width: 90%
   :alt: Peering scheme

   **Fig. 2.** Peering interconnection scheme

.. raw:: html

   <br>

IPSec VPN
----------------------------------

DIDWW offers encrypted interconnection over IPSec VPN, allowing secure voice traffic routing over public infrastructure. While this option does not impact pathing, it provides strong encryption and supports private IP addressing for SIP endpoints.

Supported PoPs for IPSec VPN:

      - USA, New York
      - Germany, Frankfurt

Multiple VPN tunnels are recommended for failover and redundancy.

.. figure:: https://doc.didww.com/_images/IPSec_VPN_v2.svg
   :figclass: align-center
   :class: no-shadow
   :width: 90%
   :alt: VPN interconnection scheme

   **Fig. 3.** IPSec VPN interconnection scheme



.. _glossary:

Glossary
=============

.. raw:: html

    <style>
        .sd-tab-set > input:checked + label + .sd-tab-content {
            -moz-animation: sd-fade-in .5s ease-in-out;
            -webkit-animation: sd-fade-in .5s ease-in-out;
            animation: sd-fade-in .5s ease-in-out;
        }

        @keyframes sd-fade-in {
            from {
                opacity: 0;
            }
            to {
                opacity: 1;
            }
        }
    </style>

.. tab-set::
   :class: my-tabs

   .. tab-item:: A

      .. glossary::
         :sorted:

         A2P Messaging
           Application-to-Person Messaging; the process where a software application sends messages or notifications to individuals or end-users.

         Amazon Chime SDK
           A set of real-time communications components provided by Amazon Web Services (AWS) that developers can use to add audio capabilities to their applications.

         API
           Application Programming Interface; a set of protocols and tools for building software applications, allowing integration with DIDWW services.

         API Keys
           Unique identifiers used to authenticate requests associated with your DIDWW account, ensuring secure access to the API.

         Asterisk
           An open-source framework for building communications applications such as IP PBX systems, VoIP gateways, and conference servers.

         ACD
           Average Call Duration (ACD) is the average length of time a call lasts, used to measure call activity and efficiency in telecommunications.

         ASR
           Answer-Seizure Ratio (ASR) is a metric indicating the percentage of successfully answered calls compared to the total call attempts, used to evaluate call quality and network performance.

         AI
           Artificial Intelligence (AI) is a technology that enables machines to perform tasks typically requiring human intelligence, such as learning, reasoning, and decision-making. In telecommunications, AI is used for the delivery and analysis of call recordings, providing insights into inbound, outbound, and internal calls.

         Alphanumeric
           A combination of letters (A–Z) and numbers (0–9) used to represent data or identifiers. In telecommunications, alphanumeric sender IDs are commonly used in messaging to display a brand name or custom text as the sender of an SMS, enhancing brand recognition and trust.

         App
           Application is a software program designed to perform specific tasks or provide functionality on a device, such as a computer, smartphone, or web platform. In telecommunications, apps often include tools for facilitating communication, such as softphone apps.

         API Callback
           An automated action where a system sends real-time event data or status updates to a predefined URL, known as the callback endpoint. API callbacks enable event-driven communication between systems.

         Auto Top-Up
           A feature that automatically replenishes a prepaid balance when it drops below a defined threshold, ensuring continuous service without manual payments.

   .. tab-item:: B

      .. glossary::
         :sorted:

         Billing
           The process of invoicing and charging customers for services provided, including tracking usage and payments.

         Billing Cycles
           The regular intervals at which service usage is measured and invoices are generated. Each cycle defines the period covered for charges and payments.

         BYOC
           Bring Your Own Carrier; a service model allowing businesses to use their own preferred carrier with third-party communication platforms.

         Bulk Messaging
           The process of sending a large volume of messages simultaneously to multiple recipients, commonly used for marketing campaigns and notifications.

         Batch actions
           A functionality that allows users to perform multiple operations or updates simultaneously on a set of items, such as DIDs, configurations, or routing settings. Batch actions streamline workflows by reducing the time and effort required for repetitive tasks, enabling efficient management of large-scale telecommunications resources.

         BGP Anycast
           A routing technique in which multiple servers share the same IP address, and incoming traffic is routed to the nearest or best-performing server based on the Border Gateway Protocol (BGP).

         Blocklist
              A list of phone numbers that are explicitly blocked from accessing or interacting with a service. In telecommunications, blocklists are commonly used to prevent unwanted calls.

   .. tab-item:: C

      .. glossary::
         :sorted:

         Call Queuing
           A telephony feature that places incoming calls in a virtual queue when all available agents or endpoints are busy. Callers are typically provided with hold music, estimated wait times, or announcements while waiting for the next available agent. Call queuing is commonly used in customer service environments to manage high call volumes efficiently.

         Credentials
           Authentication information, such as usernames, passwords, API keys, or tokens, used to verify a user's identity and grant secure access to systems, services, or applications. In telecommunications, credentials are critical for accessing services like SIP trunks, APIs, and user portals.

         CDR
           Call Data Record (CDR) consists of detailed information about a telephone call, including duration, time, and parties involved.

         Cloud Storage
           A service that allows users to store, manage, and access data over the internet instead of on local hardware. In telecommunications, cloud storage is often used to archive call recordings.

         Call Logs
           Detailed call history, with optional date filters.

         Call Events
           DIDWW Events API enables customers to receive realtime Call Events and CDRs to customers designated HTTP Endpoint. This web-hook mechanism provides flexibility to develop applications for near real-time call processing, CDR receiving, billing and tracking purposes.

         CDR Streaming
           An Application Programming Interface (API) that provides real-time access to Call Detail Records (CDRs) as calls are processed. This enables efficient tracking, monitoring, and analysis of call data for purposes such as billing, reporting, and operational insights. CDR Streaming APIs are particularly useful in environments requiring near-instantaneous updates on call activity.

         Call Flow
           The predefined sequence of actions or routing logic that a telecommunication system follows to handle an incoming or outgoing call. Call flows determine how calls are processed, including steps like IVR interactions, call routing, voicemail handling, and failover mechanisms. Properly designed call flows enhance user experience and operational efficiency.

         Call Forwarding
           The process of redirecting incoming calls from one phone number to another.

         Capacity
           The maximum number of simultaneous inbound calls per Direct Inward Dialing (DID) number.

         CDR Export
           The process of exporting Call Data Records for analysis, reporting, or record-keeping purposes.

         CLI
           Calling Line Identification; a feature that identifies and displays the telephone numbers of incoming calls.

         CNAM IN
           Enables the delivery of the caller’s name to the customer’s endpoint set in trunk settings.

         CNAM OUT
           Assigns a caller’s name to the DID number, which will be displayed for the receiving party during the call, if the destination operator is performing CNAM lookup.

         Configuration Profiles
           Predefined settings that allow for the easy distribution and configuration of multiple DID numbers requiring the same settings.

         CRM
           Customer Relationship Management (CRM) is a system used by businesses to manage interactions and relationships with current and potential customers.

         CPC
           Calling Party Category is a parameter in telecommunications signaling that identifies the type or classification of the calling party. CPC information is used to influence call treatment, such as prioritizing emergency calls or routing calls based on their origin. Examples of CPC values include "ordinary subscriber," "payphone," or "emergency services."

         Concurrent Calls
           The number of simultaneous active calls that can be handled by a telecommunication system or service at any given time. Concurrent call capacity is a critical metric for systems like SIP trunks, PBXs, or VoIP platforms and is influenced by factors such as bandwidth, licensing, and system configuration.

         Codec
           Short for "coder-decoder" a codec is a device or software that compresses and decompresses digital media, such as audio or video. In telecommunications, codecs are used to encode voice signals for transmission over IP networks and to decode them at the destination. Common voice codecs include G.711, G.729, and Opus, each balancing factors like bandwidth usage and audio quality.

         Callback
           A telephony feature that automatically returns a call to a user or endpoint after an initial request or attempt.

         Callback URL
           The specific URL endpoint configured to receive real-time call events or status updates from DIDWW systems.

         Call Recording
           A feature that enables the recording and storage of inbound or outbound call audio for quality assurance, compliance, or analysis purposes.

   .. tab-item:: D

      .. glossary::
         :sorted:

         DID
           Direct Inward Dialing; a local telephone number in a selected country or city, also known as DDI in Europe or a virtual number.

         DTMF
           Dual-Tone Multi-Frequency (DTMF) is a signaling system used in telecommunication to send digits or commands via distinct tone pairs, commonly used for dialing and interactive voice response systems.

         Digest Authentication
           A security protocol used in telecommunications and web applications to verify a user's identity by exchanging hashed credentials instead of transmitting plain-text passwords. In SIP (Session Initiation Protocol) systems, digest authentication ensures secure communication by requiring the client to provide a hashed response to a server's challenge, using shared credentials and a nonce value.

         DLR
           Delivery Receipt also known as Delivery Report; a notification from an SMSC or carrier confirming the status of an SMS message. Indicates whether the message was delivered, failed, or is pending.

         Direct Routing
           A method of connecting external telephony services, such as DIDWW trunks, to platforms like Microsoft Teams, enabling inbound and outbound calls through the PSTN.

         Destination
           The endpoint or number to which an inbound call is routed, as defined in the configuration of a trunk or DID.

   .. tab-item:: E

      .. glossary::
         :sorted:

         ESME
           External Short Messaging Entity (ESME) is an external application that connects to an SMSC to send and receive SMS messages.

         Emergency Calling
           The ability to make calls to emergency services, such as 911 in the United States or 112 in many European countries.

         Environments
           The various settings and URLs used to access different stages of the DIDWW API, such as production, and sandbox environments.

         E.164
           E.164 is an international phone number format ensuring global uniqueness, consisting of a + prefix, country code, area code, and subscriber number (e.g., +1 212 555 0123).

         Extension
           A short, internal number assigned to an individual user, device, or department within a private telephony system, such as a PBX. Extensions enable users to make internal calls within the organization without dialing a full phone number and can also be used in conjunction with external numbers for direct routing.

         Endpoint
           A device or application that serves as a termination point for communication in a network. In telecommunications, endpoints can include SIP phones, softphones, or any other devices capable of sending or receiving voice over a network. Endpoints are integral to establishing and managing VoIP or other communication sessions.

   .. tab-item:: F

      .. glossary::
         :sorted:

         FAX
           The telephonic transmission of scanned-in printed material (text or images), usually to a telephone number associated with a printer or other output device.

         FOC date
           Indicates the date your previous carrier is expected to finalize porting your phone number(s), enabling them for use with your new carrier.

         Failover
           A redundancy mechanism that automatically reroutes calls or services to a predefined backup destination when the primary endpoint or route becomes unavailable. Failover ensures service continuity and minimizes downtime in telecommunications systems, making it a critical feature for reliable call handling.

         FTP
           File Transfer Protocol (FTP) is a standard network protocol used to transfer files between a client and a server over the internet or a private network. In telecommunications, FTP is commonly employed for exchanging configuration files, logs, or reports between systems.

   .. tab-item:: G

      .. glossary::
         :sorted:

         Geographical Number
           A local number belonging to a particular area or city within a country.

   .. tab-item:: H

      .. glossary::
         :sorted:

         Hosted PBX
           A cloud-based Private Branch Exchange (PBX) system managed by a service provider, reducing the need for on-premises hardware.

         Host
           A server, device, or system that provides services or resources to other devices or users in a network. In telecommunications, a host often refers to the system managing SIP endpoints, PBX services, or API endpoints.

   .. tab-item:: I

      .. glossary::
         :sorted:

         Identities
           Verified information associated with a user or entity, used for authentication and authorization purposes.

         Integrations
           The process of connecting DIDWW services with third-party applications or platforms to enhance functionality.

         IVR
           Interactive Voice Response; an automated telephony system that interacts with callers through voice prompts and keypad inputs.

         IOT
           Internet of Things (IOT) is a network of interconnected physical devices, sensors, and software that communicate and exchange data over the internet without requiring human-to-human or human-to-computer interaction.

         ISP
           Internet Service Provider (ISP) is a company or organization that provides access to the internet for individuals, businesses, and other entities. ISPs offer various services, including broadband, fiber-optic, DSL, and wireless internet connections, as well as ancillary services like email hosting and domain registration.

         IXP
           Internet Exchange Point (IXP) is a physical infrastructure that enables different internet service providers (ISPs), content delivery networks (CDNs), and other network operators to exchange traffic between their networks. IXPs improve internet performance by reducing latency and bandwidth costs through direct interconnection.

         Internal Numbers
           Phone numbers used within an organization's private telephony system, such as a PBX, to facilitate communication between employees or departments without requiring external dialing. Internal numbers are often shorter than public phone numbers and are not accessible from outside the organization.

         IP-based Authentication
           A security mechanism that allows access to a service or system based on the originating IP address. In telecommunications, IP-based authentication is commonly used for SIP trunking and VoIP services to validate incoming requests from trusted IP addresses, eliminating the need for username and password credentials.

         IPSec VPN
           Internet Protocol Security Virtual Private Network is a secure communication method that uses the IPSec protocol suite to encrypt and authenticate data transmitted over a virtual private network (VPN). IPSec VPNs are commonly used in telecommunications to establish secure connections between endpoints, ensuring confidentiality, data integrity, and protection against unauthorized access.

         Inbound Trunk
           A trunk configuration used to route incoming calls from DID numbers to customer endpoints or systems.

         Instant Payment
           A feature that enables immediate balance replenishment using a saved payment method or a credit card, without waiting for confirmation or manual approval.

   .. tab-item:: L

      .. glossary::
         :sorted:

         Latency
           The time delay between the initiation of a communication signal and its reception at the destination. In telecommunications, latency is a critical metric for assessing the performance of voice and data networks, as excessive latency can degrade call quality and user experience. Low latency is particularly important for real-time services such as VoIP conferencing.

         LNP
           Local Number Portability; the ability to transfer a phone number from one service provider to another.

         LOA
           A document granting permission to port phone numbers from one carrier to another, required by DIDWW to process number transfers.

         LOI
            is a document that outlines the preliminary understanding between parties intending to enter into a formal agreement.

         Lost Calls
           Calls that were initiated but not successfully connected.

         Load Balancing
           A method of distributing network traffic or service requests across multiple servers, endpoints, or routes to ensure efficient resource utilization, reduce latency, and prevent system overload. In telecommunications, load balancing improves the reliability and performance of services such as VoIP, messaging, and API operations by managing traffic dynamically based on demand.

         Long-code
           A standard 10-digit phone number used for person-to-person (P2P) and application-to-person (A2P) messaging or voice communication. Long codes are commonly used for two-way communication, such as customer service, notifications, and marketing, and are ideal for lower-volume messaging due to regulatory and throughput limitations.

         Local Routes
           Telecommunication routes that prioritize local carriers or networks for terminating calls, typically within the same geographic region or country as the destination number. Local routes are often used to improve call quality, reduce latency, and minimize costs by leveraging infrastructure close to the call's endpoint.

   .. tab-item:: M

      .. glossary::
         :sorted:

         Metered Number
           A Direct Inward Dialing (DID) number charged per minute.

         Microsoft Teams Direct Routing
           A feature that allows the integration of external telephony services with Microsoft Teams, enabling users to make and receive calls.

         MO
           MO (Mobile-Originated) messages sent from a mobile device to a server or another mobile.

         MT
           MT (Mobile-Terminated) messages sent to a mobile device, such as notifications or alerts.

         MMC
           Minimum Monthly Commitment (MMC) refers to the amount that needs to be deposited every month to qualify for particular pricing.

         Mobile Number
           A number from the mobile numbering plan, which differs by country.

         MRC
           Monthly Recurring Cost; an ongoing monthly fee applied for service renewal.

         Multi-Channel Messaging
           The ability to send messages through multiple communication channels, such as SMS, WhatsApp, or email, from a single platform.

   .. tab-item:: N

      .. glossary::
         :sorted:

         National Number
           A telephone number not restricted to a particular city or area within a country, also known as a nomadic number.

         NPA
           Numbering Plan Area (NPA), commonly known as the area code, the NPA is a three-digit code that designates a specific geographic region within the North American Numbering Plan (NANP). It is the first part of a 10-digit telephone number and is used to route calls to the appropriate region.

         NRC
           Non-Recurring Cost; a one-time setup fee applied for service activation.

         NXX
           Exchange Code (NXX) is a three-digit code that follows the NPA (area code) in a phone number and identifies a specific telephone exchange or central office within the area code. It plays a crucial role in routing calls within the NANP.

   .. tab-item:: O

      .. glossary::
         :sorted:

         Opt-out
           The process by which a recipient declines or unsubscribes from receiving further communications, such as SMS, email, or calls.

         Order
           A purchase or renewal of any service.

         Omnichannel
           A platform that integrates multiple communication channels like SMS, whatsapp, and email.

         OS
           The software that manages hardware and software resources on a device, providing a foundation for applications to run. Common operating systems include Windows, macOS, Linux, Android, and iOS. In telecommunications, the OS is critical for managing applications such as softphones, PBX systems, and communication tools.

         Outbound Trunk
           A trunk configuration that allows outbound calls to be placed from customer systems through DIDWW’s network.

   .. tab-item:: P

      .. glossary::
         :sorted:

         P2P Messaging
           Person-to-Person Short Message Service; the exchange of SMS between individuals.

         PAI
           P-Asserted-Identity; a SIP header used to convey the caller's identity within trusted networks for authentication and call routing.

         Payphone
           A public telephone, typically coin or card-operated, that allows users to make calls without requiring a personal telephone line or mobile device.

         Payment
           A transaction made by credit card, wire transfer, or PayPal.

         phone.systems™
           The phone.systems™ PBX offers a user-friendly, cloud-based PBX with drag-and-drop setup. This guide covers everything from system basics to advanced settings, helping you manage users, call flows, analytics, and more. Start with the introduction and explore specific sections as needed for full system optimization.

         Prepaid Balance
           A certain amount of money on the customer’s account used to pay for services.

         POP
           Point of Presence (POP) refers to a physical or virtual location where DIDWW physically connects to the internet or another network.

         Prefix
           A numerical code at the beginning of a phone number that identifies a specific geographic region, service provider, or type of service. In telecommunications, prefixes are used for call routing, billing, and determining the destination of a call. For example, in international dialing, country codes serve as prefixes to indicate the destination country.

         PSTN
           Public Switched Telephone Network; traditional phone lines, both fixed and mobile.

         PBX
           Private Branch Exchange (PBX) is a private telephone system used within organizations to manage calls internally and externally, enabling features like call routing, voicemail, and conferencing.

         PSAP
           Public Safety Answering Point (PSAP) is a facility responsible for receiving and processing emergency calls, such as those made to 911 in the United States or 112 in Europe. PSAPs route calls to the appropriate emergency services, such as police, fire, or medical responders. In telecommunications, ensuring accurate call routing and location information to PSAPs is critical for effective emergency response.

         Port In
           The process of transferring an existing phone number from another carrier to DIDWW.

         Port Out
           The process of transferring a DIDWW number to another carrier at the customer's request.

         Production Environment
           The live environment used for real operations and customer data.

   .. tab-item:: Q

      .. glossary::
         :sorted:

         QoS
           Quality of Service (QoS) is a set of technologies and policies used to prioritize and manage network traffic to ensure optimal performance for critical applications, such as voice services. In telecommunications, QoS is essential for maintaining call quality, minimizing latency, and preventing packet loss in VoIP and other real-time communications.

   .. tab-item:: R

      .. glossary::
         :sorted:

         Rate Limits
           Restrictions placed on the number of API requests a user can make within a given time period to ensure fair usage and prevent abuse.

         RTP
           Real-time Transport Protocol (RTP) is a standardized network protocol used for delivering audio, and other types of real-time data over IP networks.

         RUN
           Routing User Number (RUN) is a unique identifier used in telecommunications to facilitate the routing of calls, often within private or specialized networks. The RUN ensures that calls are directed to the correct endpoint without relying solely on traditional numbering systems.

         RUT
           Routing Universal Table (RUT) is a centralized table or database used in telecommunications to manage and determine the routing of calls and messages. The RUT simplifies call handling by storing routing information, including destination numbers, carriers, and priority rules.

         Ring Group
           A feature in telephony systems that allows multiple phone lines or extensions to ring simultaneously or in a specific sequence when a single number is called. Ring groups are commonly used to ensure that calls are answered promptly by routing them to a team or department, such as customer support or sales.

   .. tab-item:: S

      .. glossary::
         :sorted:

         SKU
           Stock Keeping Unit (SKU) is a unique identifier for each distinct product or service that can be purchased.

         SMPP
           Short Message Peer-to-Peer (SMPP) is a protocol used by the telecommunications industry for exchanging SMS messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME).

         SMSC
           Short Message Service Center (SMSC) is a network element in the mobile telephone network which delivers SMS messages.

         SAP
           Services Aging Pool; refers to DID numbers that are expired or removed and no longer active but can be restored to a customer’s account.

         SBC
           A network device that manages and secures VoIP communications, controlling signaling and media streams.

         Shared Cost Number
           A number that enables sharing call costs between the caller and the number owner.

         Short Code
           A short, numeric code used for sending and receiving SMS messages, typically for marketing or alerts.

         SID
           Sender ID (SID) is an identifier that represents the sender of an SMS message. SIDs can be alphanumeric, displaying a brand or company name, or numeric, such as a long code or short code. In telecommunications, the Sender ID is used to establish the identity of the sender and enhance trust and recognition among message recipients. The availability and formatting of Sender IDs may vary by country due to local regulations.

         SIP
           Session Initiation Protocol (SIP) is a signaling protocol used in telecommunications to establish, manage, and terminate real-time communication sessions.

         SIP Account
           An account that allows a device or application to register with a SIP server to make and receive VoIP calls.

         SIP Trunk
           A service that allows businesses to connect their private branch exchange (PBX) to the internet, enabling voice over IP (VoIP) calls.

         SLA
           Service Level Agreement; a contract between DIDWW and the customer, stipulating and committing to a certain level of service.

         SMS
           Short Message Service; a text messaging service component of most telephone, internet, and mobile device systems.

         Softphone
           A software-based phone that allows users to make calls over the internet using a computer or mobile device.

         STIR/SHAKEN
           A framework used in the telecommunications industry to combat robocalls and caller ID spoofing by verifying call authenticity.

         Switch
           A device that connects calls by routing voice or data traffic between endpoints within a network.

         SRTP
           Secure Real-Time Transport Protocol (SRTP) is an extension of RTP that provides encryption, authentication, and integrity for securing real-time voice communications.

         SSL
           A cryptographic protocol designed to secure communication over the internet by encrypting data transmitted between a client and a server.

         SFTP
           Secure File Transfer Protocol (SFTP) is a secure protocol for transferring files over a network, leveraging SSH (Secure Shell) to encrypt data during transmission. SFTP ensures confidentiality and integrity, making it a preferred choice for transferring sensitive files such as configuration data, logs, or reports in telecommunications and other industries.

         Sub-Account
           A separate account under a main DIDWW customer profile, allowing independent management of DIDs, trunks, and billing.

         SIP REFER
           A SIP method used to transfer an ongoing call to a new destination, often employed for blind call transfers.

         Sandbox Environment
           A testing environment used for development and integration without affecting live services.

   .. tab-item:: T

      .. glossary::
         :sorted:

         Threshold Amount
           Identifies a certain amount of money in the prepaid balance which triggers automatic refill.

         Toll-Free Number
           A phone number that allows callers to reach businesses or individuals without incurring charges for the call.

         Trunk
           Defines the connection between a DID and its call destination.

         Trunk Group
           Trunk Group is a logical grouping of multiple trunks.

         Two-Factor Authentication (2FA)
           Two-Factor Authentication (2FA) is a security mechanism that enhances account protection by requiring users to verify their identity using two distinct authentication methods. It adds an extra layer of security beyond just a username and password, making unauthorized access significantly more difficult.

         TCP
           Transmission Control Protocol (TCP) is a reliable, connection-oriented transport protocol that ensures data delivery in the correct order.

         TLS
           Transport Layer Security (TLS) is a cryptographic protocol that secures data transmission over networks by encrypting and authenticating communication channels.

         Third-Party
           An external entity, organization, or service provider that is not directly affiliated with DIDWW but interacts with its systems or services. In telecommunications, third-party providers may supply software, integrations, or services such as carriers, and analytics platforms, extending the capabilities DIDWW.

         Time Schedule
           A predefined configuration that controls the activation or routing of telecommunication services based on specific time periods. Time schedules are often used in call routing to direct calls to different destinations during business hours, after hours, or holidays, ensuring efficient handling of calls based on organizational needs.

         Termination
           The process of delivering outbound calls from a customer’s system to external networks or phone numbers.

   .. tab-item:: U

      .. glossary::
         :sorted:

         UCaaS
           Unified Communications as a Service; a cloud-based delivery model for communication and collaboration tools such as voice and messaging.

         UIFN
           Universal International Freephone Number (UIFN) is a global toll-free telephone number that allows callers from multiple countries to reach a business or organization without incurring any charges for the call.

         UDP
           User Datagram Protocol (UDP) is a lightweight, connectionless transport protocol used for fast data transmission without guaranteeing delivery, commonly employed in real-time applications like VoIP.

         UI
           User Interface (UI) is the visual and interactive elements of a software application or system that allow users to interact with and control the service. In telecommunications, the UI typically refers to dashboards, control panels, or mobile app interfaces that enable users to manage features such as call routing, messaging, and account settings.

   .. tab-item:: V

      .. glossary::
         :sorted:

         Voicemail
           A system that records and stores audio messages from callers for later retrieval.

         VoIP
           Voice over Internet Protocol; a technology that allows voice communication over the internet instead of traditional phone lines.

         VAT
           Value-Added Tax (VAT) is a consumption tax applied to goods and services at each stage of production or distribution, typically levied by governments. In telecommunications, VAT is often added to invoices for services provided, depending on the customer’s location and applicable tax regulations.

   .. tab-item:: W

      .. glossary::
         :sorted:

         WebRTC
           Web Real-Time Communication is an open-source technology enabling real-time calls between web browsers or applications without additional plugins.

         Webhooks
           Automated HTTP callbacks used by DIDWW APIs to deliver real-time event notifications to customer applications.

.. This script automatically opens the correct glossary tab when a user accesses
.. a glossary term via a direct link (e.g., #term-WebRTC).

.. raw:: html

    <script>
        document.addEventListener("DOMContentLoaded", function () {
            const hash = window.location.hash;
            if (hash.startsWith("#term-")) {
                // Extract term name (e.g., "WebRTC" from "#term-WebRTC")
                const termName = hash.replace("#term-", "");
                if (termName.length > 0) {
                    // Get the first letter (e.g., "W" for "WebRTC")
                    const firstLetter = termName.charAt(0).toUpperCase();

                    // Locate the correct tab item based on the first letter
                    let tabButton = [...document.querySelectorAll(".sd-tab-label")].find(label =>
                        label.textContent.trim() === firstLetter
                    );

                    if (tabButton) {
                        tabButton.click();
                    }
                }
            }
        });
    </script>


Certifications and Memberships
==============================

DIDWW maintains recognized information security practices and participates in key telecommunications industry organizations.

ISO/IEC 27001:2022 Certification
--------------------------------

DIDWW holds an ISO/IEC 27001:2022 certification for its Information Security Management System (ISMS).

ISO/IEC 27001:2022 is an internationally recognized standard for Information Security Management Systems. DIDWW maintains an Information Security Management System designed to support the confidentiality, integrity, and availability of information assets.

DIDWW's Information Security Management System is certified against ISO/IEC 27001:2022 by Bureau Veritas, an accredited certification body.

DIDWW publicly announced its ISO/IEC 27001 certification in June 2023. The publicly announced certification scope covers personnel, business processes, software development activities, and supporting infrastructure used in the provision of voice, messaging, and cloud PBX services.

`DIDWW ISO/IEC 27001 announcement <https://news.didww.com/2023/06/14/global-telecoms-provider-didww-is-iso-27001-certified/>`_

Industry memberships
--------------------

DIDWW participates in a number of telecommunications industry organizations.

.. list-table::
   :header-rows: 1
   :widths: 35 25 45

   * - Organization
     - DIDWW participation
     - Public reference
   * - International Telecommunication Union (ITU)
     - Member and contributor
     - `ITU membership listing for Ireland, 2021 <https://www.itu.int/online/mm/scripts/gensel9?_ctryid=1000100565&_ctryname=Ireland>`_
   * - RIPE Network Coordination Centre (RIPE NCC)
     - Member
     - `RIPE NCC member index, 2021 <https://www.ripe.net/membership/indices/data/ie.didwwltd.html>`_
   * - Communications Fraud Control Association (CFCA)
     - Member
     - `CFCA membership announcement, 2022 <https://news.didww.com/2022/05/11/didww-joins-communications-fraud-control-association-cfca/>`_
   * - Pacific Telecommunications Council (PTC)
     - Member
     - `PTC membership announcement, 2023 <https://news.didww.com/2023/12/12/didww-joins-the-pacific-telecommunications-council/>`_

Membership in these organizations demonstrates participation in industry forums and professional communities.

ITU-assigned international network code
---------------------------------------

DIDWW has been assigned the international shared country code +883 5170 by the International Telecommunication Union (ITU).

The assignment was published in the ITU Operational Bulletin in May 2019.

`ITU Operational Bulletin amendment for +883 5170 <https://www.ituob.org/issues/1173-en/#amendments-3>`_

:html_theme.sidebar_secondary.remove: true

.. _service_phone_systems2:

Cloud Phone System
==================

The phone.systems™ PBX offers a user-friendly, cloud-based PBX with drag-and-drop setup. This guide covers everything from system basics to advanced settings, helping you manage users, call flows, analytics, and more. Start with the introduction and explore specific sections as needed for full system optimization.

.. grid:: 1 1 3 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`info` **Introduction**
      :link: Introduction/index
      :link-type: doc
      :text-align: left

      Learn the basics of phone.systems™, its capabilities, and architecture.

   .. grid-item-card:: :octicon:`light-bulb` **Getting Started**
      :link: Getting-started/index
      :link-type: doc
      :text-align: left

      Step-by-step guide to quickly set up and begin using phone.systems™ effectively.

   .. grid-item-card:: :octicon:`credit-card` **Subscription Details**
      :link: subscription-details/index
      :link-type: doc
      :text-align: left

      Review your subscription plan and usage summary.

   .. grid-item-card:: :octicon:`device-mobile` **phone.systems™ App**
      :link: app/index
      :link-type: doc
      :text-align: left

      Cross-platform SIP-based app with HD audio, secure VoIP, CRM integrations, and real-time call management.

.. raw:: html

   </br>

phone.systems™ Admin UI
-----------------------

.. grid:: 1 1 3 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: |default| **Call Flows**
      :link: Call-flows/index
      :link-type: doc
      :text-align: left

      Configure and manage call flows, objects, and softphones for optimized call handling.

   .. grid-item-card:: |users| **Users**
      :link: Users/index
      :link-type: doc
      :text-align: left

      Create, edit, and manage user profiles.

   .. grid-item-card:: |contact-methods| **Contact Methods**
      :link: Contact-methods/index
      :link-type: doc
      :text-align: left

      Define how and where calls are delivered for each contact.

   .. grid-item-card:: |phone-numbers| **Numbers**
      :link: Numbers/index
      :link-type: doc
      :text-align: left

      Configure and manage phone numbers and internal extensions.

   .. grid-item-card:: |time-schedules| **Time Schedules**
      :link: Time-schedules/index
      :link-type: doc
      :text-align: left

      Configure time-based routing and call handling rules.

   .. grid-item-card:: |delivery-methods| **Delivery Methods**
      :link: Delivery-methods/index
      :link-type: doc
      :text-align: left

      Configure and manage delivery methods for voicemails, recordings, faxes, and notifications.

   .. grid-item-card:: |audio-files| **Audio Files**
      :link: Audio-files/index
      :link-type: doc
      :text-align: left

      Upload and manage audio files and playlists for greetings, music-on-hold, and call flow announcements.

   .. grid-item-card:: |trunks| **Trunks**
      :link: Trunks/index
      :link-type: doc
      :text-align: left

      Manage inbound and outbound trunks, gateways, and routes for seamless call routing.

   .. grid-item-card:: |call-analytics| **Call Analytics**
      :link: Call-analytics/index
      :link-type: doc
      :text-align: left

      Access detailed CDRs and performance metrics to track call activity and optimize handling.

   .. grid-item-card:: |contacts| **Contacts**
      :link: Contacts/index
      :link-type: doc
      :text-align: left

      Store and organize contact information within the system.

   .. grid-item-card:: |settings| **Settings**
      :link: Settings/index
      :link-type: doc
      :text-align: left

      Configure core PBX options, integrations, and system preferences.

.. toctree::
  :maxdepth: 1
  :hidden:

  Introduction <Introduction/index.rst>
  Getting Started <Getting-started/index.rst>
  Call Flows <Call-flows/index.rst>
  Users <Users/index.rst>
  Contact Methods <Contact-methods/index.rst>
  Numbers <Numbers/index.rst>
  Time Schedules <Time-schedules/index.rst>
  Delivery Methods <Delivery-methods/index.rst>
  Audio Files <Audio-files/index.rst>
  Trunks <Trunks/index.rst>
  Call Analytics <Call-analytics/index.rst>
  Contacts <Contacts/index.rst>
  Settings <Settings/index.rst>
  Subscription Details <subscription-details/index.rst>
  phone.systems™ App <app/index.rst>

.. |audio-files| image:: /img/phone_systems/icons/icons-sidebar-audio-files.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |call-analytics| image:: /img/phone_systems/icons/icons-sidebar-call-analytics.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |contact-methods| image:: /img/phone_systems/icons/icons-sidebar-contact-methods.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |default| image:: /img/phone_systems/icons/icons-sidebar-default.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |delivery-methods| image:: /img/phone_systems/icons/icons-sidebar-delivery-methods.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |phone-numbers| image:: /img/phone_systems/icons/icons-sidebar-phone-numbers.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |settings| image:: /img/phone_systems/icons/icons-sidebar-settings.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |time-schedules| image:: /img/phone_systems/icons/icons-sidebar-time-schedules.svg
   :class: no-border inline-img no-shadow
   :width: 19px
   :height: 19px

.. |trunks| image:: /img/phone_systems/icons/icons-sidebar-trunks_v2.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |users| image:: /img/phone_systems/icons/icons-sidebar-users.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |contacts| image:: /img/phone_systems/icons/icons-sidebar-contacts.svg
   :class: no-border inline-img no-shadow
   :width: 19px
   :height: 19px


============
Introduction
============

phone.systems™ is a fully-featured, cloud-based virtual PBX that is specifically designed to interconnect with any service provider. There is no special hardware to purchase and maintain, and phone.systems™ is compatible with all landlines, mobile phones and computers, SIP devices and multi-line desktop phones. Multiple users, remote offices and telecommuters become part of a highly flexible, scalable and cost-effective phone system, supported by essential PBX services such as voice menus, voicemail to email, conferencing, time and caller routing, internal extensions and more

The user interface for phone.systems™ is specifically designed for simplicity and ease-of-use. No special training or expertise is required, and voice systems are instantaneously activated as call flows are configured via an intuitive, drag-and-drop graphical web interface.

phone.systems™ is applicable for both business and personal use, and configurations cover a wide range of applications from simple home use through to complex, multi-branch voice systems.

____

Feature List Overview
~~~~~~~~~~~~~~~~~~~~~

phone.systems™ includes the following features:

**PBX and call management**

-  **Internal numbers** - extension numbers that are directly accessible
   to system users.
-  **Ring groups** - redirect incoming external or internal calls to
   different destinations included in the ring group.
-  **Voice menus** - Interactive Voice
   Response (IVR) allows callers to listen to a recording and navigate to
   different destinations using their dial pad.
-  **Audio playback** - play customized audio messages to callers.
-  **Conference calling** - multiple callers can partake in a conference
   call.
-  **Voicemail** - a mailbox in which callers may leave voice messages,
   which are then sent to a specified email address, a file server or a
   third party cloud account.
-  **Call recording** - calls are recorded, including for SIP Account
   and External Line contact methods (if applicable), with the call
   contents being sent to a specified email address, a file server or a
   third party cloud account.
-  **Caller blocklist** - block incoming calls received from specific
   phone numbers.
-  **Call queuing** - place incoming calls in a queue before passing
   those calls to queue members.
-  **Time routing** - incoming calls are forwarded to different
   destinations, according to the day and time of the call.
-  **Caller routing** - incoming calls are forwarded to different
   destinations, depending on the originating phone number.
-  **Receive faxes** - Convert incoming faxes to PDF, with multiple file
   delivery options available.
-  **Event notifications** - users receive alerts via email when
   specified events occur.
-  **Configurable feature codes** - for accessing system functions such
   as call transfers and call pickup directly from the phone.
-  **Call forwarding options** - forward incoming calls to any phone
   number or VoIP destination.

**User interface, system management and special features**

-  **Graphical user interface** - call flows are configured via an
   easy-to-use, intuitive, drag-and-drop graphical web interface that is
   compatible with desktop computers, tablets and mobile devices.
-  **Remote management** - system management is achieved via a web-based
   interface, accessible from anywhere in the world.
-  **Instant activation** - voice configurations are instantaneously
   activated as they are graphically assembled, providing immediate
   access to the voice system.
-  **Contact Methods** - for managing contacts and contact
   methods used by phone.systems™.
-  **Audio files** - for uploading audio files, recording
   messages and managing playlists that are used by phone.systems™.
-  **Receive calls on one or many phone numbers** - add phone numbers
   used for inbound calling directly from the management interface.
-  **SIP trunk configuration** - Add and configure inbound and outbound SIP trunks directly from the phone.systems™ management dashboard.
-  **Call logs** - access to detailed call history, with optional date
   filters.
-  **Call statistics** - access to detailed call statistics and charts.
-  **Lost calls** - calls that were initiated but not successfully connected.
-  **Third-party compatibility** - the phone.systems™ platform is
   specifically designed to seamlessly interconnect with any
   SIP-standard compatible VoIP service provider, hardware or software.
-  **Integrated phone.systems™ SIP softphone** - optional iOS, Android,
   Windows and MacOS compatible softphone, including a secure management
   portal.


.. |br| raw:: html

    <br>

.. _ps3_getting_started:

===============
Getting Started
===============

This guide walks you through the essential steps to set up phone.systems™, a cloud-based virtual PBX. It helps you configure the system to make and receive calls quickly and efficiently.

phone.systems™ is ideal for managing inbound and outbound communications, routing calls through custom flows, and integrating multiple devices or applications. With a visual interface and advanced control features, it enables consistent and scalable telephony for teams of all sizes.

----

.. raw:: html

    <br>

.. _ps3_prerequisites:

Before You Begin
================

Before setting up phone.systems™, ensure you have the following:

    - **A DIDWW Account** – Required to access and manage services. If you don’t have one, `register here <https://my.didww.com/users/sign_up>`_.
    - **At Least One DID Number** – Required to set up call routing. To purchase a number, visit the `Coverage page <https://my.didww.com/#/coverage>`_.
    - **An Active phone.systems™ Subscription** – Required to launch and configure your PBX environment. If you haven’t subscribed yet, go to the `phone.systems™ page <https://my.didww.com/#/phone_systems>`_.

----

.. raw:: html

    <br>

.. _ps3_user_panel_config:

Assign phone.systems™ Trunk in the DIDWW User Panel
===================================================

To ensure calls are routed to your phone.systems™ PBX, assign the phone.systems™ trunk in the DIDWW User Panel to your DID numbers.

1. Go to **Phone Numbers > My Numbers** from the main menu.
2. In the **Trunk** column for your selected DID, click the current trunk name (**Voice: none** if none assigned).

.. figure:: https://doc.didww.com/_images/figure3.png
  :figclass: align-center
  :alt: Accessing the trunk assignment options for a DID.
  :width: 100%

  **Fig. 1.** Accessing the trunk assignment options for a DID.

3. In the **Update Voice IN Trunk** window, click the dropdown menu and select the **phone.systems** trunk.
4. Click **Confirm** to assign the trunk.

.. note::

   Repeat these steps for any other DID numbers you want to route through your **phone.systems™** PBX.

   If you want to assign the phone.systems™ trunk to multiple DID numbers at once, you can use batch actions. To learn more, see :ref:`Assign the trunk for multiple DID numbers <user_panel_assign_trunk_batch>`.

.. figure:: https://doc.didww.com/_images/figure3.1.png
  :figclass: align-center
  :alt: Selecting and confirming the phone.systems™ trunk for the DID.
  :width: 100%

  **Fig. 2.** Selecting and confirming the phone.systems™ trunk.

----

.. raw:: html

    <br>

.. _ps3_launch_and_configure:

Launch and Configure phone.systems™
===================================

After completing the configuration in the DIDWW User Panel, you can launch the **phone.systems™** platform to begin setting up your call flows, users, and devices.

Step 1: Launch the phone.systems™ Platform
------------------------------------------

1. In the DIDWW User Panel, go to **Cloud Phone System** from the main menu.
2. Make sure your phone.systems™ subscription is active.
3. Click **Launch** to open the phone.systems™ management interface in a new browser tab.

.. figure:: https://doc.didww.com/_images/figure4.png
  :figclass: align-center
  :alt: Launching the phone.systems™ platform from the DIDWW User Panel.
  :width: 100%

  **Fig. 3.** Launching the phone.systems™ platform.

Step 2: Choose Your Configuration Method
----------------------------------------

Once inside the phone.systems™ interface, you'll need to configure how you want to receive incoming calls and make outbound calls. Choose one of the following options to continue your setup:

.. raw:: html

   <br>

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **phone.systems™ app**
      :link: ps3_getting_started_app
      :link-type: ref
      :text-align: center

      Configure your account using the dedicated phone.systems™ application (recommended for ease of use).

   .. grid-item-card:: **Third-party Softphone**
      :link: ps3_getting_started_softphone
      :link-type: ref
      :text-align: center

      Set up a SIP account within phone.systems™ and configure it on a compatible third-party softphone or device.

.. raw:: html

   <br>

.. toctree::
  :maxdepth: 1
  :hidden:

  phone.systems™ application line <app.rst>
  Third-party softphone <third_party_softphone.rst>



.. |br| raw:: html

    <br>

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. _ps3_getting_started_app:

phone.systems™ App Configuration
==========================================

The phone.systems™ mobile application allows users to make and receive calls
directly from their device using your configured phone.systems™ setup.

This section explains how the app connects to a user account and application
line, so calls can be handled through the platform instead of a traditional
phone system. Once the user is configured, you can activate the app and complete the setup
on their device.

----

.. raw:: html

    <br>

Configure User and Application Line in phone.systems™
--------------------------------------------------------

The phone.systems™ app can be activated on a device, a user account
and application line must be configured in the phone.systems™ interface.
This ensures the user has a dedicated calling setup for handling inbound and
outbound calls through the platform.

Step 1: Create a New User
^^^^^^^^^^^^^^^^^^^^^^^^^

Follow these steps to create a new user:

1. Navigate to the **Users** menu in the phone.systems™ interface.
2. Click the |+-symbol| symbol and select **Create new**.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Create A New User
  :width: 80%

  **Fig. 1.** Create A New User

3. In the **Create User** form, fill in the user details: **First Name**, **Last Name**, **Department**, **Job Title**, and **Email**.

.. note::
   The **Email** field is mandatory. The user will receive an invitation email at this address, which is required to activate the phone.systems™ application.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :alt: Create User page details.
  :width: 25%

  **Fig. 2.** Create User page details.

Step 2: Configure Application Line Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Immediately after filling in the user details, configure their application line:

1. Ensure the toggle switch labeled **Configure application line in the next step** is enabled.
2. Click **Next**.

.. figure:: https://doc.didww.com/_images/fig11.png
  :figclass: align-center
  :width: 30%
  :alt: Configure Application Line Toggle switch.

  **Fig. 3.** Configure Application Line Toggle switch.

3. You will be presented with the **Edit App Configuration** form. Configure the settings for **Inbound Calls**, **Outbound Calls**, and **Call Recording**.

   Assign a specific DID number for incoming calls, allow external outgoing calls, and set the caller ID to enable inbound and outbound calling:

        .. list-table::
           :widths: 20 80
           :header-rows: 1

           * - Field
             - Description
           * - **DID Number**
             - Select the DID number used to receive inbound calls.
           * - **Enable External Outbound Calls**
             - Specifies whether the user can make external outbound calls.
           * - **Caller IDs**
             - Specifies **one or multiple** caller IDs used for outbound calls.

4. After completing the configuration, click **Save**.

.. figure:: https://doc.didww.com/_images/fig9.png
     :figclass: align-center
     :alt: Application Line Configuration options example.
     :width: 80%

     **Fig. 4.** Application Line Configuration options example.

----

Install and Activate the phone.systems™ App
-------------------------------------------

After a user account and their application line have been configured in
phone.systems™, the system automatically sends an invitation email to the
user’s registered email address.
This email allows the user to install the phone.systems™ mobile application
and securely connect it to their assigned application line.

The invitation email provides:

- A download link for the mobile application
- Activation details (QR code and authentication code) required to connect
  the app to the configured app

The user must follow the instructions in the email to complete the installation
and activation process on their device.

.. note::

   If the invitation email does not arrive, check the spam or junk folder,
   or contact your administrator to resend the invitation.

.. figure:: https://doc.didww.com/_images/activation_email.png
   :figclass: align-center
   :width: 30%
   :alt: phone.systems invitation email

   **Fig. 5.** Invitation email

Step 1: Install the App and Sign In
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Download the application using the links in the email if necessary, then open the installed **phone.systems™ application**.
2. On the sign-in screen, tap **Sign in**.

.. figure:: https://doc.didww.com/_images/sign_in.png
   :figclass: align-center
   :width: 30%
   :alt: Sign-in screen

   **Fig. 6.** Sign-in screen

Step 2: Activate the phone.systems™ App
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Activate the application using one of the following methods provided in the invitation email.

When activating using a QR code, the application may request camera access to scan the code.

.. note:: When activating using a QR code, the application may request camera access to scan the code.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Scan QR Code*

      1. Allow camera access when prompted.
      2. Scan the QR code from the invitation email.

      .. figure:: https://doc.didww.com/_images/qr_scan.png
         :figclass: align-center
         :width: 30%
         :alt: QR code activation

         **Fig. 7.** QR code activation

   .. tab-item:: *Enter Code Manually*

      If camera access is denied or unavailable, activate the application using the authentication code from the invitation email.

      1. Tap **Enter code manually** on the QR scanning screen.
      2. Copy the authentication code from the invitation email.
      3. Paste the code into the **Enter authentication code** field.
      4. Tap **Continue** to proceed.

      .. grid:: 1 1 1 2
         :gutter: 3

         .. grid-item::

            .. figure:: https://doc.didww.com/_images/manual_code.png
               :width: 100%
               :figclass: align-center
               :alt: Camera permission denied screen

               **Fig. 8.** Camera permission denied screen

         .. grid-item::

            .. figure:: https://doc.didww.com/_images/enter_code.png
               :width: 100%
               :figclass: align-center
               :alt: Enter authentication code screen

               **Fig. 9.** Enter authentication code screen

Step 3: Grant Required Permissions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After activation, the **Welcome to phone.systems™** screen is displayed. Tap
**Continue** to proceed.

On the next screen, tap **Setup permissions** to allow the required device
permissions for calling.

Allow the following permissions:

- **Microphone access** – Required to make and receive calls.
- **Push notifications** – Required to receive incoming call alerts and notifications.

.. note::
   - If microphone or push notification permissions are denied, the application may not be able to place or receive calls properly. Permissions can be modified later in the device system settings.
   - On **iPhone**, **Focus** mode may silence calls and notifications. If you are
     not receiving incoming call alerts, make sure Focus mode is disabled or
     that phone.systems™ is allowed in your Focus settings.

     See Apple’s documentation:
     `Set up a Focus on iPhone <https://support.apple.com/guide/iphone/set-up-a-focus-iphd6288a67f/ios>`_
     and
     `Allow or silence notifications for a Focus <https://support.apple.com/guide/iphone/allow-or-silence-notifications-for-a-focus-iph21d43af5b/ios>`_.

.. grid:: 1 1 1 2
   :gutter: 3

   .. grid-item::

      .. figure:: https://doc.didww.com/_images/continue.png
         :width: 100%
         :figclass: align-center
         :alt: Welcome screen with Continue button

         **Fig. 10.** Welcome screen

   .. grid-item::

      .. figure:: https://doc.didww.com/_images/setup_permissions.png
         :width: 100%
         :figclass: align-center
         :alt: Setup permissions screen

         **Fig. 11.** Permissions setup screen

Step 4: Review and Confirm Profile Details
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After granting the required permissions, you will be prompted to review and confirm your profile information.

1. Enter or verify your profile details, such as your name, job title, and department.
2. Tap **Save and continue** to complete the setup.

The phone.systems™ application is now activated and ready to make and receive calls.

.. figure:: https://doc.didww.com/_images/personal_information.png
   :figclass: align-center
   :width: 30%
   :alt: Personal information screen

   **Fig. 12.** Personal information

.. |br| raw:: html

    <br>

.. _ps3_getting_started_softphone:

Third-Party Softphone Configuration
===================================

This guide explains how to configure phone.systems™ to work with a third-party softphone or SIP device. It covers creating the necessary user and SIP account within phone.systems™, retrieving the credentials, and provides an example of setting up the popular Zoiper5 softphone.

----

.. raw:: html

    <br>

Configure User and SIP Account in phone.systems™
--------------------------------------------------

First, you need to set up a user and a dedicated SIP account within the phone.systems™ management interface. This process generates the credentials required by your third-party softphone.

Step 1: Create a New User
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Follow these steps to add a new user profile:

    1. Navigate to the **Users** menu in the phone.systems™ interface.
    2. Click the |+-symbol| symbol and select **Create new**.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Create A New User button location.
  :width: 80%

  **Fig. 1.** Create a New User.

..

    3. Fill in the user details (**First Name**, **Last Name**, **Email**, etc.).
    4. Click **Save** to create the new user.

.. tip:: When configuring a user solely for a third-party softphone, you can skip the application line configuration step that might appear (the toggle shown in the application setup guide is not needed here).

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :width: 25%
  :alt: Create User Form fields.

  **Fig. 2.** Create User Form.

Step 2: Create and Configure a SIP Account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Next, create the SIP account that will be linked to this user:

    1. Navigate to the **Contact Methods** menu.
    2. Select the **SIP Accounts** tab.
    3. Click the |+-symbol| symbol to create a new SIP account.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :alt: Create SIP Account button location.
  :width: 80%

  **Fig. 3.** Create SIP Account Button.

..

    4. In the **General** section of the new SIP account form, select the **User** you just created from the dropdown menu.

    5. In the **Inbound calls** section, select the **DID Number** that should route calls to this SIP account.

    6. In the **Outbound calls** section:
        * Check the **Enable external outbound calls** box.
        * Choose the desired **Caller ID(s)** from the dropdown.
    7. Click **Save** to create the SIP account.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :alt: Create SIP Account.

  **Fig. 4.** SIP Account Configuration.

Step 3: Retrieve SIP Credentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now, retrieve the credentials needed for your softphone:

    1. In the **SIP Accounts** list (**Contact Methods > SIP Accounts**), locate the SIP account you just created.
    2. Click the |...action_button| actions button next to it and select **Edit**.
    3. In the **General** section of the configuration window, find the SIP credentials: **Username**, **Password**, and **Domain**.
    4. Copy these details securely. You will need them to configure your third-party softphone.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :alt: Location of SIP Account Credentials (Username, Password, Domain).

  **Fig. 5.** SIP Account Credentials.

----

.. raw:: html

    <br>

Configure Your Third-Party Softphone
--------------------------------------

With the SIP credentials obtained, you can now configure your chosen third-party softphone, VoIP device, or system. These applications use the SIP protocol to register with phone.systems™ and handle calls.

.. note::
   - **Incoming Calls**: Your softphone *must* successfully register using the provided SIP credentials to receive incoming calls.
   - **Outbound Calls**: SIP registration is recommended for outbound calls but not strictly mandatory. Outbound calls can sometimes be made via a direct SIP INVITE if authentication is handled correctly within the request, but registration is the standard method.

Zoiper5
-------

The following steps illustrate how to configure the Zoiper5 softphone using the credentials retrieved earlier. Steps for other softphones will be similar.

    1. Download Zoiper5 from the `Zoiper website <https://www.zoiper.com/en/voip-softphone/download/current>`_ and install it on your device.
    2. Launch Zoiper5. You will likely be prompted to log in or create an account. Enter the **Username** and **Password** you copied from phone.systems™. Click **Login** to proceed.

    .. figure:: https://doc.didww.com/_images/fig1.png
      :figclass: align-center
      :alt: Zoiper5 login screen with Username and Password fields.
      :width: 50%

      **Fig. 6.** Zoiper5 Login - entering SIP credentials.

    3. Enter the **Domain** ``sip.phone.systems`` and click **Next** to proceed.

    .. figure:: https://doc.didww.com/_images/fig2.png
      :figclass: align-center
      :alt: Zoiper5 domain entry screen.
      :width: 50%

      **Fig. 7.** Zoiper5 - Enter Domain.

    4. Zoiper might present optional settings like Authentication Username or Outbound Proxy. These are typically not required for phone.systems™. Click **Skip** to proceed without entering them.

    .. figure:: https://doc.didww.com/_images/fig3.png
      :figclass: align-center
      :alt: Zoiper5 optional Authentication and Outbound Proxy screen.
      :width: 50%

      **Fig. 8.** Zoiper5 - Skip Optional Settings.

    5. Zoiper will test connection methods (e.g., SIP UDP, SIP TCP). Ensure at least one compatible method is found (phone.systems™ supports both SIP UDP and SIP TCP). Click **Next**.

       .. note::
          While phone.systems™ also supports secure TLS transport protocol, it is not enabled by default and is only available in the paid Zoiper5 PRO version.

    .. figure:: https://doc.didww.com/_images/fig4.png
      :figclass: align-center
      :alt: Zoiper5 transport protocol verification screen.
      :width: 50%

      **Fig. 9.** Zoiper5 - Verify Transport Protocol.

    6. Verify the SIP account connection. Press **X** to close the window, complete the setup, and return to the main screen.

       .. note::
          A successful connection is typically indicated by a green status icon next to the account name or URI (e.g., ``username@sip.phone.systems``).

    .. figure:: https://doc.didww.com/_images/fig5.png
      :figclass: align-center
      :alt: Zoiper5 accounts list showing a successfully configured account.
      :width: 50%

      **Fig. 10.** Zoiper5 - Account successfully configured.

    7. From the main Zoiper5 screen, locate and tap the **dialer icon** or equivalent to open the dial pad. Your SIP account is now registered, and you should be able to make and receive calls.

    .. figure:: https://doc.didww.com/_images/fig6.png
      :figclass: align-center
      :alt: Zoiper5 main screen with dialer icon highlighted.
      :width: 50%

      **Fig. 12.** Zoiper5 - Open Dial Pad.

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |...action_button| image:: ../assets/img/guide-v2/contact_methods/three_dots_action_button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. _ps3_call_flows_index:

==========
Call Flows
==========

This section provides a comprehensive guide to configuring and managing call flows within the system. Whether you're setting up the control panel, configuring objects, or navigating through tabs and multiple pages, you'll find detailed instructions and examples to streamline your process. Additionally, this section covers the configuration of softphones, ensuring that your communication setup is optimized for efficient call handling. Explore the following topics to gain a deeper understanding of each aspect of call flow management.

----

.. grid:: 1 1 3 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`device-desktop` **Control Panel**
      :link: control-panel
      :link-type: doc
      :text-align: left

      Learn how to navigate and manage the control panel for phone.systems™ administration.

   .. grid-item-card:: :octicon:`gear` **Object Configuration**
      :link: Object-configuration
      :link-type: doc
      :text-align: left

      Configure and manage objects to customize your PBX setup.

   .. grid-item-card:: :octicon:`browser` **Tabs and Multiple Pages**
      :link: tabs-and-multiple-pages
      :link-type: doc
      :text-align: left

      Utilize tabs and multiple pages to organize your workspace efficiently.

   .. grid-item-card:: :octicon:`book` **Usage Examples**
      :link: usage-examples
      :link-type: doc
      :text-align: left

      Explore examples to better understand and implement phone.systems™ features.

   .. grid-item-card:: :octicon:`device-mobile` **Configuring Softphones**
      :link: configuring-softphones
      :link-type: doc
      :text-align: left

      Set up and configure softphones for seamless call handling.

.. toctree::
  :maxdepth: 1
  :hidden:

  Control Panel <control-panel.rst>
  Object Configuration <Object-configuration.rst>
  Tabs and Multiple Pages <tabs-and-multiple-pages.rst>
  Usage Examples <usage-examples.rst>
  Configuring Softphones <configuring-softphones.rst>


.. |br| raw:: html

   <br />

.. _ps3_control_panel:

=============
Control Panel
=============

phone.systems™ is quickly and easily configured via a graphical web
interface, with drag-and-drop objects being connected together to define
the call flows and the functionality of the PBX.

The components used in building phone.systems™ applications are as
follows:

-  **Object** - there are a number of different objects, with each
   object performing a specified PBX function such as voicemail, time
   routing or conferencing.
-  **Object Menu** - a menu listing the various objects that are used in
   building the call flow.
-  **Feature Menu** - a menu listing options for managing important
   supplementary phone.systems™ components such as phone numbers,
   internal numbers, contacts, media, inbound and outbound trunks, file
   delivery methods, feature codes and for accessing call
   logs.
-  **Call Flows** - an area where you may separate your PBX configurations based on recipients, for example - sales, support, etc.
-  **Workspace** - an area where the objects are placed and the call
   flows assembled.
-  **Workspace Tab Menu** - for displaying different pages of the PBX
   workspace.
-  **Trash Bin** - for removing objects from the workspace.
-  **Cables** - used to logically connect objects together to define
   call flows.

The phone.systems™ configuration screen consists of the following main
components: the **Feature Menu** where all of the phone.systems™ features can be found, the center **Workspace** where the PBX logic is assembled,
the **Object Menu** on the right-hand side of the screen, the
**Workspace Tab Menu** along the top of the screen, and **Trash Bin**
(when activated) in the lower right-hand corner.

Additionally, this screen includes options for managing and editing call flows.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: phone.systems™ Layout
  :width: 80%

  **Fig. 1.** phone.systems™ Layout

----

.. _ps3_call_flows:

Call Flows
^^^^^^^^^^^

Call Flows are used to differentiate the recipients for calls and specific configurations.

In most cases, **call flows** should be created based on the organizations departments, such as **Sales**, **Support**, **Billing**, and others.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Call Flows Tab
  :width: 80%

  **Fig. 1.** Call Flows Tab

Create Call Flows
'''''''''''''''''

To create a new call flow, click on the |+-symbol| on the bottom right of the screen.

You will be taken to the new call flow creation screen, where you need to:

1. Select a **Name** for the call flow.
2. Add **Users**.

Finally, click **Save** to create the call flow.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :alt: Creating Call Flows

  **Fig. 2.** Creating Call Flows

If you have multiple call flows and would like to navigate between them quickly, click the call flow name at the top of the UI. This will reveal shortcuts for all your available call flows.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :alt: Switching Between Call Flows
  :width: 80%

  **Fig. 3.** Switching Between Call Flows

.. _ps3_call_flows_editing:

Edit Call Flows
'''''''''''''''

To edit an existing call flow, click the |actions| button and select **Edit**.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :alt: Edit Actions Button
  :width: 80%

  **Fig. 4.** Edit Actions Button

Make the necessary changes and click **Save** to update your call flow.

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center
  :alt: Editing a Call Flow

  **Fig. 5.** Editing a Call Flow

Delete Call Flows
'''''''''''''''''

To delete an exiting call flow, click on the |actions| button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center
  :alt: Delete Actions Button
  :width: 80%

  **Fig. 6.** Delete Actions Button

.. warning:: Please note that once deleted, it will not be possible to restore the call flow. All associated data and settings will be lost.

Then, click the **Delete** button to confirm the deletion of the call flow.

.. figure:: https://doc.didww.com/_images/fig10.png
  :figclass: align-center
  :alt: Deleting a Call Flow
  :width: 30%

  **Fig. 7.** Deleting a Call Flow

.. _ps3_control_panel_manage_users:

Manage Users for existing Call Flows
''''''''''''''''''''''''''''''''''''

To add or remove users from your existing call flows, follow these steps:

1. :ref:`Edit <ps3_call_flows_editing>` the existing call flow.

To edit an existing call flow, click the |actions| button and select **Edit**.

.. figure:: https://doc.didww.com/_images/fig20.png
  :figclass: align-center
  :alt: Actions button
  :width: 80%

  **Fig. 8.** Actions button

2. Add or remove users from the call flow.

  - Add users by clicking **Add user** button and selecting the user from the dropdown menu. |br|
  - Remove users by clicking the |x-symbol| button.

3. Save the call flow.

.. figure:: https://doc.didww.com/_images/fig21.png
  :figclass: align-center
  :alt: Managing Users
  :width: 45%

  **Fig. 9.** Managing Users

----

Workspace
^^^^^^^^^

The workspace is used to assemble call flows. Objects are dragged from the **Object Menu** onto the workspace, configured, and then logically connected via **cables** to build the required voice system.

To select an object, position the mouse over the required object in the
menu. Drag that object from the menu over the workspace, and release it
where required.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 1.** Object On The Workplace

Once objects are positioned on the workspace, a configuration
dialog box will be automatically opened on the right-hand side of the
workspace. All required fields must be completed, and then the object is
saved onto the workspace by pressing the **Save** button.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 2.** Saving The Object

Objects positioned on the workspace may be dragged and
repositioned as needed.

----

.. _ps3_workspace_tab_menu:

Workspace Tab Menu
^^^^^^^^^^^^^^^^^^

phone.systems™ allows the user to segment a voice system into logical
groups and functions that may be arranged over multiple workspace pages.
This feature is very useful when building complex voice systems, such as
a PBX for a multi-branch business. The various workspace pages are
accessed via the tabs on the **Workspace Tab Menu**, and tabs may be
added, deleted or repositioned as required. In addition, the tabs may be
labeled so as to define the functionality of each workspace page. Note
that when phone.systems™ is initially activated, there is a single tab
denoted as **Default**. This tab may be renamed, but cannot be deleted
unless at least one additional tab has been added to the workspace.

A new workspace page may be added by clicking on the |cpimg5| icon at
the top right-hand edge of the **Workspace Tab Menu**.

.. figure:: https://doc.didww.com/_images/fig11.png
  :figclass: align-center

  **Fig. 1.** New Tab

A window is opened in which the name of the new tab must be entered, and
the Tab Menu is updated by clicking on the **Save** button.

.. figure:: https://doc.didww.com/_images/fig12.png
  :figclass: align-center
  :width: 35%

  **Fig. 2.** Creating A New Tab

A new, blank workspace is created, and is accessed by selecting the
|cpimg9| tab.

.. figure:: https://doc.didww.com/_images/fig13.png
  :figclass: align-center

  **Fig. 3.** Newly created Tab

Placing the mouse over a tab name displays |cpimg11| icon. The name of
the tab may be changed by clicking on the icon, which opens a tab
configuration window. Note that a tab and its associated workspace page
may deleted by clicking on the |cpimg12|, even if there are
phone.systems™ objects on that page. Therefore, added care must be taken
when deleting tabs.

.. figure:: https://doc.didww.com/_images/fig14.png
  :figclass: align-center
  :width: 26%

  **Fig. 4.** Editing A Tab

Tab positions may be changed within the **Workspace Tab Menu** by
"dragging" tags horizontally along the tag listing bar.

More information regarding the usage of multiple workspaces is detailed
in the section :ref:`Tabs and Multiple Pages <ps3_tabs_and_multiple_pages>`.

----

Search
^^^^^^

The search tool is used to find related phone.systems™ resources with a
single search request. It is effectively a combination of the existing
search capabilities, with the addition of the ability to search for
associated objects, contacts, delivery methods and phone numbers.

To begin the search, click on the |magn| icon in the Workspace tab menu
to activate the search window.

.. figure:: https://doc.didww.com/_images/fig15.png
  :figclass: align-center

  **Fig. 1.** Search Tool

In the search field, type in the name of the resource to be located and
click the **Search** button. Once the search has been completed, all
results will be displayed and grouped by resource type.

.. figure:: https://doc.didww.com/_images/fig16.png
  :figclass: align-center

  **Fig. 2.** Searching A Name

The |cpimg17| and |cpimg18| buttons allow you to locate the object on the workspace or access the resource's settings window.

----

Feature Menu
^^^^^^^^^^^^

The **Feature Menu** is accessed on the left side of the phone.systems™ UI.

.. figure:: https://doc.didww.com/_images/fig17.png
  :figclass: align-center

  **Fig. 1.** Feature Menu

The options for the **Feature Menu** are:

:ref:`Call Flows <ps3_call_flows>` - Used to differentiate the recipients for calls and specific configurations. In most cases, call flows should be organized by department, such as **Sales**, **Supports**, **Billing**, and others.

:ref:`Users <ps3_users>` - The **Users** menu allows you to manage users and app devices in phone.systems™ interface. This section includes tools for adding, modifying, and organizing user profiles and app devices essential for the PBX operation.

:ref:`Contact Methods <ps3_contact_methods>` - Provides information on configuring contact methods in the system. This includes managing application settings, SIP accounts, routing PSTN calls, setting up SIP forwarding, and configuring email settings. Each topic outlines the necessary steps for proper setup and management.

:ref:`Numbers <ps3_numbers>` - Configure third-party and internal phone numbers for call handling within the phone.systems™.

:ref:`Time Schedules <ps3_time_schedules>` - Create time schedules, set exceptions for working hours, and select time zones.

:ref:`Delivery Methods <ps3_delivery_methods>`- Lists and configures methods used to deliver audio and text files generated by phone.systems™, such as voicemail and notifications. Delivery options include **Email**, **Dropbox**, **FTP**, **SFTP**, **Google Drive**, and **OneDrive**.

:ref:`Audio Files <ps3_audio_files>` - Used for general purposes like music-on-hold or for specific functions, such as directing callers in a Voice Menu object.

:ref:`Trunks <ps3_trunks_index>` - Configure inbound SIP trunks, routes and gateways for outbound SIP trunks to be used by phone.systems™.

:ref:`Settings <ps3_general_settings>` - The settings section provides an overview of the essential configurations that shape the functionality and behavior of your phone.systems™ PBX. Here, you can customize various parameters, manage feature codes, and access detailed technical information to optimize your phone.systems™ according to your specific requirements.

----

Object Menu
^^^^^^^^^^^

.. figure:: https://doc.didww.com/_images/fig18.png
  :figclass: align-center

  **Fig. 1.** Object Menu

The Object Menu serves as a listing of the various objects that may be
used in setting up the PBX. This menu may be minimized to create a
larger workspace by clicking on the |cpimg34| icon located at the bottom
right-hand corner of the workspace. When this menu is minimized, the
icon |cpimg35| is rotated to appear as |cpimg36|, and clicking on this
icon once again recovers the Object Menu.

----

Objects
^^^^^^^

There are a number of different objects, each performing a specific
function or set of functions. These objects may be arranged and
inter-connected in a wide variety of combinations, with calls being
passed from one object to another as required.

Objects are dragged from the Object Menu onto the workspace, and once an
object has been added to the workspace, it must be configured.
Configuration options for all objects are specified in the section :ref:`Object Configuration <ps3_object_configuration>`

Each object has either one or two sockets which are shown as small
protrusions on the left and/or right-hand sides of the object, and these
sockets are used for connecting the objects together via cables. The
left-hand socket acts as the input to an object, while the right-hand
socket acts as the output from that object

.. figure:: https://doc.didww.com/_images/objects.jpg
  :figclass: align-center

  **Fig. 1.** Objects

Duplicating objects
'''''''''''''''''''

phone.systems™ includes the ability for users to duplicate objects on
the workspace. All configuration parameters in the original object are
copied to the new object, however the name of the new object is modified
to include a copy number. For example, the first duplication of a **Voice
Menu** object named “Voicemail” will be named “Voicemail Copy 1”.

To use this copy feature:

-  For **MacOS**, hold down the **Option** key when dragging an object.

-  For **Windows**, hold down the **Ctrl** key when dragging an object.

.. figure:: https://doc.didww.com/_images/copy-object.gif
  :figclass: align-center

  **Fig. 2.** Duplicating Objects

It is important to note that not all objects may be duplicated. For
example, Phone Number and Internal Number objects are assigned unique
phone/internal numbers and may therefore not be copied.

Selecting and moving multiple objects
'''''''''''''''''''''''''''''''''''''

phone.systems™ allows users to select multiple objects and reposition
them simultaneously on the workspace, or move all of the selected
objects to another tab. Once an object has been selected, it will be
marked with a blue border.

To use the object selection feature:

-  **MacOS** - hold the \ **Command**\  key to select individual objects

-  **MacOS** - hold the \ **Shift**\   to select a complete object tree
   (objects connected by cables)

-  **Windows** - hold the \ **Ctrl**\   key to select individual objects

-  **Windows** - hold the \ **Shift**\   to select a complete object tree
   (objects connected by the cables)

.. figure:: https://doc.didww.com/_images/object-multiselection.gif
  :figclass: align-center

  **Fig. 3.** Selecting And Moving Objects

Use the same keys as listed above to deselect objects, or to exclude
particular objects from the object tree selection. Clicking on an empty
area on the workspace will deselect all previously selected objects or
object trees. Additionally, selected object trees may be moved to the
**Trash Bin**.

----

Cables
^^^^^^

Cables are used to logically interconnect the objects that have been
placed in the workspace area, thereby defining the call flows and the
functionality of the PBX.

To create a cable, place the mouse over the right-hand socket of an
object, and use the mouse to "drag" a cable from that socket towards the
left-hand socket of the destination object.

.. figure:: https://doc.didww.com/_images/cables-1.jpg
  :figclass: align-center

  **Fig. 1.** Dragging The Cable

Once the end of the cable is over the left-hand socket of the
destination object, release the cable and the two objects will be
logically connected as required.

.. figure:: https://doc.didww.com/_images/cables-2.jpg
  :figclass: align-center

  **Fig. 2.** Connecting The Cable

.. note:: phone.systems™ includes an intelligent cabling configuration assistant that simplifies the connection logic between objects by highlighting possible cable attachment points. In the figure below, after a cable is generated from the **Phone Number** object, valid input connection options are shown by available objects with their left-hand sockets highlighted in blue. The cable can be connected to any of these sockets.

.. figure:: https://doc.didww.com/_images/cables-3.jpg
  :figclass: align-center

  **Fig. 3.** Connection Options

To remove a cable and logically disconnect two objects, place the mouse
pointer over that cable until the "delete cable" icon |cpimg43| appears.
Click on that icon to complete the removal of the cable.

.. figure:: https://doc.didww.com/_images/cables-4.jpg
  :figclass: align-center

  **Fig. 4.** Delete Cable Icon

A “Delete Connection” window will appear, displaying the details of the
object connection to be terminated. To complete the action, click the
“Delete Anyway” button, or select the "Cancel" button to leave the
connection unchanged.

.. figure:: https://doc.didww.com/_images/fig19.png
  :figclass: align-center

  **Fig. 5.** Deleting Connections

In some cases, multiple cables, each having a distinct logical function,
may be generated from the exit (right-hand) socket of an object, and
these cables are connected to various objects as required by the call
flow. For example, when configuring a voice menu, there are three
different logical options for the cables that are generated from the
right-hand side of this object:

-  Calls are forwarded to objects according to the extension number
   entered by the caller.

-  Calls are forwarded to a specific object if the caller enters an
   invalid extension number.

-  Calls are forwarded to a specific object if the caller does not enter
   an extension number within a defined timeout period.

When a variety of logical functional options may be assigned to a single
cable, then once the cable has been connected between two objects, a
configuration window is automatically displayed that allows the user to
select the required function for that cable.

The screenshot below illustrates the functionality of multiple cables
exiting a **Voice Menu** object. After the voice message has been played
to the caller, if the caller presses “100” then the call will be
forwarded to the sales ring group, and if “200” is pressed, then the
call will be forwarded to the support ring group. Invalid extension and
timeout conditions (denoted as i and t respectively on the cables) are
forwarded to specified **Audio Playback** objects where appropriate
messages are played to the caller.

.. figure:: https://doc.didww.com/_images/cables-5.jpg
  :figclass: align-center

  **Fig. 6.** Multiple Connections

Note that the allocated extension numbers may be changed by clicking on
the configured number displayed on the cable. A configuration dialog
window is opened, and a new extension number may be entered.

Similarly, some objects, such as **Time Router** or **Caller Router**,
have two right hand (exit) sockets, which are used to implement a
“Yes/No” call flow logic. For example, for a **Time Routing** object, a
cable generated from the “Yes” (green) socket defines the routing of
calls if those calls are received within the configured day/time
interval, and the “No” (red socket) option defines routing in the case
of a time period match failure.

In the illustration below using a **Time Router** object, if the
incoming call is received within the configured day/time parameters,
then the call will be forwarded to Sales. Otherwise, the call will be
forwarded to an **Audio Playback** object where a pre-recorded
"after-hours" message is played to the caller.

.. figure:: https://doc.didww.com/_images/cables-6.jpg
  :figclass: align-center

  **Fig. 7.** Time Router Object Connections

It is important to note that if a cable is not connected from the
left-hand (output) socket of an object to the right-hand (input) socket
of another object, then a call will be terminated if the PBX logic
attempts to pass that call to adjacent objects. For example, in the
illustration below, an incoming call is forwarded to an **Audio
Playback** object where a message is played to the caller. Because the
right-hand side of the **Audio Playback** object does not have a cable
connected to another object, the call will be terminated as soon as that
message has been played.

.. figure:: https://doc.didww.com/_images/cables-7.jpg
  :figclass: align-center

  **Fig. 8.** Audio Playback Object Connections

----

Trash Bin
^^^^^^^^^

The Trash Bin allows the user to delete objects that have been
previously placed on the workspace. To delete an object, drag that
object towards the |cpimg50| or |cpimg51| icon at the bottom right-hand
corner of the workspace. This icon will be replaced by the Trash Bin
icon |cpimg52|, and the object to be deleted should be dragged and
dropped over the Trash Bin.

Note that the Trash Bin does not have a recycling facility, and trashed
items may not be recovered.

----

.. |cpimg1| image:: ../assets/img/guide-v2/control-panel/initial-screen.png
   :class: guide-img
.. |cpimg2| image:: ../assets/img/guide-v2/control-panel/workspace.jpg
   :class: guide-img
.. |cpimg3| image:: ../assets/img/guide-v2/inline-img/save-button.jpg
   :class: inline-long-img
.. |cpimg4| image:: ../assets/img/guide-v2/control-panel/configuration-box-save.jpg
   :class: guide-img
.. |cpimg5| image:: ../assets/img/guide-v2/inline-img/add-tab-button.jpg
   :class: no-shadow no-lightbox inline-settings-img
.. |cpimg6| image:: ../assets/img/guide-v2/control-panel/add-tab-button-hover.jpg
   :class: guide-img
.. |cpimg7| image:: ../assets/img/guide-v2/inline-img/save-button.jpg
   :class: inline-long-img
.. |cpimg8| image:: ../assets/img/guide-v2/control-panel/creating-new-tab.jpg
   :class: guide-img guide-medium-img
.. |cpimg9| image:: ../assets/img/guide-v2/inline-img/new-tab.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg10| image:: ../assets/img/guide-v2/control-panel/tab-panel.jpg
   :class: guide-img guide-medium-img
.. |cpimg11| image:: ../assets/img/guide-v2/inline-img/tab-settings-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg12| image:: ../assets/img/guide-v2/inline-img/tab-delete-button.jpg
   :class: inline-long-img no-shadow no-lightbox
.. |cpimg13| image:: ../assets/img/guide-v2/control-panel/tab-settings-icon-loc.jpg
   :class: guide-img guide-medium-img no-shadow no-lightbox
.. |cpimg14| image:: ../assets/img/guide-v2/control-panel/workspace-search-button-hover.jpg
   :class: guide-img
.. |cpimg15| image:: ../assets/img/guide-v2/control-panel/workspace-search-results.jpg
   :class: guide-img guide-medium-img
.. |cpimg16| image:: ../assets/img/guide-v2/inline-img/expand-menu-icon.jpg
   :class: inline-img
.. |cpimg17| image:: ../assets/img/guide-v2/inline-img/locate-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg18| image:: ../assets/img/guide-v2/inline-img/settings-icon-light.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg19| image:: ../assets/img/guide-v2/inline-img/menu-icon.jpg
   :class: inline-img inline-settings-img
.. |cpimg20| image:: ../assets/img/guide-v2/control-panel/settings-menu.png
   :class: guide-img guide-medium-img
.. |cpimg21| image:: ../assets/img/guide-v2/control-panel/phone-numbers.jpg
   :class: inline-object-img
.. |cpimg22| image:: ../assets/img/guide-v2/control-panel/internal-numbers.jpg
   :class: inline-object-img
.. |cpimg23| image:: ../assets/img/guide-v2/control-panel/contact-center.jpg
   :class: inline-object-img
.. |cpimg24| image:: ../assets/img/guide-v2/control-panel/media-center.jpg
   :class: inline-object-img
.. |cpimg25| image:: ../assets/img/guide-v2/control-panel/delivery-methods.jpg
   :class: inline-object-img
.. |cpimg26| image:: ../assets/img/guide-v2/control-panel/call-logs.jpg
   :class: inline-object-img
.. |cpimg27| image:: ../assets/img/guide-v2/feature_codes/feature-codes-small.png
   :class: inline-object-img
.. |cpimg29| image:: ../assets/img/guide-v2/inbound_trunks/inbound-trunks-small.png
   :class: inline-object-img
.. |cpimg30| image:: ../assets/img/guide-v2/outbound_trunks/outbound-trunks-small.png
   :class: inline-object-img
.. |cpimg31| image:: ../assets/img/guide-v2/control-panel/general-settings.jpg
   :class: inline-object-img
.. |cpimg32| image:: ../assets/img/guide-v2/inline-img/cancel-icon.jpg
   :class: inline-img
.. |cpimg33| image:: ../assets/img/guide-v2/control-panel/object-menu.png
   :class: guide-img guide-medium-img
.. |cpimg34| image:: ../assets/img/guide-v2/inline-img/x-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg35| image:: ../assets/img/guide-v2/inline-img/x-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg36| image:: ../assets/img/guide-v2/inline-img/plus-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg37| image:: ../assets/img/guide-v2/control-panel/objects.jpg
   :class: guide-img guide-small-img
.. |cpimg38| image:: ../assets/img/guide-v2/control-panel/copy-object.gif
   :class: guide-img guide-small-img
.. |cpimg39| image:: ../assets/img/guide-v2/control-panel/object-multiselection.gif
   :class: guide-img guide-small-img
.. |cpimg40| image:: ../assets/img/guide-v2/control-panel/cables-1.jpg
   :class: guide-img guide-small-img
.. |cpimg41| image:: ../assets/img/guide-v2/control-panel/cables-2.jpg
   :class: guide-img guide-small-img
.. |cpimg42| image:: ../assets/img/guide-v2/control-panel/cables-3.jpg
   :class: guide-img guide-small-img
.. |cpimg43| image:: ../assets/img/guide-v2/inline-img/remove-cable-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg44| image:: ../assets/img/guide-v2/control-panel/cables-4.jpg
   :class: guide-img guide-small-img
.. |cpimg45| image:: ../assets/img/guide-v2/inline-img/cancel-icon.jpg
   :class: inline-img
.. |cpimg46| image:: ../assets/img/guide-v2/control-panel/cables-delete-connection_window.jpg
   :class: guide-img guide-medium-img
.. |cpimg47| image:: ../assets/img/guide-v2/control-panel/cables-5.jpg
   :class: guide-img guide-small-img
.. |cpimg48| image:: ../assets/img/guide-v2/control-panel/cables-6.jpg
   :class: guide-img guide-small-img
.. |cpimg49| image:: ../assets/img/guide-v2/control-panel/cables-7.jpg
   :class: guide-img guide-small-img
.. |cpimg50| image:: ../assets/img/guide-v2/inline-img/plus-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg51| image:: ../assets/img/guide-v2/inline-img/x-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg52| image:: ../assets/img/guide-v2/inline-img/trash-bin-icon.jpg
   :class: inline-img no-shadow no-lightbox
.. |cpimg53| image:: ../assets/img/guide-v2/inline-img/touchscreen-select-icon.jpg
   :class: inline-img
.. |cpimg54| image:: ../assets/img/guide-v2/inline-img/touchscreen-select-icon.jpg
   :class: inline-img
.. |cpimg55| image:: ../assets/img/guide-v2/inline-img/touchscreen-select-icon.jpg
   :class: inline-img
.. |cpimg56| image:: ../assets/img/guide-v2/control-panel/mobile-object-moving.gif
   :class: guide-img guide-small-gif-img
.. |cpimg57| image:: ../assets/img/guide-v2/inline-img/touchscreen-select-icon.jpg
   :class: inline-img
.. |cpimg58| image:: ../assets/img/guide-v2/control-panel/mobile-object-connecting-cables.gif
   :class: guide-img guide-small-gif-img
.. |cpimg59| image:: ../assets/img/guide-v2/inline-img/touchscreen-select-icon.jpg
   :class: inline-img
.. |cpimg60| image:: ../assets/img/guide-v2/inline-img/remove-cable-icon.jpg
   :class: inline-img
.. |cpimg61| image:: ../assets/img/guide-v2/control-panel/mobile-object-deleting-cables.gif
   :class: guide-img guide-small-gif-img
.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: no-shadow no-lightbox
   :width: 30px
   :height: 30px
.. |magn| image:: ../assets/img/guide-v2/inline-img/inline-magn.png
   :class: inline-img no-shadow no-lightbox
   :width: 30px
   :height: 30px
.. |actions| image:: /phone-systems/assets/img/guide-v2/workspace/actions.png
   :class: no-shadow no-lightbox
   :width: 40px
   :height: 20px
.. |x-symbol| image:: /phone-systems/assets/img/guide-v2/workspace/x-symbol.png
   :class: no-shadow no-lightbox
   :width: 30px
   :height: 30px

.. raw:: html

   <style>
        /* Fix image size */
        .custom-button5rem,
        .custom-button5rem img,
        .custom-button5rem a {
            width: 4.5rem !important;
        }

        .custom-button8rem,
        .custom-button8rem img,
        .custom-button8rem a {
            width: 8rem !important;
        }

        .no-lightbox50,
        .no-lightbox50 img,
        .no-lightbox50 a {
            width: 35px !important;
        }

        .no-lightbox110,
        .no-lightbox110 img,
        .no-lightbox110 a {
            width: 110px !important;
        }

   </style>



.. _ps3_object_configuration:

====================
Object Configuration
====================

Once an object has been dragged from the **Object Menu** and released onto
the workspace, a configuration dialog box is automatically opened. Each
object has a specific set of configuration requirements, and the object
will only be usable once the configuration has been successfully
completed and clicked the **Save** button.

If the user
chooses not to configure the object but instead clicks the **Cancel**
button, then that object will be removed from the workspace.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Configuring Objects

After configuring an object, clicking the object displays the selected configuration details. For example, clicking on the
**Conference** object expands that object, showing the required
participation PIN code.

.. figure:: https://doc.didww.com/_images/object-1.png
  :figclass: align-center

  **Fig. 2.** Created And Expanded Object

In addition, the configuration of an object may be modified by clicking
on the |objimg7| icon on the right-hand side of that object.

----

.. grid:: 1 1 3 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :fa:`phone` **Object: Phone Number**
      :link: objects/phone-number
      :link-type: doc

      Manage external phone numbers assigned to your phone.systems™ PBX.

   .. grid-item-card:: :fa:`user` **Object: Internal Number**
      :link: objects/internal-number
      :link-type: doc

      Configure internal extensions for users and departments.

   .. grid-item-card:: :fa:`users` **Object: Ring Group**
      :link: objects/ring-group
      :link-type: doc

      Set up ring groups to allow multiple phones to ring simultaneously.

   .. grid-item-card:: :fa:`list` **Object: Voice Menu**
      :link: objects/voice-menu
      :link-type: doc

      Create interactive voice menus (IVRs) for caller navigation.

   .. grid-item-card:: :fa:`volume-up` **Object: Audio Playback**
      :link: objects/audio-playback
      :link-type: doc

      Play pre-recorded audio files during calls.

   .. grid-item-card:: :fa:`comments` **Object: Conference**
      :link: objects/conference
      :link-type: doc

      Set up conference bridges for multi-party calls.

   .. grid-item-card:: :fa:`inbox` **Object: Voicemail**
      :link: objects/voicemail
      :link-type: doc

      Enable and manage voicemail boxes for users.

   .. grid-item-card:: :fa:`fax` **Object: Fax**
      :link: objects/fax
      :link-type: doc

      Send and receive faxes using integrated virtual fax services.

   .. grid-item-card:: :fa:`microphone` **Object: Call Recorder**
      :link: objects/call-recorder
      :link-type: doc

      Record calls for compliance and review.

   .. grid-item-card:: :fa:`random` **Object: Caller Router**
      :link: objects/caller-router
      :link-type: doc

      Route calls dynamically based on caller ID or input.

   .. grid-item-card:: :fa:`ban` **Object: Blocklist**
      :link: objects/blocklist
      :link-type: doc

      Block unwanted callers or specific numbers.

   .. grid-item-card:: :octicon:`stack` **Object: Queue**
      :link: objects/queue
      :link-type: doc

      Place callers in queues to be answered in order.

   .. grid-item-card:: :octicon:`clock` **Object: Time Router**
      :link: objects/time-router
      :link-type: doc

      Route calls based on specific time schedules.

   .. grid-item-card:: :fa:`bell` **Object: Notification**
      :link: objects/notification
      :link-type: doc

      Send call notifications or alerts for events.

   .. grid-item-card:: :fa:`share` **Object: Forwarding**
      :link: objects/forwarding
      :link-type: doc

      Forward calls automatically to specified numbers or destinations.

.. toctree::
  :maxdepth: 1
  :hidden:

  Object: Phone Number <objects/phone-number.rst>
  Object: Internal Number <objects/internal-number.rst>
  Object: Ring Group <objects/ring-group.rst>
  Object: Voice Menu <objects/voice-menu.rst>
  Object: Audio Playback <objects/audio-playback.rst>
  Object: Conference <objects/conference.rst>
  Object: Voicemail <objects/voicemail.rst>
  Object: Fax <objects/fax.rst>
  Object: Call Recorder <objects/call-recorder.rst>
  Object: Caller Router <objects/caller-router.rst>
  Object: Blocklist <objects/blocklist.rst>
  Object: Queue <objects/queue.rst>
  Object: Time Router <objects/time-router.rst>
  Object: Notification <objects/notification.rst>
  Object: Forwarding <objects/forwarding.rst>

.. |objimg7| image:: ../assets/img/guide-v2/inline-img/settings-icon.jpg
   :class: inline-img

.. raw:: html

    <style>

    img.inline-img.no-shadow.no-border {
        border-radius: 0px !important;
    }

        /* Make sure the parent container has a relative position if needed */
    .section-container {
      position: relative;
    }

    /* Light mode: show the SVG as a background element */
    html.light .styles_waves__tcfLl {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;    /* Adjust width as necessary */
      height: auto;   /* If needed you can set a fixed height */
      z-index: -1;    /* Place it behind all other content */
      pointer-events: none; /* Ensure it won't capture mouse events */
    }

    /* Dark mode: hide the SVG background */
    html.dark .styles_waves__tcfLl {
      display: none;
    }

        .styles_title__pmgeW {
            font-size: 64px;
            line-height: 76.8px;
            color: #023f7f
        }

      :root {
        /* LIGHT THEME */
        --sd-color-primary: #005fcc;
        --sd-color-card-background: var(--sd-color-card-background);
        --sd-color-card-text: #1e1e1e;
        --sd-color-card-border: #d1d5db;
        /* Shadow variable removed from use */

        --sy-c-border: #d1d5db;
        --sy-c-bold: #374151;
        --gray-1: #e5e7eb;
        --sd-gutter-x: 1rem;
        --sd-gutter-y: 1rem;
        --page-background: #ffffff;
      }

      [data-theme="dark"],
      html.dark {
        /* DARK THEME */
        --sd-color-card-background: #111111;
        --sd-color-card-text: #f9f9f9;
        /* No shadow is applied */

        --sy-c-border: #4b5563;
        --sy-c-bold: #fff;
        --page-background: #000000;
      }

      html, body {
        background-color: var(--page-background);
        color: var(--sd-color-card-text);
        transition: background-color 0.3s ease, color 0.3s ease;
      }

      /* This style mirrors your .sd-card and .sd-text-center rules without any box-shadow.
         It uses the theme colors and spacing, and includes a small hover scale effect */
      .surface {
        background-color: var(--sd-color-card-background);
        color: var(--sd-color-card-text);
        border: 1px solid var(--sd-color-card-border);
        border-radius: 15px;
        padding: var(--sd-gutter-y) var(--sd-gutter-x);
        transition: background-color 0.3s ease, color 0.3s ease, transform 0.15s ease-in-out;
        width: 100%;
        box-sizing: border-box;
      }

      .surface:hover {
        transform: scale(1.02);
      }

      /* Optional grid layout to display items in a row */
      .surface-grid {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: var(--sd-gutter-x);
        width: 100%;
      }

      @media (max-width: 991.98px) {
        .surface-grid {
          grid-template-columns: 1fr;
        }
      }

        /* Responsive Columns: Four */
    @media (min-width: 1728px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1532px) and (max-width: 1727.98px),
           (min-width: 992px) and (max-width: 1127.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1128px) and (max-width: 1531.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 24rem;
      }
    }

    @media (min-width: 768px) and (max-width: 991.98px),
           (min-width: 576px) and (max-width: 767.98px),
           (max-width: 575.98px) {
      .sd-row-cols-md-3 > *,
      .sd-row-cols-sm-3 > * {
        min-width: 100%;
      }
    }

    .sd-card-body {
        -ms-flex: 1 1 auto;
        flex: 1 1 auto;
        padding: 2rem 2rem 2rem 2rem;
    }

    .. .sd-row {
        margin-top: calc(var(--sd-gutter-y) * 3);
    }

    </style>



.. _ps3_object_phone_number:

.. raw:: html

   <br>

Object: Phone Number
^^^^^^^^^^^^^^^^^^^^

The **Phone Number** object is configured with a phone number on which
incoming calls are to be received.

.. figure:: https://doc.didww.com/_images/phone-number-object.jpg
  :figclass: align-center

  **Fig. 1.** Phone Number Object

The information to be entered for this object includes:

* **Name** of the **Phone Number** object, used to identify the number on the workspace. For example, "Toll-Free London."

  Newly created **Phone Number** objects are provided with default names in the format {Tab name} {Object type} {Object type count in current tab}, for example "Main Phone Number 3".

* The phone number, which may be selected from a list of unused phone numbers that were previously added via the :ref:`Phone Numbers <ps3_phone_numbers>` tab in the Numbers menu.

  Phone numbers are entered in E.164 format: <CountryCode> <City/AreaCode> <LocalNumber>. The country code is 1-3 digits long, while the length of the city/area code and local number may vary. For example:

   * 14169233346 for Toronto, Canada
   * 442034116446 for London, United Kingdom.

A phone number may only be allocated to a single **Phone Number** object, and may not be reused by other such objects.

.. note:: Phone numbers can be added or deleted in the **Numbers** menu under the :ref:`Phone Numbers <ps3_phone_numbers>` tab. This section allows you to manage the list of available phone numbers, which can then be assigned to specific **Phone Number** objects.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 2.** Phone Number Object Creation

----

CLI Rules
"""""""""

**CLI Rules** are used to override the Source **Caller Name**. This
functionality allows flexible Caller Name configurations and may be used
to differentiate SIP calls received from phone.systems™. **CLI Rules**
will help you to identify from which **Phone Number** object the call is
coming from.

Some CLI Rule examples:

**1. Changing Caller Name to Custom text:**

  * SRC Name Rewrite Rule: ``^(.*)$``
  * SRC Name Rewrite Result: ``Custom text``

**2. Add Custom text before the original Caller Name:**

  * SRC Name Rewrite Rule: ``^(.*)$``
  * SRC Name Rewrite Result: ``Custom text \1``

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :width: 35%

  **Fig. 3.** CLI Rules


.. _ps3_internal_number_object:

.. raw:: html

   <br>

Object: Internal Number
^^^^^^^^^^^^^^^^^^^^^^^

The **Internal Number** object is used for internal dialing as an
extension number. This facility allows users to call each other directly
and to reach selected objects (such as **Conference** and **Voice Menu**
objects) via internally-assigned extension numbers. Note that one
**Internal Number** object must be created for each internal extension
required, and extension numbers cannot be duplicated on multiple
**Internal Number** objects.

Internal numbers are optionally used as internal caller IDs by
SIP devices when making outbound calls to other extensions within the
phone.systems™ network.

.. figure:: https://doc.didww.com/_images/internal-number-object.jpg
  :figclass: align-center

  **Fig. 1.** Internal Number Object

The information to be entered for this object is:

-  The name of the **Internal Number** object, for example, "Sales Conf
   Extension".

   Newly created **Internal Number** objects are automatically assigned default names in the format `{Tab name} {Object type} {Object type count in current tab}`, such as "Main Internal Number 7."

-  **Internal Number (Extension Number)** This is the number used for internal dialing (1 to 4 digits). It can be selected from a list of unused internal numbers that were previously added in the :ref:`Internal Numbers <ps3_internal_numbers>` menu.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 2.** Internal Number Object Creation

A simple usage example of the **Internal Number** object is shown below,
where an internal extension number is dialed by phone.systems™ users to
access the company's conferencing facility.

.. figure:: https://doc.didww.com/_images/internal-number-example.jpg
  :figclass: align-center

  **Fig. 3.** Example


.. _ps3_object_ring_group:

.. raw:: html

   <br>

Object: Ring Group
^^^^^^^^^^^^^^^^^^

The **Ring Group** object redirects incoming external or internal calls
to different destinations included in the ring group. These
destinations consist of :ref:`Contact Methods <ps3_contact_methods>`, such as phone numbers
(landline or mobile) and VoIP connections that are configured for the
various **contacts** in the system.

Multiple contacts and contact methods may be included as call
destinations within a single **Ring Group** object, and the ring times
and ring sequences for the selected contacts/contact methods are fully
configurable. If the first contact/contact method is busy or remains
unanswered for the set time period, the call is passed to the next
device in the configured ring sequence, and so on through the list of
contact methods. Alternatively, all destinations in the ring group may
be configured to ring simultaneously.

.. note::

   By default, up to **10 destinations per customer account** can ring
   simultaneously. If more destinations are scheduled to ring at the same
   time, only the number allowed by the account's simultaneous ringing limit
   can be processed at once.

The contacts and their various contact methods to be used by **Ring
Group** and these contacts methods need to be pre-configured by using the
:ref:`Contact Methods <ps3_contact_methods>` tab

The Ring Group object includes the ability to configure playlists as
both "music-on-hold" and "ringback-tone", so that pre-recorded music,
messages, commercials or any other audio clips may be played to callers.

.. figure:: https://doc.didww.com/_images/ring-group-object.jpg
  :figclass: align-center
  :alt: Ring Group Object

  **Fig. 1.** Ring Group Object

----

.. raw:: html

    <br>

Ring Group Configuration
""""""""""""""""""""""""

The information to be entered for this object is:

-  The name of the **Ring Group** object, for example "Sales Ring
   Group".

-  Users, defining a ring destination or multiple ring destinations
   to which incoming calls will be forwarded. Each ring destination
   consists of a User and an associated contact method, must be pre-configured by using the :ref:`Contact Methods <ps3_contact_methods>` tab

Selecting "Add ring group destination" allows the user to add a ring destination from a
drop-down menu of pre-configured contacts and their associated contact
methods.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :alt: Contact Methods

  **Fig. 2.** Contact Methods

Once the ring destinations have been added to the **Ring Group** object,
the ring times and, if applicable, the ring sequences may be configured.
The ring times for each contact method are shown on a 60 second timeline
bar, and each contact method may be placed as required along the
timeline bar. This is achieved by positioning the mouse over the
selected contact method, and then "dragging" the contact method along
the timeline bar to the required position.

.. note:: At least one of the contact methods must have a ring time starting at the zero second mark.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: Users Tab

  **Fig. 3.** Users Tab

The ring start and end times for each contact method may be changed by
"stretching" or "shrinking" that contact method. To do this, place the
mouse over the left or right-hand edge of the contact method, and
re-size that contact method by "dragging" the mouse in a left or
right-hand direction as required.

.. note:: The position of the **Contact Methods** on the timeline bar are automatically adjusted to ensure that there are no time gaps between the end ring time of one contact method, and the start ring time of the next sequential contact method.

----

.. raw:: html

    <br>

Media Tab
"""""""""

The **Media** tab is used to include media as both "music-on-hold" and
"ringback tone" playlists. This allows pre-recorded music, messages,
commercials or any other audio clips to be played to callers before
their call is answered (ringback tone), or while an active call is put
on hold (music-on-hold).

In general, this audio file will have previously been uploaded from a local drive
or recorded, and stored in the phone.systems™ :ref:`Audio Files <ps3_audio_files>`. New files may be added to
the Audio Files by selecting the "Upload audio file" option.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :alt: Media Tab

  **Fig. 4.** Media Tab

----

.. raw:: html

    <br>

CLI Rules Tab
"""""""""""""

The **CLI Rules** are used to override the Source **Caller Name**. This
functionality allows flexible Caller Name configurations and may be used
to differentiate SIP calls received from phone.systems™. **CLI Rules**
will help you to identify from which **Ring Group** object the call is
coming from.

Some CLI Rule examples:

**1. Changing Caller Name to Custom text:**

  * SRC Name Rewrite Rule: ``^(.*)$``
  * SRC Name Rewrite Result: ``Custom text``

**2. Add Custom text before the original Caller Name:**

  * SRC Name Rewrite Rule: ``^(.*)$``
  * SRC Name Rewrite Result: ``Custom text \1``

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center
  :width: 35%
  :alt: CLI Rules Tab

  **Fig. 5.** CLI Rules Tab

The only cable exiting the **Ring Group** object is for a “timeout”
condition, defining the path if an incoming call is not answered within
the maximum configured ring time.

A simple usage example of the **Ring Group** object is shown below,
where an incoming call is directed to the Sales Ring Group. If the call
is unanswered within the maximum configured ring time, then that call is
forwarded to voicemail.

.. figure:: https://doc.didww.com/_images/ring-group.png
  :figclass: align-center
  :alt: Ring Group Utilization Example

  **Fig. 6.** Example

----

.. raw:: html

    <br>

Adding Multiple Destinations
""""""""""""""""""""""""""""

Clicking **Add ring group destinations** allows the user to add a multiple ring destination
from a drop-down menu of pre-configured contacts and their associated
contact methods.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :alt: Adding Multiple Destinations

  **Fig. 7.** Adding Multiple Destinations

----

.. raw:: html

    <br>

Remove Destinations
"""""""""""""""""""

To remove destinations from a ring group, follow these steps:

    1. **Edit** the ring group by clicking the gear icon.
    2. **Find** the destination you want to remove from your ring group.
    3. Click the **x** button to the right of the destination to remove it from your ring group.
    4. Click **Save** to apply the changes.

.. figure:: https://doc.didww.com/_images/remove_destination.png
   :figclass: align-center
   :alt: Removing a destination from a ring group
   :width: 35%

   **Fig. 8.** Removing a destination from a ring group


.. _ps3_object_voice_menu:

.. raw:: html

   <br>

Object: Voice Menu
^^^^^^^^^^^^^^^^^^

The **Voice Menu** object is used for implementing an IVR (Interactive
Voice Response) or automated attendant system, allowing callers to
listen to a recording and navigate to different destinations using their
dial pad. This object acts as a virtual receptionist, and includes the
ability to play key messages and pass information to callers.

On receiving an incoming call, the **Voice Menu** plays an audio
message, prompting the caller to enter an extension number. The call is
then passed to the connecting object with the matching extension number.
Logic is included so that erroneously entered extensions or caller-entry
timeouts may be properly handled.

.. figure:: https://doc.didww.com/_images/voice-menu-object.jpg
  :figclass: align-center

  **Fig. 1.** Voice Menu Object

The information to be entered for this object is:

-  The name of the **Voice Menu** object, for example, "Main Voice
   Menu".

-  An audio message that is played to the caller can be uploaded from a local drive (in .mp3, .m4a, .wav, .flac, or .ogg format), recorded directly, or selected from files or playlists previously uploaded to the :ref:`Audio Files <ps3_audio_files>` menu. This audio message typically includes information about extension numbers that callers need to enter on their dial pad to connect with people or departments.

.. figure:: https://doc.didww.com/_images/text_to_speech_audio_file_option.png
  :figclass: align-center
  :width: 40%

  **Fig. 2.** Voice Menu Object Creation

If an audio file has not been created yet, you can generate one from
the **Audio File** field in the **Voice Menu** object window. Open the
**Audio File** dropdown and click **Create Audio File**.

In the **Text to speech** window, enter the message, select a **Voice**
from the list of available voices, and click **Generate**. After
previewing the generated audio, enter a filename and click **Save** to
store the file in your audio library. For the full text-to-speech audio
file creation flow, see :ref:`Text to speech audio files <ps3_audio_files_text_to_speech>`.

.. figure:: https://doc.didww.com/_images/text_to_speech_generate.png
  :figclass: align-center
  :width: 40%

  **Fig. 3.** Text to speech window

-  A timeout (from 1 second to 2 minutes), defining the maximum time
   allowed for the caller to enter an extension number using their dial
   pad. This timer starts immediately after the audio message has been
   played. The timeout value is changed by positioning the mouse over
   the right-hand edge of the timeout bar, and then "dragging" the edge
   in a left or right direction.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 4.** Timeout And Playback Sliders

-  A playback counter (from 1 to 11) allows the sequence of playing the
   selected audio file and completing the caller-input timeout to be
   repeated before that call is forwarded in accordance with the
   “Reached timeout limit” logic as described below. The playback count
   is changed by positioning the mouse over the right-hand edge of the
   “Playbacks” bar, and then "dragging" the edge in a left or right
   direction.

It is important to note that cables exiting from the right-hand socket
of the **Voice Menu** object serve three possible functions:

-  **Extension** - The cable forwards incoming calls to the appropriate
   object in response to a valid extension number entered by the caller.

-  **IVR invalid selection** - The cable forwards incoming calls to a
   specified object (such as an **Audio Playback** object) if the caller
   enters an invalid extension number.

-  **Reached the timeout limit** - The cable forwards incoming calls to
   a specified object (such as an **Audio Playback** object) if the
   caller does not enter an extension number within the defined timeout
   period.

When a cable is generated from a **Voice Menu** object and is connected
to another object, a configuration menu is automatically displayed,
prompting the user to select the **Connection type** ("Extension", "IVR
invalid selection" or "Reached the timeout limit") for that cable.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 5.** Create Connection

If a **Connection type** "Extension" is selected, an extension number
must be entered to match the instructions in the voice message that is
played to the caller. This extension number will be displayed on the
cable that connects the **Voice Menu** object to the adjacent object.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 6.** Extension

In the usage example of the **Voice Menu** object shown below, a voice
message is played to the caller, with the instructions “Press 100 for
sales, and 200 for support". If the caller presses “100”, then the call
will be forwarded to the sales ring group, and if “200” is pressed, then
the call will be forwarded to the support ring group. Invalid extension
and timeout conditions are forwarded to specified **Audio Playback**
objects where appropriate messages are played to the caller.

.. figure:: https://doc.didww.com/_images/voice-menu-example-1.jpg
  :figclass: align-center

  **Fig. 7.** First Usage Example

Extension numbers may be changed by clicking on the configured number
displayed on the cable. A configuration dialog window will be opened,
and a new extension number may be entered.

It should be noted that in the case where the caller enters an invalid
extension number or a timeout occurs, the call may be "looped" back to
the **Voice Menu** object. This will cause the instructions regarding
valid extension numbers to be replayed to the caller, and the caller
will have an additional opportunity to contact the desired party. In the
illustration below, calls generating error conditions are forwarded to
**Audio Playback** objects where specified messages are played to the
caller (for example, a message "You have entered an invalid extension
number"). On completion of this audio playback, the call is returned to
the **Voice Menu** object.

.. figure:: https://doc.didww.com/_images/voice-menu-example-2.jpg
  :figclass: align-center

  **Fig. 8.** Second Usage Example

.. |ivrimg1| image:: ../../assets/img/guide-v2/object_config/voice_menu/voice-menu-object.jpg
   :class: guide-img guide-small-png
.. |ivrimg2| image:: ../../assets/img/guide-v2/object_config/voice_menu/creating-voice-menu.png
   :class: guide-img guide-medium-img
.. |ivrimg3| image:: ../../assets/img/guide-v2/object_config/voice_menu/creating-voice-menu-2.png
   :class: guide-img guide-medium-img
.. |ivrimg4| image:: ../../assets/img/guide-v2/object_config/voice_menu/voice-menu-new-connection-1.jpg
   :class: guide-img guide-medium-img
.. |ivrimg5| image:: ../../assets/img/guide-v2/object_config/voice_menu/voice-menu-new-connection-2.jpg
   :class: guide-img guide-medium-img
.. |ivrimg6| image:: ../../assets/img/guide-v2/object_config/voice_menu/voice-menu-example-1.jpg
   :class: guide-img guide-small-img
.. |ivrimg7| image:: ../../assets/img/guide-v2/object_config/voice_menu/voice-menu-example-2.jpg
   :class: guide-img guide-small-img


.. _ps3_object_audio_playback:

.. raw:: html

   <br>

Object: Audio Playback
^^^^^^^^^^^^^^^^^^^^^^

**Audio Playback** allows an audio message such as a voice recording or
music-on-hold to be played to caller. After the audio file has been
played, the call is passed to the object connected to the right-hand
socket of the **Audio Playback** object.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Audio Playback Object

The information to be entered for this object is:

-  The name of the **Audio Playback** object.

-  An audio message that should be played to the caller. In general,
   this audio file will have previously been uploaded from a local drive
   or recorded, and stored in the phone.systems™ :ref:`Audio Files <ps3_audio_files>`.

.. figure:: https://doc.didww.com/_images/text_to_speech_audio_file_option.png
  :figclass: align-center
  :width: 40%

  **Fig. 2.** Create audio file option

If an audio file has not been created yet, you can generate one from
the **Audio File** field in the **Audio Playback** object window. Open
the **Audio File** dropdown and click **Create Audio File**.

In the **Text to speech** window, enter the message, select a **Voice**
from the list of available voices, and click **Generate**. After
previewing the generated audio, enter a filename and click **Save** to
store the file in your audio library. For the full text-to-speech audio
file creation flow, see :ref:`Text to speech audio files <ps3_audio_files_text_to_speech>`.

.. figure:: https://doc.didww.com/_images/text_to_speech_generate.png
  :figclass: align-center
  :width: 40%

  **Fig. 3.** Text to speech window

A usage example for the **Audio Playback** object is shown below, where
a voice message is played to the caller, after which the call is passed
to a **Ring Group** object (“Mike Brown”) for further processing.

.. figure:: https://doc.didww.com/_images/playback-example.jpg
   :class: guide-img
   :align: center

   **Fig. 4.** Example



.. _ps3_object_conference:

.. raw:: html

   <br>

Object: Conference
^^^^^^^^^^^^^^^^^^

The **Conference** object allows multiple callers to partake in a
conference call.

.. figure:: https://doc.didww.com/_images/conference-object.jpg
  :figclass: align-center

  **Fig. 1.** Conference Object

The information to be entered for this object is:

-  The name of the **Conference** object.

-  A PIN (Personal Identification Number) for accessing the conference
   room, with a length of up to four digits. All callers wishing to take
   part in the conference must enter this PIN correctly. If no PIN is
   required, then this field should be left blank.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** Creating A Conference Object

A simple usage example of the **Conference** object is shown below,
where multiple international phone numbers as well as an internal number
provide access to the conference facility.

.. figure:: https://doc.didww.com/_images/conference-example.jpg
  :figclass: align-center

  **Fig. 3.** Usage Example

.. |confimg1| image:: ../../assets/img/guide-v2/object_config/conference/conference-object.jpg
   :class: guide-img guide-small-png
.. |confimg2| image:: ../../assets/img/guide-v2/object_config/conference/creating-conference.jpg
   :class: guide-img guide-medium-img
.. |confimg3| image:: ../../assets/img/guide-v2/inline-img/settings-icon.jpg
   :class: inline-img
.. |confimg4| image:: ../../assets/img/guide-v2/object_config/conference/conference-object-settings-hover.jpg
   :class: guide-img guide-medium-img
.. |confimg5| image:: ../../assets/img/guide-v2/inline-img/mute-icon.jpg
   :class: inline-img
.. |confimg6| image:: ../../assets/img/guide-v2/inline-img/remove-icon.png
   :class: inline-img
.. |confimg7| image:: ../../assets/img/guide-v2/object_config/conference/conference-participants.jpg
   :class: guide-img guide-medium-img
.. |confimg8| image:: ../../assets/img/guide-v2/object_config/conference/conference-refresh1.jpg
   :class: guide-img guide-medium-img
.. |confimg9| image:: ../../assets/img/guide-v2/object_config/conference/conference-refresh2.jpg
   :class: guide-img guide-medium-img
.. |confimg10| image:: ../../assets/img/guide-v2/object_config/conference/conference-refresh3.jpg
   :class: guide-img guide-medium-img
.. |confimg11| image:: ../../assets/img/guide-v2/object_config/conference/conference-example.jpg
   :class: guide-img guide-medium-img


.. _ps3_object_voicemail:

.. raw:: html

   <br>

Object: Voicemail
^^^^^^^^^^^^^^^^^

The **Voicemail** object serves as a mailbox in which callers may leave
voice messages, which are then immediately sent to a specified
destination on the termination of each call.

.. figure:: https://doc.didww.com/_images/voicemail-object.jpg
  :figclass: align-center

  **Fig. 1.** Voicemail Object

The information to be entered for this object is:

-  The name of the **Voicemail** object.

-  The delivery method for the voicemail file. Available delivery methods include:
   Email, Dropbox, FTP, SFTP, Google Drive, OneDrive, and the default phone.systems™ :ref:`cloud storage <ps3_phonesystems_cloudstorage>`.

.. tip::
    - If the required delivery method has not previously been configured, a delivery method may be added by navigating to the :ref:`Delivery Methods <ps3_delivery_methods>` menu.
    - When using the default **phone.systems™** cloud storage as the delivery method, voicemails will appear in the :ref:`call flow CDRs <ps3_call_flow_cdrs_voicemail>`, providing a centralized and convenient way to review voicemails alongside other call activities.

-  An audio message that is played to the caller can be uploaded from a local drive (in .mp3, m4a, .wav, .flac, or .ogg format), recorded directly, or selected from files or playlists previously uploaded to the :ref:`Audio Files <ps3_audio_files>` menu.

-  The maximum length of the voicemail, with valid values being from 1
   to 60 minutes. The call will automatically be terminated after this
   configured time period, unless the caller hangs up before the
   expiration of this timer.

.. figure:: https://doc.didww.com/_images/text_to_speech_audio_file_option.png
  :figclass: align-center
  :width: 40%

  **Fig. 2.** Voicemail Object Creation

If an audio file has not been created yet, you can generate one from
the **Audio File** field in the **Voicemail** object window. Open the
**Audio File** dropdown and click **Create Audio File**.

In the **Text to speech** window, enter the message, select a **Voice**
from the list of available voices, and click **Generate**. After
previewing the generated audio, enter a filename and click **Save** to
store the file in your audio library. For the full text-to-speech audio
file creation flow, see :ref:`Text to speech audio files <ps3_audio_files_text_to_speech>`.

.. figure:: https://doc.didww.com/_images/text_to_speech_generate.png
  :figclass: align-center
  :width: 40%

  **Fig. 4.** Text to speech window

A simple usage example of the **Voicemail** object is shown below, where
an incoming call is forwarded to the ring group Mike Brown. If Mike does
not answer the call within the defined ring timeout period then that
call is sent to voicemail, where the caller may leave a message.

.. figure:: https://doc.didww.com/_images/voicemail-example.jpg
  :figclass: align-center

  **Fig. 5.** Example


.. _ps3_object_fax:

.. raw:: html

   <br>

Object: Fax
^^^^^^^^^^^

The **Fax** object allows incoming faxes to be stored in PDF format,
with multiple file delivery options being available. G.711 pass-through
and T.38 fax protocols are supported.

.. figure:: https://doc.didww.com/_images/fax-object.jpg
  :figclass: align-center
  :alt: Fax Object

  **Fig. 1.** Fax Object

The information to be entered for this object is:

-  The name of the **Fax** object.

-  The delivery method for the fax PDF file. Available delivery methods include:
   Email, Dropbox, FTP, SFTP, Google Drive, OneDrive, and the default phone.systems™ :ref:`cloud storage <ps3_phonesystems_cloudstorage>`.

.. tip::
    - If the required delivery method has not previously been configured, a delivery method may be added by navigating to the :ref:`Delivery Methods <ps3_delivery_methods>` menu.
    - When using the default **phone.systems™** cloud storage as the delivery method, faxes will appear in the :ref:`call flow CDRs <ps3_call_flow_cdrs_fax>`, providing a centralized and convenient way to review fax transmissions alongside other call activities.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :width: 40%
  :alt: Fax Object Creation

  **Fig. 2.** Fax Object Creation

A simple usage example of the **Fax** object is shown below, where an
incoming call is forwarded to the Sales Fax object.

.. figure:: https://doc.didww.com/_images/fax-example.jpg
  :figclass: align-center
  :alt: Fax Object Example

  **Fig. 3.** Example



.. _ps3_object_call_recorder:

.. raw:: html

   <br>

Object: Call Recorder
^^^^^^^^^^^^^^^^^^^^^

The **Call Recorder** object allows phone calls to be recorded. The call
contents are sent to a predefined destination immediately after the
termination of each call.

.. figure:: https://doc.didww.com/_images/call-recorder-object.jpg
  :figclass: align-center

  **Fig. 1.** Call Recorder

The information to be entered for this object is:

-  The name of the **Call Recorder** object.

-  The delivery method for the call recording file. Available delivery methods include:
   Email, Dropbox, FTP, SFTP, Google Drive, OneDrive, and the default phone.systems™ :ref:`cloud storage <ps3_phonesystems_cloudstorage>`.

.. tip::
    - If the required delivery method has not previously been configured, a delivery method may be added by navigating to the :ref:`Delivery Methods <ps3_delivery_methods>` menu.
    - When using the default **phone.systems™** cloud storage as the delivery method, call recordings will appear in the :ref:`call flow CDRs <ps3_call_flow_cdrs_recording>`, providing a centralized and convenient way to review call recordings alongside other call activities.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :width: 40%

  **Fig. 2.** Call Recorder Object creation

.. note:: Call recordings sent to an email address may not be delivered due to file size limitations on the destination email server. Please note that if the destination server rejects the file, then that file will be unrecoverable. The approximate file size of call recordings is 7 MB per hour, and users should carefully consider this parameter when selecting a file **Delivery Method**.

A usage example for the **Call Recorder** object is shown below, where
this object is inserted between a **Phone Number** and **Ring Group**
object. All incoming calls to Mike Brown are recorded, and the audio
file is forwarded to a predefined destination immediately after the
termination of each call.

.. figure:: https://doc.didww.com/_images/call-recorder-example.jpg
  :figclass: align-center

  **Fig. 3.** Example

.. _ps3_object_caller_router:

.. raw:: html

   <br>

Object: Caller Router
^^^^^^^^^^^^^^^^^^^^^

The **Caller Router** object allows incoming calls to be forwarded to
different objects, depending on the originating phone number or CLI
(Calling Line Identity). Users have the option of matching complete
phone numbers, or forwarding calls according to number prefixes.

.. figure:: https://doc.didww.com/_images/caller-router-object.jpg
  :figclass: align-center

  **Fig. 1.** Caller Router

Caller routing is based on a simple “Allow/Disallow” logic, depending on
the setting of the "behavior" indicator associated with each listed
number/prefix. The **Caller Router** object must be connected to two
child objects such as **Ring Group** or **Voicemail** objects, to which
calls are forwarded according to this “Allow/Disallow” logic.

The **Caller Router** object includes both green ("Allow") and red
("Disallow") right-hand sockets for cable connections. A cable
originating from the green socket corresponds to the “Allow” option,
while a cable originating from the red socket corresponds to the
“Disallow” option.

In the figure below, the **Caller Router** object is configured to
include the phone number prefixes 1416, 1437, and 1647, with the
"behavior" set to "Allow" for all the listed prefixes. Therefore, if
incoming calls are received with a CLI matching any of these prefixes,
then those calls are routed via the green socket to the Toronto Voice
Menu. All other incoming calls are sent to the Ontario Voice Menu.

.. figure:: https://doc.didww.com/_images/caller-router-example.jpg
  :figclass: align-center

  **Fig. 2.** Caller Router Implementation

The information to be entered for this object is:

-  **Name:**  The name of the **Caller Router** object.

-  **Default Route:**  Specifies which route ("Allow" or "Disallow") to
   which the call will be forwarded if the incoming phone number does
   not match any of the configured routing rules.

-  **Algorithm:**  An algorithm to be used for number routing, with the
   options being "Prefix" or "Number". "Prefix" matches are determined
   according to "number starts with" logic, while "Number" matches
   require an exact CLI match. Note that either the "Prefix" or "Number"
   option may be selected, and these algorithms may not be mixed on a
   single Caller Router object.

-  **Numbers and Behavior:**  A list of phone number/s or prefix/es required
   for the caller routing logic, together with an “Allow/Disallow”
   indicator that defines the call routing behavior for that specific
   number or prefix. Alphanumeric inputs (both letters and numerals) are
   supported, with letters being case sensitive. There are no
   limitations on the format (such as E.164) or the number of characters
   used in listing these phone numbers/prefixes, so as to allow for
   maximum flexibility in CLI matching. Multiple numbers or prefixes may
   be added as required.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 3.** Caller Router Object creation

In the figure above, incoming calls with a CLI prefix of 1647 or 1416 will be forwarded to the object connected to the green ("Allow") socket of the **Caller Router** object, while calls having a prefix of 1514 will be forwarded to the object connected to the red ("Disallow") socket.

Phone numbers or prefixes previously added to the **Caller Router**
object may be deleted by clicking on the "X" icon to the right of
the number.

.. _ps3_object_blocklist:

.. raw:: html

   <br>

Object: Blocklist
^^^^^^^^^^^^^^^^^

The **Blocklist** object is used to block incoming calls received from
specific phone numbers and empty or alphabetical CLIs. If the calling
number **exactly** matches the configured settings or phone number, then
the incoming call will be automatically terminated and will not be
passed to objects connected to the right-hand side of the **Blocklist**
object.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 1.** Blocklist Object

The information to be entered for this object is:

-  The name of the **Blocklist** object.

-  Additional Settings:

  - **Block empty Caller IDs** - When the source number field is empty or null, the call will be terminated.

  - **Block Caller IDs containing letters** - When the source number field includes alphabetical characters, the call will be terminated.

-  **The blocklisted phone numbers** - A list of the **exact** phone
   numbers to be blocked. There are no limitations on the format (such
   as E.164) or the number of digits used in listing these phone
   numbers, so as to allow for maximum flexibility in CLI matching.
   Multiple numbers may be added as required.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 2.** Creating a Blocklist

Phone numbers previously added to the **Blocklist** object may be
deleted by clicking on the "X" icon to the right of the number.

A simple usage example of the **Blocklist** object is shown below, where
the blocklist filter is applied to all incoming calls before those calls
are processed by the company’s voice menu.

.. figure:: https://doc.didww.com/_images/blocklist-example.png
  :figclass: align-center
  :figwidth: 50%

  **Fig. 3.** Example


.. _ps3_object_queue:

.. raw:: html

   <br>

Object: Queue
^^^^^^^^^^^^^

The **Queue** object causes incoming calls to be placed in a queue
before those calls are passed on to queue members (destinations). This
allows a large number of calls to be handled, such as in a call center.
The **Queue** object includes a ring strategy that is used to define how
the calls are divided between queue destinations. Music or other
messages may be played to callers while they are waiting in the queue,
and ringback tones are supported, allowing audio clips to be played to
callers before their call is answered.

.. figure:: https://doc.didww.com/_images/queue-object.jpg
  :figclass: align-center
  :alt: Queue Object

  **Fig. 1.** Queue Object

The **Queue** object includes multiple destinations to which calls are
forwarded as per the selected ring strategy, and these destinations are
added to the **Queue** object as "contacts". The only cable exiting the
**Queue** object is for a “queue timeout”, defining the call path if the
queue wait time exceeds the maximum configured value.

In the figure below, incoming calls are forwarded to the **Queue**
object, which includes two queue destinations. If a call is not
answered within the configured queue timeout, then that call is sent to
the “Queue Timeout” Voicemail object.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: Queue Object Usage

  **Fig. 2.** Queue Object Usage

----

.. raw:: html

    <br>

Queue Configuration
"""""""""""""""""""

The information to be entered for this object is:

-  The name of the **Queue** object.
-  The ring strategy to be used for this queue. The options for the ring strategy are as follows:

   - **Round robin** – The queue remembers the last destination it attempted
     to contact. The next call starts with the following destination and
     continues forward through the queue.

     For example, if Call A attempts destinations 1, 2, and 3 before
     terminating, Call B starts with destination 4 and continues through the
     remaining destinations until the end of the queue is reached.

   - **Ring all** – When a call enters a queue configured with two or more
     destinations, all available destinations are called simultaneously for
     the configured **Queue Destination Timeout**.

     .. note::

        By default, up to **10 queue destinations per customer account** can
        ring simultaneously. If more queue destinations are available, only
        the number allowed by the account's simultaneous ringing limit can be
        processed at once.

     If none of the destinations answers, the queue behavior depends on the
     SIP response received:

     - **480 – Temporarily Unavailable**
     - **486 – Busy Here**
     - **487 – Request Terminated**

     These responses are treated as temporary conditions, so the affected
     destinations may be attempted again while the call remains in the same
     queue. If none of the destinations returns one of these responses, the
     call skips to the next object connected to the queue.

   - **Random** – Randomly rings a single queue member.

- **Queue timeout** defines the maximum time that an unanswered call can
  remain in the queue. When this time expires, the call is forwarded to the
  connected object. Valid values range from **00:05** (five seconds) to
  **15:00** (fifteen minutes). If no call path is connected to the queue
  timeout, the call is terminated when the timeout expires.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :alt: Creating Queue Objects

  **Fig. 3.** Creating Queue Objects

----

.. raw:: html

    <br>

Users Tab
""""""""""""

The **Users** tab is used to define the members or destinations of the queue. Each queue destination consists of a user and an associated contact method, which must be pre-configured using the :ref:`Contact Methods <ps3_contact_methods>` tab.

Selecting **Add queue destination** allows the user to add a queue destination from a drop-down menu of pre-configured contacts and their associated contact methods. If you do not have any contacts, you can create them in the :ref:`Contact Methods <ps3_contact_methods>` tab.

**Queue Destination Timeout** defines how long each destination rings before
the queue moves on. It applies to all three ring strategies and is separate
from the object-level **Queue timeout**, which limits the call's total time
in the queue rather than a single ringing attempt. Valid values range from
**0** to **60 seconds**.

.. important::

   Many softphones respond with SIP **408 Request Timeout** when a call
   rings for the full 60 seconds, following SIP/RFC timeout handling
   implemented by those clients. Set the Queue Destination Timeout to
   **55 seconds** or less to avoid reaching this limitation.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center
  :alt: Users Tab

  **Fig. 4.** Users Tab

----

.. raw:: html

    <br>

Media Tab
"""""""""

The **Media** tab is used to set both "music-on-hold" and "ringback
tone" playlists. This allows pre-recorded music, messages, commercials
or any other audio clips to be played to callers before their call is
answered (ringback tone), or while an active call is put on hold
(music-on-hold).

An audio message that is played to the caller can be uploaded from a local drive (in .mp3, .wav, .flac, or .ogg format), recorded directly, or selected from files or playlists previously uploaded to the :ref:`Audio Files <ps3_audio_files>` menu.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Media Tab

  **Fig. 5.** Media Tab

----

.. raw:: html

    <br>

CLI Rules Tab
"""""""""""""

The **CLI Rules** tab is used to override the Source **Caller Name**.
This functionality allows flexible Caller Name configurations and may be
used to differentiate SIP calls received from phone.systems™. **CLI
Rules** will help you to identify from which **Queue** object the call
is coming from.

Some CLI Rule examples:

**1. Changing Caller Name to Custom text:**

  * SRC Name Rewrite Rule: ``^(.*)$``
  * SRC Name Rewrite Result: ``Custom text``

**2. Add Custom text before the original Caller Name:**

  * SRC Name Rewrite Rule: ``^(.*)$``
  * SRC Name Rewrite Result: ``Custom text \1``

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :width: 35%
  :alt: CLI Rules Tab

  **Fig. 6.** CLI Rules Tab

----

.. raw:: html

    <br>

Adding Multiple Destinations
""""""""""""""""""""""""""""

Selecting **Add queue destination** allows the user to add a multiple ring destination
from a drop-down menu of pre-configured contacts and their associated
contact methods.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :alt: Adding Multiple Destinations

  **Fig. 7.** Adding Multiple Destinations

----

.. raw:: html

    <br>

Remove Destinations
"""""""""""""""""""

To remove destinations from a queue, follow these steps:

    1. **Edit** the queue object by clicking the gear icon.
    2. Open the **Users** tab.
    3. **Find** the destination you want to remove from your queue.
    4. Click the **x** button to the right of the destination to remove it from your queue.
    5. Click **Save** to apply the changes.

.. figure:: https://doc.didww.com/_images/remove_destination.png
   :figclass: align-center
   :alt: Removing a destination from a queue
   :width: 35%

   **Fig. 8.** Removing a destination from a queue


.. _ps3_object_time_router:

.. raw:: html

   <br>

Object: Time Router
^^^^^^^^^^^^^^^^^^^

The **Time Router** object allows incoming calls to be forwarded to
different objects based on specific day and time conditions.
This enables flexible call routing during and outside of business hours.

.. figure:: https://doc.didww.com/_images/time-router-object.png
  :figclass: align-center
  :alt: Time Router Object
  :width: 20%

  **Fig. 1.** Time Router Object

The **Time Router** operates using a simple ``Yes / No`` logic.

- A cable from the **green socket** corresponds to ``Yes``, defining how calls are routed **within** the configured schedule or time intervals.
- A cable from the **red socket** corresponds to ``No``, defining how calls are routed **outside** the configured schedule or time intervals.

In the example below, if incoming calls are received within the configured business hours, they are forwarded to the **Sales Queue**.
Otherwise, calls are directed to the **Voicemail** object, where an after-hours message is played.

.. figure:: https://doc.didww.com/_images/time-router-example.png
  :figclass: align-center
  :alt: Time Router Usage Example
  :width: 30%

  **Fig. 2.** Example of Time Router usage in a call flow

----

Configuration
-------------

When configuring the **Time Router**, you can choose between using a predefined **Time Schedule** or defining **Dedicated Time Intervals** manually.

.. tab-set::
   :sync-group: time-router
   :class: my-tabs

   .. tab-item:: **Using Time Schedules**
      :sync: schedule

      .. raw:: html

         <br>

      Select an existing **Time Schedule** to determine when the Time Router directs calls through its ``Yes`` or ``No`` paths.
      This option allows you to reuse predefined schedules created in the :ref:`Time Schedules <ps3_time_schedules>` section.

      1. Enter the **Name** for your Time Router object.
      2. From the **Time Schedule** dropdown, choose a previously created schedule.
      3. Ensure the **Use dedicated time intervals** toggle is **disabled**.

      .. note::
         The time zone used for routing is defined in the selected **Time Schedule**.

      .. figure:: https://doc.didww.com/_images/time_schedule_config.png
         :figclass: align-center
         :alt: Time Router using a Time Schedule
         :width: 33%

         **Fig. 3.** Creating a Time Router using a Time Schedule

   .. tab-item:: **Using Dedicated Time Intervals**
      :sync: intervals

      .. raw:: html

         <br>

      Enable the **Use dedicated time intervals** toggle to manually define specific day and time conditions directly within the Time Router.

      1. Enter the **Name** for your Time Router object.
      2. Toggle **Use dedicated time intervals** to **ON**.
         The **Time Schedule** dropdown will become unavailable.
      3. Select a **Time Zone**.
         The ``System`` option applies the same time zone as defined in :ref:`General Settings <ps3_general_settings>`.
      4. Click **Add Time Interval** to create one or more routing rules.

          Each interval can specify:
             - **Days of the week** (selectable by clicking on each day).
             - **Start** and **End times** using the **HH:MM** 24-hour format.

      .. note::

          The Time Router object may include **multiple** dedicated time intervals, allowing flexible routing options.
          For example, you can define intervals for **Monday–Friday 09:00–17:00** and **Saturday 09:00–13:00**, both routing calls to the ``Yes`` destination.

      .. grid:: 1 1 1 2
         :gutter: 4

         .. grid-item::
            :class: text-center

            .. figure:: https://doc.didww.com/_images/dedicated_time_interval2.png
               :figclass: align-center
               :alt: Time Router using Dedicated Time Intervals

               **Fig. 4.** Time Router using Dedicated Time Intervals

         .. grid-item::
            :class: text-center

            .. figure:: https://doc.didww.com/_images/dedicated_time_interval1.png
               :figclass: align-center
               :alt: Creating a Time Interval

               **Fig. 5.** Creating a Time Interval



.. _ps3_object_notification:

.. raw:: html

   <br>

Object: Notification
^^^^^^^^^^^^^^^^^^^^

The **Notification** object is used to provide alerts via email when a
specified event occurs. For example, a notification may be issued when a
caller joins a conference or when a queue timeout occur.

.. figure:: https://doc.didww.com/_images/notification-object.jpg
  :figclass: align-center

  **Fig. 1.** Notification Object

The information to be entered for this object is:

-  The name of the **Notification** object.

-  The delivery method for the notification message, with the only
   option being Email. If the required delivery method has not
   previously been configured, a delivery method may be added by
   selecting the navigating to the :ref:`Delivery Methods <ps3_delivery_methods>` menu.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 2.** Notification Object Creation

A simple usage example of the **Notification** object is shown below.
Calls that are not answered by any of the members of the sales queue
within the defined timeout period are passed to the **Notification**
object, and a notification email is issued.

.. figure:: https://doc.didww.com/_images/notification-example.jpg
  :figclass: align-center

  **Fig. 3.** Example



.. _ps3_object_forwarding:

.. |br| raw:: html

   <br />

.. raw:: html

   <br>

Object: Forwarding
^^^^^^^^^^^^^^^^^^

The **Forwarding Object** is used to forward calls between two different :ref:`Call Flows <ps3_call_flows>`.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Forwarding Object

**Step 1:** Create an Internal Number:

Begin by creating an :ref:`Internal Number <ps3_internal_numbers>`.

**Step 2:** Add the Internal Number to the target Call Flow:

Place the :ref:`Internal Number object <ps3_internal_number_object>` into the call flow workspace where you want the calls to be forwarded.

**Example**: If forwarding calls from Support to Sales, place the :ref:`Internal Number object <ps3_internal_number_object>` in the Sales call flow.

**Step 3:** Configure the :ref:`Internal Number object <ps3_internal_number_object>`:

In this scenario, we will be forwarding calls from Support to Sales, so configure the Internal Number object in the Sales call flow.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** Internal Number Object

**Step 4:** Add the Forwarding Object.

After configuring the :ref:`Internal Number object <ps3_internal_number_object>`, return to the original call flow from which you will be forwarding the calls. Select the **Forwarding Object** and drag it onto your workspace.

**Step 5:** Configure the **Forwarding Object**, you will need to configure the following details:

- **Name**

- **Internal Number Forwarding Destination**

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 3.** Creating The Forwarding Object

**Step 6:** Connect the Forwarding Object.

Once the object is created, connect it to your existing call flow.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 4.** Connecting The Forwarding Object To The Support Call Flow

In our example, when a caller contacts the support number and dials the extension "3", the call will be forwarded to the Sales call flow.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 5.** Connecting The Internal Number Object To The Sales Call Flow

.. _ps3_tabs_and_multiple_pages:

=======================
Tabs and Multiple Pages
=======================

phone.systems™ allows users to segment voice systems into logical groups
and functions that may be arranged over multiple workspace pages. This
feature is very useful when building complex voice systems, such as a
virtual PBX for a multi-branch business.

As detailed in the previous :ref:`Workspace Tab Menu <ps3_workspace_tab_menu>`
section, additional workspace pages may be added as required, and the
various workspace pages are accessed via the tabs on the **Workspace Tab** menu.

This section serves to illustrate how to use multiple workspace pages in
order to build advanced voice scenarios.

----

.. _ps3_moving_objects_between_workspace_pages:

Moving Objects between Workspace Pages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Objects may be moved between workspace pages. In the illustration below,
two workspace pages are available: **Default** and **Sales**, with the
**Default** workspace comprising a number of objects, including an
object "Sales Voice Menu". Note that the name of the active workspace
page (i.e., the page that is currently being displayed) is shown in
blue.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :width: 50%

  **Fig. 1.** Selecting The Object

If it is required that the voice system logic for the sales division
should be assembled on the **Sales** workspace page, then the "Sales
Voice Menu" object should be moved to that page. To achieve this, "drag"
the "Sales Voice Menu" object over the **Sales** workspace tab, until
that tab is shown in blue to indicate that the **Sales** workspace is
active. Do not release the object.

.. figure:: https://doc.didww.com/_images/gif1.gif
  :figclass: align-center

  **Fig. 2.** Dragging The Object

Continue "dragging" the "Sales Voice Menu" object downwards into the
active **Sales** workspace, and release that object in the desired
position on that workspace. Further assembly of the voice system logic
for the sales division may now continue on this workspace.

.. figure:: https://doc.didww.com/_images/gif2.gif
  :figclass: align-center

  **Fig. 3.** Dropping The Object

Re-selecting the **Default** workspace tab shows the objects remaining on this page. The "Sales Voice Menu" object is no longer present, as it has been moved to the **Sales** workspace page.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :width: 50%

  **Fig. 4.** Tab View

----

.. _ps3_connecting_cables:

Connecting Cables Between Objects on Different Workspace Pages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Partial voice scenarios assembled on different workspace pages must be
interconnected in order to build complete voice systems. In the example
above, calls must be passed from the "Main Voice Menu" on the
**Default** workspace page to the "Sales Voice Menu" on the **Sales**
workspace page.

To generate a cable between these two objects, "drag" a cable from the
right-hand socket of the "Main Voice Menu" object, placing the mouse
pointer over the **Sales** workspace tab, until that tab is shown in
blue to indicate that the **Sales** workspace is active. Do not release
the cable.

Continue "dragging" the cable downwards into the active **Sales**
workspace, and position that cable over the left-hand socket of the
"Sales Voice Menu" object. Release the cable.

.. figure:: https://doc.didww.com/_images/gif3.gif
  :figclass: align-center
  :width: 50%

  **Fig. 1.** Connecting Two Objects In Different Tabs

The cable connection between the "Main Voice Menu" on the **Default**
workspace page and the "Sales Voice Menu" on the **Sales** workspace
page is now complete.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :width: 50%

  **Fig. 2.** "Sales" Tab Configuration

The logical connectivity between objects on different workspace pages is
represented by a cable terminating in a |wspimg8| icon. By clicking on
this |wspimg9| icon, the alternate workspace page associated with this
connection will be displayed.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :figwidth: 62%

  **Fig. 3.** "Default" Tab Configuration

The cable termination icon |wspimg12| may be dragged and
repositioned independently on each individual workspace page, without
affecting the position of the logically connected termination icon on
the other workspace page.

.. important:: if two objects on the same workspace page are connected, then moving one of the objects to a different workspace page will not disconnect the objects. Instead, these objects will remain connected, with the |wspimg13| icon indicating the cable continuity over the different workspace pages.

----

Usage Example - Multiple Workspace Pages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the PBX configuration below, the main voice menu directs incoming
calls to either a sales or support departmental voice menu, and then
these calls are further distributed to members within each department.

.. figure:: https://doc.didww.com/_images/figX.jpg
  :figclass: align-center

  **Fig. 1.** Medium Business Workspace Example

This PBX configuration may be logically divided into three separate
functional groups:

-  The main PBX logic consisting of the incoming phone numbers and the
   main voice menu.

-  The PBX logic for the sales division (starting with the sales Voice
   Menu object).

-  The PBX logic for the support division (starting with the support
   Voice Menu object).

In order to segment this voice scenario, additional workspace pages must
be added and workspace tabs are labeled **Main**, **Sales** and
**Support**.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :width: 50%

  **Fig. 2.** Workspaces

In order to logically segment this voice system, objects on the **Main**
workspace page may now be moved to other workspace pages as detailed in
the section :ref:`Moving Objects Between Workspaces <ps3_moving_objects_between_workspace_pages>`
above.

.. important:: Instead of assembling the complete voice system on a single workspace page and then moving objects to other pages, it is easier and more practical to first create the required workspace pages and assemble the voice "sub-systems" on each of those pages. Once this has been done, then the partial voice scenarios on different workspace pages may be interconnected as described in the section :ref:`Connecting Cables Between Objects on Different Workspace Pages <ps3_connecting_cables>`.

Referring to the voice scenario described above, the logical
segmentation results in three separate workspaces pages as follows:

-  The Main workspace

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center
  :figwidth: 80%

  **Fig. 3.** The Main Workspace

-  The Sales workspace

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center
  :figwidth: 79%

  **Fig. 4.** The Sales Workspace

-  The Support workspace

.. figure:: https://doc.didww.com/_images/fig10.png
  :figclass: align-center
  :figwidth: 96%

  **Fig. 5.** The Support Workspace

.. |wspimg1| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-1.jpg
   :class: guide-img guide-small-img
.. |wspimg2| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-2.jpg
   :class: guide-img guide-small-img
.. |wspimg3| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-3.jpg
   :class: guide-img guide-small-img
.. |wspimg4| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-4.jpg
   :class: guide-img guide-small-img
.. |wspimg5| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-cables-1.jpg
   :class: guide-img guide-small-img
.. |wspimg6| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-cables-2.jpg
   :class: guide-img guide-small-img
.. |wspimg7| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-cables-3.jpg
   :class: guide-img guide-small-img
.. |wspimg8| image:: ../assets/img/guide-v2/inline-img/teleport-icon.jpg
   :class: inline-img no-lightbox no-shadow
.. |wspimg9| image:: ../assets/img/guide-v2/inline-img/teleport-icon.jpg
   :class: inline-img no-lightbox no-shadow
.. |wspimg10| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-cables-4.jpg
   :class: guide-img guide-small-img
.. |wspimg11| image:: ../assets/img/guide-v2/workspace/workspace-tab-moving-cables-5.jpg
   :class: guide-img guide-small-img
.. |wspimg12| image:: ../assets/img/guide-v2/inline-img/teleport-icon.jpg
   :class: inline-img no-lightbox no-shadow
.. |wspimg13| image:: ../assets/img/guide-v2/inline-img/teleport-icon.jpg
   :class: inline-im no-lightbox no-shadow
   :width: 30px
   :height: 30px
.. |wspimg15| image:: ../assets/img/guide-v2/workspace/workspace-tabs.jpg
   :class: guide-img guide-small-long-img
.. |wspimg16| image:: ../assets/img/guide-v2/workspace/workspace-tab-main.jpg
   :class: guide-img guide-small-long-img
.. |wspimg17| image:: ../assets/img/guide-v2/workspace/workspace-tab-sales.jpg
   :class: guide-img guide-small-long-img
.. |wspimg18| image:: ../assets/img/guide-v2/workspace/workspace-tab-support.jpg
   :class: guide-img guide-small-long-img

.. raw:: html

   <style>
        /* Fix image size */
        .custom-button5rem,
        .custom-button5rem img,
        .custom-button5rem a {
            width: 4.5rem !important;
        }

        .custom-button8rem,
        .custom-button8rem img,
        .custom-button8rem a {
            width: 8rem !important;
        }

        .no-lightbox50,
        .no-lightbox50 img,
        .no-lightbox50 a {
            width: 35px !important;
        }

        .no-lightbox110,
        .no-lightbox110 img,
        .no-lightbox110 a {
            width: 110px !important;
        }
   </style>


==============
Usage Examples
==============

phone.systems™ objects may be arranged and logically connected in an
unlimited number of combinations that will satisfy a wide variety of
voice system requirements. Below are some basic configuration examples
that will assist the user to understand the various objects, their
functionality and the versatility of phone.systems™.

----

Simple Call Forwarding Setup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For this easy setup only 2 objects are required to be connected - a
Phone Number and a Ring Group object.

.. figure:: https://doc.didww.com/_images/simple-call-setup-sip-offline.jpg
  :figclass: align-center

  **Fig. 1.** Simple Call Forwarding Setup

Before adding these objects to the phone.systems™ workspace, some
resources may optionally be pre-configured, namely:

-  A phone number must be added to the phone.systems™ environment - see
   the section :ref:`Phone Numbers <ps3_phone_numbers>` for further
   details.
-  A Contact Method (preferably a SIP account) should be configured -
   see the section :ref:`SIP Accounts <ps3_sip_accounts>` for further details.

If these resources are not pre-configured, then they may be added during
object configuration.

-  **Add a “Phone Number” object** - From the object menu, drag and
   drop a **Phone Number** object onto the workspace.

.. figure:: https://doc.didww.com/_images/gif1.gif
  :figclass: align-center

  **Fig. 2.** Adding Phone Number Object

Once the object is added to the workspace, a new configuration window will appear. In the **Number** section, click the dropdown menu and select the phone number configured in the previous step. Alternatively, you can add and assign a new phone number to the **Phone Number** object. Click **Save**.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 3.** Phone Number Object Creation

-  **Add a “Ring Group” Object** - From Object Menu drag and drop a **Ring Group** object onto the workspace.

.. figure:: https://doc.didww.com/_images/gif2.gif
  :figclass: align-center

  **Fig. 4.** Adding Ring group Number Object

Once the object is added to the workspace, a window will appear for configuring the ring group. Click **Add ring group destinations** and select a previously configured contact method from the dropdown menu. Alternatively, you can add a new contact and contact method, and assign them to the **Ring Group** object. Click **Save**.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 5.** Ring Group Object Creation

-  **Connect objects with the “cable”** - Drag the “cable” from the
   **Phone Number** object and connect it to the **Ring Group** Object. The
   setup has now been completed in the phone.systems™ environment.

.. figure:: https://doc.didww.com/_images/simple-call-setup-connect-cable.jpg
  :figclass: align-center

  **Fig. 6.** Connecting Objects

-  **Configure a SIP account on your device** - please refer to the
   section :ref:`Configuring Softphones <ps3_configuring_softphones>`.

You are now ready to receive and make phone calls using phone.systems™.

.. figure:: https://doc.didww.com/_images/simple-call-setup-sip-online.jpg
  :figclass: align-center

  **Fig. 7.** Completed Configuration

----

Calling between Internal Numbers (Extensions)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This usage example will enable voice calls on phone.systems™ between two
softphones, using Internal Numbers (or extensions) to connect the two
parties. The configuration steps for this usage example are as follows:

-  **Optionally pre-configure resources**

   -  Two Internal Numbers - see the section :ref:`Internal Numbers <ps3_internal_numbers>` for further details.

   -  Two SIP account Contact Methods - see the section :ref:`Contact Methods <ps3_contact_methods>` for further details.
      Important - when configuring a SIP account, the “Internal caller
      ID” for the account must be assigned from the pre-configured
      Internal Number list. This number will be displayed as “Caller ID”
      to the recipient of the incoming call.

-  **Add an “Internal Number” object**

From the **Object Menu**, drag and drop an “Internal Number” object onto the workspace.

.. figure:: https://doc.didww.com/_images/fig1.gif
  :figclass: align-center

  **Fig. 1.** Adding An Internal Number Object

Once this **Internal Number** object is added onto the workspace, a configuration window will appear. Click on the **Number** section in the dropdown menu, and select a pre-configured internal number (if applicable). Alternatively, a new internal number may be added and allocated to this “Internal Number” object. Click on the **Save** button.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** Creating An Internal Number Object

* **Add a “Ring Group” Object:**

From the **Object Menu**, drag and drop a “Ring Group” object onto the workspace.

.. figure:: https://doc.didww.com/_images/fig3.gif
  :figclass: align-center

  **Fig. 3.** Adding A Ring Group Object

Once that object is added onto the workspace, a window will appear that allows the configuration of the Ring Group. Click **Add queue destination** and select a previously configured **Contact Method** from the drop-down menu (if applicable). Alternatively, a new **Contact** and **Contact Method** may be added and allocated to the “Ring Group” object. Click on the **Save** button.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 4.** Creating A Ring Group Object

* **Connect the “Internal Number” and “Ring Group” objects with a “cable”:**

Drag a “cable” from the “Internal Number” object and connect it to the “Ring Group” object.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 5.** Connecting Objects

* **Repeat the procedure of adding and configuring “Internal Number” and “Ring Group” objects:**

Add another **Internal Number** object (for example, using the number 2010)

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 6.** Second Internal Number Object

Add another **Ring Group** destination (for example Tim’s PSTN).

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 7.** Second Ring Group Object

Connect these two objects with a “cable”.

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 8.** Connecting The Cables

Calls may now be made between the two internal numbers (extensions) on
phone.systems™.

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 9.** Completed Configuration

----

For Personal/Small Business Use
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Incoming calls to the assigned phone number are directed to a **Ring
Group** object ("Mike Brown"), where the calls are forwarded to Mike's
configured contact numbers ("Work" and "Mobile") in a defined sequence.
If the call is not answered, then that call is directed to voicemail.
The caller leaves a message that is sent to a specified email address.

.. figure:: https://doc.didww.com/_images/personal-use-example.jpg
  :figclass: align-center

  **Fig. 9.** Completed Configuration

In the above example, this **Ring Group** object is configured for the
following logic:

-  On receiving an incoming call, first ring Mike's work phone for 30
   seconds.

-  If the work phone is not answered (or the line is busy), then ring
   Mike’s mobile phone for 30 seconds.

-  If there is still no answer, then forward the call to voicemail.

.. note:: Ringing sequence and ringing times for each contact method are configurable.

----

For Small Businesses and Groups
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Incoming calls to multiple phone numbers are directed to the **Voice
Menu** object, and a previously recorded, custom message is played. This
message serves to provide the caller with further options regarding the
routing of their call via extension numbers, for example, *“Press 1 for
Mike, 2 for Pete”*. If neither Mike nor Pete answer the incoming call
within the defined timeouts, then that call is sent to their personal
voicemail. In the case that callers do not select a valid extension
option or if they do not provide keypad input within the defined timeout
period, the **Voice Menu** object directs those calls to **Audio
Playback** objects where messages are played to callers.

.. figure:: https://doc.didww.com/_images/small-business-use-example.jpg
  :figclass: align-center

  **Fig. 10.** Completed Configuration

----

For Medium-Size Businesses
^^^^^^^^^^^^^^^^^^^^^^^^^^

phone.systems™ objects may be simply added and configured to meet the
evolving needs and functions of a business, with the **Voice Menu**
object being used to direct phone calls to various departments and
personnel, whether they be local or remote.

In the scenario shown below, calls to multiple phone numbers are
directed to a **Voice Menu** object functioning as the main switchboard.
Calls are then forwarded to secondary **Voice Menus**, where extension
numbers entered by the callers direct those calls to specific personnel
in the sales or technical support departments.

.. figure:: https://doc.didww.com/_images/medium-business-use-example.jpg
  :figclass: align-center

  **Fig. 11.** Completed Configuration



.. _ps3_configuring_softphones:

======================
Configuring Softphones
======================

Softphones allow the user to receive calls and make outbound calls over
the Internet from a computer or smart device. This software acts as a
phone interface, allowing users to dial numbers and carry out other
phone related functions via a screen (such as a computer or smartphone)
using a mouse, keypad or keyboard.

Softphone applications may be downloaded from a variety of providers,
and are easily configured to become seamless components of the
phone.systems™ PBX. phone.systems™ is compatible with all SIP-compliant
softphones, including the phone.systems™ softphone which is highly
integrated into phone.systems™.

The SIP Account contact method is used to add softphones as a component
of phone.systems™ (see the section :ref:`SIP Accounts <ps3_sip_accounts>`
for details). The SIP credentials such as username, password and domain
that are required for configuring a SIP device are automatically
generated by phone.systems™.

To view and copy these credentials, edit the :ref:`SIP Account Contact Method <ps3_sip_accounts>`.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** SIP Accounts Credentials

The full list of SIP credentials are displayed, together with the
current status of the SIP device (**Offline** or **Online**).

Clicking on the |softphonesinline| icon next to the Username, Password and Domain
fields copies the configuration data to a clipboard for convenient use
in configuring the SIP device.

Once the softphone is configured with the required credentials and the
SIP account has been activated on that device, then that softphone will
be automatically be connected to phone.systems™ and is usable as an
integrated end-device.

.. note:: If this softphone is also to be used for outbound calling, then the **Enable outbound calls** option must be enabled in the contact method configuration screen shown above.

.. |softphonesimg3| image:: ../assets/img/guide-v2/inline-img/copy_icon.jpg
   :class: inline-img
.. |softphonesinline| image:: ../assets/img/guide-v2/softphones/inline.png
   :class: inline-img
   :width: 30px
   :height: 30px



.. _ps3_users_index:

=====
Users
=====

The **Users** menu in the **phone.systems™** PBX interface provides a streamlined way to manage users and their associated devices.

----

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`person` **Users**
      :link: users
      :link-type: doc
      :text-align: left

      Create, edit, filter, and manage user profiles.

   .. grid-item-card:: :octicon:`device-mobile` **App Devices**
      :link: app-devices
      :link-type: doc
      :text-align: left

      View, download, and manage devices registered via the phone.systems™ app.

.. toctree::
  :maxdepth: 1
  :hidden:

  Users <users.rst>
  App Devices <app-devices.rst>


.. _ps3_users:

.. |br| raw:: html

    <br>

Users
=====

The **Users** section in the **Cloud PBX phone.systems™** interface allows you to:

- Create new user profiles
- Edit existing user profiles
- See user relations
- Filter users for easy navigation
- Import users from a CSV file
- Download users to a CSV file
- Send or resend invitations to the phone.systems™ app
- Delete users

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Users Menu Overview

----

.. raw:: html

   <br>

User Interface Elements
-----------------------

The filter bar at the top of the user list allows you to filter users by specific criteria. Available filter options include:

- **Full Name**
- **Job Title**
- **Department**
- **Email**
- **Time Schedule**
- **Call Flow**
- **CRM User**

Click the **Filter** button to apply the selected criteria and refine the user list.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 1.** Filter Bar

The table displays a list of users with the following columns:

+-------------------+---------------------------------------------------------+
| **Field**         | **Description**                                         |
+===================+=========================================================+
| **Avatar**        | The user's assigned avatar.                             |
+-------------------+---------------------------------------------------------+
| **First Name**    | The first name of the user.                             |
+-------------------+---------------------------------------------------------+
| **Last Name**     | The last name of the user.                              |
+-------------------+---------------------------------------------------------+
| **Job Title**     | The job title of the user.                              |
+-------------------+---------------------------------------------------------+
| **Department**    | The department of the user.                             |
+-------------------+---------------------------------------------------------+
| **Email**         | The user’s email address.                               |
+-------------------+---------------------------------------------------------+
| **Time Schedule** | The :ref:`time schedule <ps3_create_time_schedule>`     |
|                   | assigned to the user.                                   |
+-------------------+---------------------------------------------------------+
| **Call Flows**    | Specifies the :ref:`call flow <ps3_call_flows>`         |
|                   | to which the user is assigned.                          |
+-------------------+---------------------------------------------------------+
| **CRM User ID**   | Specifies the CRM user ID if assigned to a CRM.         |
+-------------------+---------------------------------------------------------+
| **Invitations**   | Shows if the user has pending invitations to the        |
|                   | **phone.systems™** app.                                 |
+-------------------+---------------------------------------------------------+
| **Devices**       | Number of devices registered by the user in the         |
|                   | **phone.systems™** app.                                 |
+-------------------+---------------------------------------------------------+
| **SIP Accounts**  | Number of SIP account contact methods assigned to       |
|                   | the user.                                               |
+-------------------+---------------------------------------------------------+
|**PSTN Forwarding**| Number of PSTN Forwarding contact methods assigned      |
|                   | to the user.                                            |
+-------------------+---------------------------------------------------------+
|**SIP Forwarding** | Number of SIP Forwarding contact methods assigned to    |
|                   | the user.                                               |
+-------------------+---------------------------------------------------------+

.. figure:: https://doc.didww.com/_images/fig10.png
  :figclass: align-center

  **Fig. 2.** User List

.. note:: You can edit the table columns directly by either double-clicking the cell or clicking the pencil icon. This functionality is available for columns where the pencil icon appears when hovering over the cell.

The **Actions** menu for each user is accessible by clicking the three dots on the right side of the user row. This menu provides options to:

- Edit the user
- Send an invitation or resend an invitation to the phone.systems™ application
- Delete the user

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 3.** Actions Menu

----

.. raw:: html

   <br>

.. _ps3_users_create_new:

Create a New User
-----------------

To create a new user, follow these steps:

1. **Click on the Add New User button:**

In the bottom right corner of the Users section, click on the |+-symbol| button.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 1.** Creating A New User

2. **Fill in the User Details:**

A form will appear where you can optionally upload a **custom avatar**:

1. Click the |upload| icon.
2. Choose the image file you want to use as your avatar.
3. Use the slider to adjust the size and position of the image.
4. Click **Submit** to save your changes.

.. note::
    - Supported image formats are **.jpeg** and **.png**.
    - If no custom avatar is uploaded, the system will automatically assign a default avatar (the user's initials).
    - The avatars are synced with the mobile application.

.. figure:: https://doc.didww.com/_images/gif1.gif
  :figclass: align-center

  **Fig. 2.** Add a custom avatar

Then enter the following **User Details** and **Contact Information**:

- **First name**
- **Last name**
- **Department**
- **Job title**
- **Time Schedule**
- **Email**

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :width: 30%

  **Fig. 3.** User Details and Contact Information

Additionally you may select whether you want to set up a dedicated application line for the user by using the **Configure application line in the next step** toggle.

3. **Configuring the Application Line:**

Select the **Configure application line in the next step** toggle and click **Next**.

.. figure:: https://doc.didww.com/_images/fig11.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 4.** Configure Application Line Toggle

Configure the App Configuration Contact Method by entering the inbound, outbound, and call recording settings for your application:

.. tab-set::
   :class: my-tabs

   .. tab-item:: **Inbound Calls**

      .. list-table::
         :widths: 20 90
         :header-rows: 0

         * - **DID Numbers**
           - Select one or more DID numbers to receive inbound calls.

             .. note::
                If no DID numbers are available, refer to :ref:`Configure DID Number with phone.systems™ <ps3_prerequisites>` or :ref:`Add Third Party Phone Numbers <ps3_add_3rd_party_phone_numbers>`.
         * - **Internal Number**
           - Select one or more internal numbers to receive inbound calls.

             .. note::
                If no internal numbers are available, refer to :ref:`Create Internal Numbers Documentation <ps3_create_internal_numbers>`.
         * - **When Unavailable**
           - Specify the forwarding behavior when the destination is unavailable.

   .. tab-item:: **Outbound Calls**

      .. list-table::
         :widths: 25 75
         :header-rows: 0

         * - **Enable External Outbound Calls**
           - Enable or disable external outbound calling functionality.
         * - **Caller IDs**
           - Select the caller IDs to be used for external outbound calls.

             .. note::
                This option becomes available only when external outbound calling is enabled.
         * - **Internal Caller ID**
           - Define the caller ID to be used for internal calls.

             .. note::
                If no internal numbers are available, refer to :ref:`Create Internal Numbers Documentation <ps3_create_internal_numbers>`.
         * - **Internal Announcement**
           - Select the announcement audio message for internal calls.

             .. note::
                To upload audio files, refer to :ref:`Audio Files Documentation <ps3_audio_files>`.
         * - **External Announcement**
           - Select the announcement audio message for external calls.

   .. tab-item:: **Call Recording**

      .. list-table::
         :widths: 30 75
         :header-rows: 0

         * - **Delivery Methods**
           - Choose how call recordings are delivered.

             .. note::
                To configure delivery methods, refer to :ref:`Delivery Methods Documentation <ps3_delivery_methods>`.
         * - **Inbound Internal**
           - Toggle to enable recording of inbound internal calls.
         * - **Inbound External**
           - Toggle to enable recording of inbound external calls.
         * - **Outbound Internal**
           - Toggle to enable recording of outbound internal calls.
         * - **Outbound External**
           - Toggle to enable recording of outbound external calls.
         * - **Record On Demand**
           - Allows users to initiate recording via a dialing command.

             .. note::
                To enable on-demand call recording, configure a :ref:`feature code <ps3_settings_feature_codes>`.

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center

  **Fig. 5.** Application Line Configuration

After filling in all the required information, click the **Save** button at the bottom of the form to create the new user. The new user will now appear in the **users** list.

.. note:: An :ref:`App Configuration contact method <ps3_app_configurations>` is automatically created for each user and appears under the **App Configurations** tab in the **Contact Methods** menu.

----

.. raw:: html

   <br>

.. _ps3_users_edit:

Editing Users
-------------

To edit an existing user, follow these steps:

1. Click the **Actions** button next to the user you want to edit.
2. Select **Edit** from the dropdown menu.

   .. figure:: https://doc.didww.com/_images/fig3.png
      :figclass: align-center
      :alt: Actions menu.
      :width: 80%

      **Fig. 1.** Actions menu.

3. In the **Edit User** screen, update the required fields:

   - **User details** – Edit first name, last name, department, job title, and time schedule.
     You can also change the **avatar** by clicking |upload| to add a new picture, or |delete| to remove the current one and revert to the default.
   - **Contact information** – Update the user’s email address.
   - **Application settings** – Adjust the active app limit for the user or send an invitation to the phone.systems™ app.

   .. tip:: To set the **Active app limit** globally for all users, go to :ref:`App Activation Settings <ps3_app_activation_settings>`.

4. Click **Save** to apply the changes, or **Cancel** to discard them.

   .. figure:: https://doc.didww.com/_images/fig13.png
      :figclass: align-center
      :alt: Edit user screen.
      :width: 35%

      **Fig. 2.** Edit user screen

----

.. raw:: html

   <br>

User Relations
--------------

The **Relations** view provides an overview of all configurations associated with the user.

To access it, click the **Actions** button and select **Relations**.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 1.** Actions Menu

This view shows related call flows, contact methods, and app devices, helping administrators understand the user’s role in the system.

To navigate to the related section, click on the |gear| symbol next to the relation.

.. figure:: https://doc.didww.com/_images/fig24.png
   :figclass: align-center
   :alt: User Relations

   **Fig. 2.** User Relations

----

.. raw:: html

   <br>

Import Users From A CSV File
-------------------------------

To import new users, click on the |+-symbol| button and select **Import CSV**.

.. figure:: https://doc.didww.com/_images/fig16.png
  :figclass: align-center

  **Fig. 1.** Actions Button

In the **Import Users** screen, click to select a CSV file or use drag and drop the file onto the screen.

.. figure:: https://doc.didww.com/_images/fig17.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** File Select Button

Select and upload a CSV file from your storage.

.. figure:: https://doc.didww.com/_images/fig18.png
  :figclass: align-center

  **Fig. 3.** Selecting A File

.. warning:: A pop-up warning will inform you that the file has to be formatted correctly. Additionally you must agree that all users in this import are expecting to hear from your organization and that you have prior relationships with these users.

Click on the checkmark and **Submit** to proceed.

.. figure:: https://doc.didww.com/_images/fig19.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 4.** Pop-up Warning

After selecting the file, choose whether to **Merge Duplicates**. Selecting this option prevents uploading users that are already in your list.

Next, match the user properties in your CSV file to the phone.systems™ properties.

.. note:: The only mandatory property is **First Name**

.. figure:: https://doc.didww.com/_images/fig20.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 5.** Matching User Properties

Once the user properties are matched, click **Next** to upload your users.

.. figure:: https://doc.didww.com/_images/fig21.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 6.** Uploading Users

**CSV file format example:**

.. list-table:: CSV File Format Example
   :header-rows: 1
   :widths: auto

   * - **First Name**
     - **Last Name**
     - **Job Title**
     - **Email**
   * - Mike
     - Brown
     - Sales representative
     - ``mike.brown@sales.com``
   * - Pete
     - Smith
     - Technical support specialist
     - ``pete.smith@support.com``
   * - Jane
     - Smith
     - Customer service representative
     - ``jane.smith@customerservice.com``

.. note:: The CSV file format supports only **comma-separated** values.

----

.. raw:: html

   <br>

Download users to a CSV file
----------------------------

To download existing users to a CSV file, click on the **Download** symbol at the top right of the UI.

.. figure:: https://doc.didww.com/_images/fig14.png
  :figclass: align-center

  **Fig. 1.** Download Symbol

A download pop-up screen will be presented. Select the file name and the location where the file will be saved and click **Save**.

.. figure:: https://doc.didww.com/_images/fig15.png
  :figclass: align-center

  **Fig. 2.** Downloading Users

----

.. raw:: html

   <br>

.. _ps3_users_user_invite:

Send or resend invitations to the phone.systems™ app
------------------------------------------------------

1. Go to the **Users** menu in the phone.systems™ dashboard.
2. Find the user and click the **Actions** button.
3. Select **Send Invite to App** or **Resend Invite to App**.

.. note::
   * If the **Send Invite to App** button is not active, it means the user does not have an email address assigned.
     Please ensure that the user's **Contact Information** includes a valid email address to enable the invitation.

   * Resending an invitation **does not** generate a new authentication token or log the user out. If the user is already logged in, their session remains active.
   * To remove a user’s session (for example, after a lost device or access change), see :ref:`Deleting App Device Users guide <ps3_app_devices_delete>`.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 1.** App Device Invitation

----

.. raw:: html

   <br>
.. _ps3_users_deleting:

Deleting Users
-----------------

To delete users, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

If the selected user has any **relations**, the **Delete User** dialog shows a warning banner and a **relations counter**. Click the counter to view the full list of related items.

To permanently delete the user and all related items, enable the **Delete user(s) and all relations** toggle, then click **Delete**.

.. note::
   Deleting a user also deletes all associated relations. If you prefer not to delete these relations, close the dialog and unlink them first.

.. figure:: https://doc.didww.com/_images/fig12.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** Delete User dialog

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |upload| image:: /phone-systems/assets/img/guide-v2/users/upload.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |delete| image:: /phone-systems/assets/img/guide-v2/users/delete.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _ps3_app_devices:

.. |br| raw:: html

    <br>

===========
App Devices
===========

The **App Devices** section of the phone.systems™ interface allows you to download, review, and delete **App Devices**. The users will appear in the UI once the phone.systems™ application is activated on a device.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center

  **Fig. 1.** App Devices Menu Overview

----

.. raw:: html

   <br>

User Interface Elements
------------------------

The main area displays a list of **App Devices** with the following columns:

+-------------+----------------------------------------------------------------------------------------------------------------------------+
| Field       | Description                                                                                                                |
+=============+============================================================================================================================+
| User        | Displays the names of the users who have **App Devices** registered in the system.                                         |
+-------------+----------------------------------------------------------------------------------------------------------------------------+
| OS          | Shows the operating system used by each device.                                                                            |
+-------------+----------------------------------------------------------------------------------------------------------------------------+
| App Version | Indicates the version of the application installed on each device.                                                         |
+-------------+----------------------------------------------------------------------------------------------------------------------------+
| Date Created| Shows the timestamp when each **App Device** was registered in the system. The format is `YYYY-MM-DD HH:MM:SS`.            |
+-------------+----------------------------------------------------------------------------------------------------------------------------+

----

.. raw:: html

   <br>

Downloading App Device Users
-----------------------------

To download existing App Device Users to a CSV file, click on the **Download** symbol at the top right of the UI.

.. figure:: https://doc.didww.com/_images/fig22.png
  :figclass: align-center

  **Fig. 1.** Download Button

A download pop-up screen will be presented. Select the file name and the location where the file will be saved and click **Save**.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center

  **Fig. 2.** Downloading App Device Users

----

.. raw:: html

   <br>

.. _ps3_app_devices_delete:

Deleting App Device Users
----------------------------

To Delete App Devices click on the |x-symbol| symbol on the right side of the active **App Device**.

.. figure:: https://doc.didww.com/_images/fig23.png
  :figclass: align-center

  **Fig. 1.** Delete App Devices

.. |x-symbol| image:: /phone-systems/assets/img/guide-v2/users/x-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. _ps3_contact_methods:

===============
Contact Methods
===============

The **Contact Methods** manages the contacts and contact methods used by phone.systems™. Specifically, the entries in the **Contact Methods** serve to list the destinations (such as people and departments) to which incoming calls are redirected, and also the methods by which these destinations are contacted.

It’s important to note that  **Contact Methods** can be pre-configured before adding objects like **Ring Groups**, which rely on these contacts for call forwarding, to the workspace.

----

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`device-mobile` **App Configurations**
      :link: app-configurations
      :link-type: doc
      :text-align: left

      Configure app settings, assign numbers, manage devices, and send invitations for phone.systems™ app access.

   .. grid-item-card:: :octicon:`rss` **SIP Accounts**
      :link: sip-accounts
      :link-type: doc
      :text-align: left

      Set up and manage SIP accounts to connect SIP-enabled devices and applications for calling.

   .. grid-item-card:: :octicon:`globe` **PSTN Forwarding**
      :link: pstn-routes
      :link-type: doc
      :text-align: left

      Configure PSTN forwarding to route calls to external telephone numbers worldwide.

   .. grid-item-card:: :octicon:`broadcast` **SIP Forwarding**
      :link: sip-forwarding
      :link-type: doc
      :text-align: left

      Enable SIP forwarding to redirect calls to specific SIP endpoints or servers.

   .. grid-item-card:: :octicon:`mail` **Emails**
      :link: emails
      :link-type: doc
      :text-align: left

      Set up email notifications for voicemails, missed calls, and user alerts.

   .. grid-item-card:: :octicon:`zap` **Actions**
      :link: actions
      :link-type: doc
      :text-align: left

      Edit, delete, view relations, or download existing contact methods to a CSV file.

.. toctree::
  :maxdepth: 1
  :hidden:

  App Configurations <app-configurations.rst>
  SIP Accounts <sip-accounts.rst>
  PSTN Forwarding <pstn-routes.rst>
  SIP Forwarding <sip-forwarding.rst>
  Emails <emails.rst>
  Actions <actions.rst>


.. |br| raw:: html

   <br />

.. _ps3_app_configurations:

==================
App Configurations
==================

The **App Configurations** in phone.systems™ automatically links to all app devices. It allows you to assign internal and phone numbers for outbound caller ID and acts as the main group for associated devices under a contact.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create**
      :link: ps3_creating_app_configurations
      :link-type: ref
      :text-align: left

      Create an App Configuration contact method.

   .. grid-item-card:: :octicon:`pencil` **Edit**
      :link: ps3_app_configurations_edit
      :link-type: ref
      :text-align: left

      Edit an existing App Configuration contact method.

   .. grid-item-card:: :octicon:`mail` **Send or Resend Invite**
      :link: ps3_app_configurations_send_invite
      :link-type: ref
      :text-align: left

      Send or resend an invitation to connect the app device.

   .. grid-item-card:: :octicon:`eye` **View Relations**
      :link: ps3_app_configurations_relations
      :link-type: ref
      :text-align: left

      View relations of an App Configuration contact method.

   .. grid-item-card:: :octicon:`trash` **Delete**
      :link: ps3_app_configurations_delete
      :link-type: ref
      :text-align: left

      Delete an App Configuration contact method.

   .. grid-item-card:: :octicon:`download` **Download**
      :link: ps3_app_configurations_download
      :link-type: ref
      :text-align: left

      Download contact methods to a CSV file.

.. note::

   After editing or creating an App Configuration, you must send an invitation to the user so they can establish the connection to the phone.systems™ app. For details, see :ref:`Send or resend invite to phone.systems™ app <ps3_app_configurations_send_invite>`.

----

.. raw:: html

    <br>

.. _ps3_creating_app_configurations:

Create and Configure App Contact Methods
============================================

Create and manage contact methods for the phone.systems™ application within the **App Configuration** section.
These contact methods are automatically linked to phone.systems™ users and enable the assignment of internal numbers and DID numbers for receiving inbound calls, as well as setting caller IDs and announcements for outbound calls. They also support call recording configuration and relations with call flows and app devices.

.. note::

    To enable calling functionality from the phone.systems™ application, each user must have an individually assigned App Configuration.

..  .. grid:: 2
       :gutter: 5

       .. grid-item-card:: **Create App Configuration for New Users**
          :link: ps3_creating_app_configurations_new_users
          :link-type: ref
          :text-align: center

          Learn how to create an app contact method |br| for new users.

       .. grid-item-card:: **Configure App Configuration for Existing Users**
          :link: ps3_creating_app_configurations_existing_users
          :link-type: ref
          :text-align: center

          Learn how to configure an app contact method |br| for existing users.

.. .. _ps3_creating_app_configurations_new_users:

..  Create App Configuration For New Users
    ------------------------------------------------------

    To create an app configuration contact method for a new user, follow these steps:

.. raw:: html

        <br>

Before You Begin
----------------

Before setting up an App Configuration, make sure all necessary components are ready to support call functionality:

    - **A DID number** – Required to enable inbound calling functionality. If not available, `purchase DID(s) from the Coverage page in the User Panel <https://my.didww.com/#/coverage>`_.
    - **An assigned phone.systems™ trunk** – Needed to establish voice connectivity for the user. For setup steps, see :ref:`Configure DID Numbers with phone.systems™ in the DIDWW User Panel <ps3_prerequisites>`.

.. raw:: html

    <br>

.. tab-set::
   :sync-group: appconfig
   :class: my-tabs

   .. tab-item:: *App Configuration for New Users*
      :sync: new-users

      .. raw:: html

         <br>

      Each user must have a distinct profile and a dedicated application line (App Configuration Contact Method) to facilitate call routing, identity assignment, and access to calling features within the phone.systems™ application.
      This ensures accurate association of internal numbers, caller ID, and recording policies for both inbound and outbound communications.

      .. raw:: html

            <h4 id="step-1-create-new-user">
                Step 1: Create a New User
                <a class="headerlink" href="?appconfig=new-users#step-1-create-new-user" title="Link to this heading">¶</a>
            </h4>

      1. Go to the **Users** menu and click the |+-symbol| button
      2. In the **Create New User** screen, enter:

         - **First Name** and **Last Name**
         - **Department** and **Job Title**
         - **Time Schedule** – Defines the user’s availability for call routing. Read more in :ref:`Time Schedules Documentation <ps3_time_schedules>`.

      4. Under **Contact Information**, provide the **Email** address.

         .. important::
             An email address is required to send the invitation and enable the user to connect with the phone.systems™ app.

      5. Enable **Configure application line in the next step**.
      6. Click **Next** to continue to the app configuration.

         .. figure:: https://doc.didww.com/_images/fig2.png
            :figclass: align-center
            :alt: Create User Screen

            **Fig. 1.** Create User Screen

   .. tab-item:: *App Configuration for Existing Users*
      :sync: existing-users

      .. raw:: html

         <br>

      Existing users may have app configuration contact methods that were created previously but remain unconfigured.
      Configuring the app configuration contact method allows you to assign inbound and outbound call settings and enables communication through the phone.systems™ application.

      .. raw:: html

            <h4 id="step-1-edit-existing-user">
                Step 1: Locate the App Configuration
                <a class="headerlink" href="?appconfig=existing-users#step-1-edit-existing-user" title="Link to this heading">¶</a>
            </h4>

      1. Go to the **Contact Methods** menu and select the **App Configurations** tab.
      2. Click the |actions| button next to the desired contact method and choose **Edit**.

         .. figure:: https://doc.didww.com/_images/fig4.png
            :figclass: align-center
            :alt: Edit App Configuration

            **Fig. 1.** Edit App Configuration

.. _ps3_creating_app_configurations_existing_users_step2:

Step 2: Configure the App Configuration Contact Method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. tab-set::
   :class: my-tabs

   .. tab-item:: **Inbound Calls**

      .. list-table::
         :widths: 20 90
         :header-rows: 0

         * - **DID Numbers**
           - Select one or more DID numbers to receive inbound calls.

             .. note::
                If no DID numbers are available, refer to :ref:`Configure DID Number with phone.systems™ <ps3_prerequisites>` or :ref:`Add Third Party Phone Numbers <ps3_add_3rd_party_phone_numbers>`.
         * - **Internal Number**
           - Select one or more internal numbers to receive inbound calls.

             .. note::
                If no internal numbers are available, refer to :ref:`Create Internal Numbers Documentation <ps3_create_internal_numbers>`.
         * - **When Unavailable**
           - Specify the desired call forwarding behavior when the destination is unavailable:

              - **Do Nothing** - The call will be terminated.
              - **Route To Voicemail** - The call will be forwarded to voicemail. You must select the voicemail audio that will be played to the caller.

              .. note:: The **Route to Voicemail** option requires the user to have either an :ref:`emails contact method <ps3_emails>` configured or :ref:`cloud storage <ps3_cloud_storage_integrations>` enabled to ensure successful voicemail delivery.

   .. tab-item:: **Outbound Calls**

      .. list-table::
         :widths: 25 75
         :header-rows: 0

         * - **Enable External Outbound Calls**
           - Enable or disable external outbound calling functionality.
         * - **Caller IDs**
           - Select the caller IDs to be used for external outbound calls.

             .. note::
                This option becomes available only when external outbound calling is enabled.
         * - **Internal Caller ID**
           - Define the caller ID to be used for internal calls.

             .. note::
                If no internal numbers are available, refer to :ref:`Create Internal Numbers Documentation <ps3_create_internal_numbers>`.
         * - **Internal Announcement**
           - Select the announcement audio message for internal calls.

             .. note::
                To upload audio files, refer to :ref:`Audio Files Documentation <ps3_audio_files>`.
         * - **External Announcement**
           - Select the announcement audio message for external calls.

   .. tab-item:: **Call Recording**

      .. list-table::
         :widths: 30 75
         :header-rows: 0

         * - **Delivery Methods**
           - Choose where call recordings are delivered. Available delivery methods include:

              - Email.
              - Dropbox.
              - FTP.
              - SFTP.
              - Google Drive.
              - OneDrive.
              - Default phone.systems™ :ref:`cloud storage <ps3_phonesystems_cloudstorage>`.

              .. tip::
                 - If the required delivery method has not previously been configured, a delivery method may be added by navigating to the :ref:`Delivery Methods <ps3_delivery_methods>` menu.
                 - When using the default **phone.systems™** cloud storage as the delivery method, call recordings will appear in the :ref:`call flow CDRs <ps3_call_flow_cdrs_recording>` and the :ref:`phone.systems™ app call attachments <ps3_appplication_call_history_attachments>`, providing a centralized and convenient way to review call recordings alongside other call activities.

         * - **Inbound Internal**
           - Toggle to enable recording of inbound internal calls.
         * - **Inbound External**
           - Toggle to enable recording of inbound external calls.
         * - **Outbound Internal**
           - Toggle to enable recording of outbound internal calls.
         * - **Outbound External**
           - Toggle to enable recording of outbound external calls.
         * - **Record On Demand**
           - Allows users to initiate recording via a dialing command.

             .. note::
                To enable on-demand call recording, configure a :ref:`feature code <ps3_settings_feature_codes>`.

.. grid:: 1 1 1 3

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/figx1.png
           :figclass: align-center
           :alt: Inbound Calls

           **Fig. 2.** Inbound Calls

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/figx2.png
           :figclass: align-center
           :alt: Outbound Calls

           **Fig. 3.** Outbound Calls

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/figx3.png
           :figclass: align-center
           :alt: Call Recording

           **Fig. 4.** Call Recording

Click **Save** to apply the configuration.

----

.. raw:: html

    <br>

.. _ps3_app_configurations_send_invite:

Send invite to phone.systems™ app
====================================================

1. Go to the **Users** menu in the phone.systems™ dashboard.
2. Find the user and click the **Actions** button.
3. Select **Send Invite to App** or **Resend Invite to App**.

.. note::
   * If the **Send Invite to App** button is not active, it means the user does not have an email address assigned.
     Please ensure that the user's **Contact Information** includes a valid email address to enable the invitation.

   * Resending an invitation **does not** generate a new authentication token or log the user out. If the user is already logged in, their session remains active.
   * To remove a user’s session (for example, after a lost device or access change), see :ref:`Deleting App Device Users guide <ps3_app_devices_delete>`.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 5.** App Device Invitation

----

.. raw:: html

    <br>

.. _ps3_app_configurations_edit:

Edit App Configurations Contact Methods
=======================================

1. Go to the **Contact Methods** menu and open the **App Configurations** tab.
2. Locate the contact method you want to edit.
3. Click the |actions| button next to the contact method and select **Edit** from the menu.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: Edit Actions Button.

   **Fig. 6.** Edit Actions Button

4. In the **Edit App Configuration** window, apply the required changes.
5. Click **Save** to confirm and apply your updates.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :alt: Edit App Configuration Contact Method.

  **Fig. 7.** Edit App Configuration Contact Methods

Unassign DID Numbers
-----------------------

1. Open the **Edit** screen for the selected App Configuration.
2. In the **Inbound Calls** section, locate the currently assigned DID number(s).
3. Click the **x** icon next to the DID number you wish to remove.
4. Click **Save** to confirm and apply the changes.

.. figure:: https://doc.didww.com/_images/fig8.png
   :figclass: align-center
   :alt: Unassign DID Number

   **Fig. 8.** Unassign a DID Number

----

.. raw:: html

    <br>

.. _ps3_app_configurations_relations:

App Configuration Relations
============================

The **Relations** view provides an overview of configurations linked to a selected App Configuration Contact Method, including associations with **Call Flows**, **Contact Methods** and **App Devices**.

1. Navigate to the **Contact Methods** menu and open the **App Configurations** tab.
2. Locate the desired contact method.
3. Click the |actions| button and select **Relations**.

.. figure:: https://doc.didww.com/_images/fig6.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 9.** Actions Menu

To access a related item, click the |gear| icon next to it. You will be redirected to the respective edit page for that configuration.

.. note:: If no associated Call Flows or App Devices exist, the message **"No relations"** will be displayed under the corresponding section.

.. figure:: https://doc.didww.com/_images/fig7.png
   :figclass: align-center
   :alt: Contact Methods Relations

   **Fig. 10.** App Configurations Contact Method Relations

----

.. raw:: html

    <br>

.. _ps3_app_configurations_delete:

Delete App Configurations
==========================

App Configuration Contact Methods **cannot** be deleted directly from the **Contact Methods** menu.

To remove an App Configuration Contact Method, the associated user must be deleted. Deleting the user will also remove their corresponding App Configuration.

    .. grid:: 1 1 1 2
       :gutter: 5

       .. grid-item-card:: **Delete Users**
          :link: ps3_users_deleting
          :link-type: ref
          :text-align: center

          Learn how to delete users, which also removes their associated App Configuration Contact Methods.

----

.. raw:: html

    <br>

.. _ps3_app_configurations_download:

Download App Configurations to a CSV File
==========================================

1. Navigate to the **Contact Methods** menu **App Configurations** tab.
2. Click the **Download** button at the top right corner.

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center
  :alt: Download Button for App Configurations Contact Methods

  **Fig. 11.** Download Button for App Configurations Contact Methods

3. A pop-up window will appear, allowing you to specify the file name and destination for saving the CSV file.
4. Click **Save** to export and download the CSV file containing the list of App Configuration Contact Methods.

.. figure:: https://doc.didww.com/_images/fig10.png
  :figclass: align-center
  :alt: Downloading App Configurations Contact Methods to CSV File

  **Fig. 12.** Downloading App Configurations Contact Methods to CSV File

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |actions| image:: ../assets/img/guide-v2/contact_methods/app/actions.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _ps3_sip_accounts:

============
SIP Accounts
============

The **SIP Accounts** section of the **Contact Method** menu in the **Cloud PBX phone.systems™** interface allows you to:

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create**
      :link: ps3_creating_sip_accounts
      :link-type: ref
      :text-align: left

      Create SIP Account contact methods.

   .. grid-item-card:: :octicon:`pencil` **Edit**
      :link: ps3_edit
      :link-type: ref
      :text-align: left

      Edit SIP Account contact methods.

   .. grid-item-card:: :octicon:`eye` **Relations**
      :link: ps3_edit_relations
      :link-type: ref
      :text-align: left

      View relations of SIP Account contact methods.

   .. grid-item-card:: :octicon:`trash` **Delete**
      :link: ps3_delete
      :link-type: ref
      :text-align: left

      Delete SIP Account contact methods.

   .. grid-item-card:: :octicon:`download` **Download**
      :link: ps3_download
      :link-type: ref
      :text-align: left

      Download SIP Account contact methods to a CSV file.

----

.. _ps3_creating_sip_accounts:

Creating SIP Account Contact Methods
====================================

To create a SIP Account **Contact Method**, click the |+-symbol| button to open the SIP Account **Contact Method** creation screen.

.. figure:: https://doc.didww.com/_images/fig8.webp
  :figclass: align-center

  **Fig. 1.** SIP Accounts Contact Methods

The **SIP Account** configuration window contains five sections:

1. General
''''''''''

- The **Name** field allows you to enter a descriptive name that identifies the contact method.
- The **User** field selects the user to whom the **SIP Account Contact Method** will be assigned.

.. figure:: https://doc.didww.com/_images/fig21.webp
  :figclass: align-center
  :figwidth: 45%

  **Fig. 1.** General Configuration

.. _ps3_sip_accounts_inbound_calls:

2. Inbound calls
''''''''''''''''

The **Inbound Calls** section allows you to configure the DID and internal numbers associated with the SIP account. You can also set up a fallback routing option to voicemail.

1. Select one or more **DID Numbers** that will forward the calls to the new **SIP Account**.
2. Select one or more the **Internal Numbers** that will forward internal the calls to the new **SIP Account**.
3. Select what happens when the SIP Account contact is not available:

    - **Do Nothing** - The call will be terminated.
    - **Route To Voicemail** - The call will be forwarded to voicemail. You must select the voicemail audio that will be played to the caller.

    .. note:: The **Route to Voicemail** option requires the user to have either an :ref:`emails contact method <ps3_emails>` configured or :ref:`cloud storage <ps3_cloud_storage_integrations>` enabled to ensure successful voicemail delivery.

.. figure:: https://doc.didww.com/_images/fig22.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 2.** Inbound Calls

.. _ps3_sip_accounts_outbound_calls:

3. Outbound calls
'''''''''''''''''

The **Outbound Calls** section allows you to configure internal and external **Caller IDs** and call announcements.

Outbound calling from this SIP device is disabled by default, but you can enable it in the settings.

1. If outbound calling is enabled, you must select an **External Caller ID**, which defines the phone number displayed as the **Caller ID** when making outbound calls. These **Caller IDs** can be chosen from a dropdown menu listing numbers previously added to **phone.systems™** via the **Phone Number** option under the **Settings** menu. It is recommended to add phone numbers before configuring **SIP Account** contact methods.
2. Optional **Internal Caller IDs** can be selected from a dropdown menu listing the extensions configured for **Internal Number** objects currently in the workspace. These numbers are displayed as the **Caller ID** when making outbound calls to other extensions within the **phone.systems™** network.
3. An optional **Internal Announcement** can be configured for outbound calls. This announcement is played to the called party when an outbound call is answered by another internal extension. Use it to provide information, greetings, or instructions for internal callers. Select an existing announcement or upload a new recording in Settings > Announcements.
4. An optional **External Announcement** can be configured for outbound calls. When an agent places an outbound call and the external party answers, the configured announcement is played to the recipient before the call continues. This can be used to provide a greeting, legal notice, or other relevant information. You can choose from existing announcements or upload a custom recording in Settings > Announcements.

.. figure:: https://doc.didww.com/_images/fig23.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 3.** Outbound Calls

.. _ps3_sip_accounts_call_recording:

4. Call Recording
'''''''''''''''''

The **SIP Account Contact Method** allows users to enable call recording and define the recording direction (inbound and/or outbound) for internal and external calls. Additionally, a **Record on Demand** feature is available, allowing users to activate call recording by dialing a predefined feature code.

1.  Choose where call recordings are delivered. Available delivery methods include:

       - Email.
       - Dropbox.
       - FTP.
       - SFTP.
       - Google Drive.
       - OneDrive.
       - Default phone.systems™ :ref:`cloud storage <ps3_phonesystems_cloudstorage>`.

       .. tip::
          - If the required delivery method has not previously been configured, a delivery method may be added by navigating to the :ref:`Delivery Methods <ps3_delivery_methods>` menu.
          - When using the default **phone.systems™** cloud storage as the delivery method, call recordings will appear in the :ref:`call flow CDRs <ps3_call_flow_cdrs_recording>` providing a centralized and convenient way to review call recordings alongside other call activities.

2. The **Inbound Internal** option records calls made between internal extensions.
3. The **Inbound External** option records calls received from external numbers to internal extensions.
4. The **Outbound Internal** option records calls made between internal extensions.
5. The **Outbound External** option records calls made from internal extensions to external numbers.
6. If the **Record on Demand** feature is enabled, you must define a dialing feature code to activate call recording.

.. note::
   - Call recordings are not uploaded to **phone.systems™** servers, and **phone.systems™** does not read, process, or store your recordings permanently if cloud storage is not enabled.
   - Call recordings sent via email may not be delivered due to file size limitations on the recipient's email server. If the destination server rejects the file, it will be unrecoverable.
   - The approximate file size of call recordings is **7 MB per hour**. Users should consider this when selecting a **Delivery Method**.

.. figure:: https://doc.didww.com/_images/fig24.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 4.** Call Recording

5. Advanced
'''''''''''

In the advanced settings, you can configure **Allowed IPs**, codecs, media types, and transport protocols.

The **Enable Allowed IPs** option, when activated, restricts device registration to specific IP addresses listed in the **Allowed IPs** field. This prevents unauthorized registration from unlisted IP addresses, enhancing security. If this option is disabled, registration from any IP address is permitted.

    - When enabled, the **Allowed IPs** list must include the IP addresses used for device registration. Both **IPv4** and **IPv6** addresses are supported, with addresses separated by the **SPACE** character. You can also define IP ranges using **CIDR (Classless Inter-Domain Routing)** notation.
    - Clicking the **Allowed IPs** input box lets you add or remove IP addresses. Each listed IP address has an |x| icon at the end. Clicking this icon deletes the corresponding IP address.

.. figure:: https://doc.didww.com/_images/fig31.png
   :figclass: align-center
   :figwidth: 45%

   **Fig. 5.** Allowed IPs

You can select the **Codecs** supported by this SIP account. Multiple codecs can be added from the dropdown list, with the following options available:

    - **OPUS**
    - **G722**
    - **PCMU**
    - **PCMA**
    - **G729**
    - **GSM**
    - **telephone-event**

.. important:: The **telephone-event** codec must be included in the list of **Allowed Codecs** if interactive menus or feature codes requiring digit input are to be used.

The **Media Types** field allows you to select the network protocol used for delivering audio and video over IP networks. The following options are available:

    - **RTP**
    - **SRTP-SDES**
    - **SRTP-DTLS**
    - **SRTP-ZRTP**

The **Transport Protocol** field allows you to select the protocol used for communication between **phone.systems™** and the end user's IP phone or softphone application. Multiple transport protocols can be selected, with the following options available:

    - **TCP**
    - **UDP**
    - **TLS**
    - **WSS**

.. figure:: https://doc.didww.com/_images/fig25.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 6.** Advanced

Click **Save** to create the SIP account.

Once created, you can view and copy the SIP account credentials by editing the **SIP Account Contact Method**.

.. figure:: https://doc.didww.com/_images/edit.webp
  :figclass: align-center
  :figwidth: 45%

  **Fig. 7.** SIP Accounts Credentials

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |x| image:: /phone-systems/assets/img/guide-v2/contact_methods/inline.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_pstn_routes:

===============
PSTN Forwarding
===============

The **PSTN Forwarding** section of the **Contact Method** menu in the **Cloud PBX phone.systems™** interface allows you to:

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create**
      :link: ps3_creating_pstn_routes
      :link-type: ref
      :text-align: left

      Create PSTN Forwarding contact methods.

   .. grid-item-card:: :octicon:`pencil` **Edit**
      :link: ps3_edit
      :link-type: ref
      :text-align: left

      Edit PSTN Forwarding contact methods.

   .. grid-item-card:: :octicon:`eye` **Relations**
      :link: ps3_edit_relations
      :link-type: ref
      :text-align: left

      View relations of PSTN Forwarding contact methods.

   .. grid-item-card:: :octicon:`trash` **Delete**
      :link: ps3_delete
      :link-type: ref
      :text-align: left

      Delete PSTN Forwarding contact methods.

   .. grid-item-card:: :octicon:`download` **Download**
      :link: ps3_download
      :link-type: ref
      :text-align: left

      Download PSTN Forwarding contact methods to a CSV file.

----

.. _ps3_creating_pstn_routes:

Creating PSTN Forwarding Contact Methods
''''''''''''''''''''''''''''''''''''''''

To create a **PSTN Forwarding Contact Method**, click the |+-symbol| button to open the **PSTN Forwarding Contact Method** creation screen.

.. figure:: https://doc.didww.com/_images/fig3.webp
  :figclass: align-center
  :alt: PSTN Forwarding Contact Methods

  **Fig. 1.** PSTN Forwarding Contact Methods

The **PSTN Forwarding** configuration window contains two sections:

**1. General**

- The **Name** field allows you to enter a descriptive name that identifies the contact method.
- The **User** option allows you to select the user for the **Contact Method**.
- The **Phone Number** field requires the actual phone number (landline or mobile) to which incoming calls should be forwarded, in **E.164 format**: ``<CountryCode> <City/AreaCode> <LocalNumber>``. The country code is **1–3 digits long**, while the length of the city/area code and local number may vary. For example, a phone number in **E.164 format** for **Minneapolis, US** is **16128884432**.
- The **Allow Call Transfer** toggle enables call transfers to other PSTN numbers when turned on.

   .. note:: Enabling **Allow Call Transfer** may incur additional per-minute charges for call transfers to another phone number.

.. figure:: https://doc.didww.com/_images/fig33.webp
  :figclass: align-center
  :width: 45%
  :alt: General Configuration

  **Fig. 1.** General Configuration

**2. Inbound Calls**

- **DID Number** specifies which DID numbers will perform PSTN forwarding.
- **Internal Number** specifies which internal numbers will perform PSTN forwarding.
- The **When Unavailable** option allows you to select how calls are forwarded when the PSTN destination is unavailable. You can select:

   - **Do Nothing**: The call ends if the PSTN destination does not respond.
   - **Route to Voicemail**: The call is routed to the selected voicemail audio message.

.. figure:: https://doc.didww.com/_images/fig34.png
   :figclass: align-center
   :alt: Inbound Calls
   :width: 45%

   **Fig. 2.** Inbound Calls

.. note:: You can edit, delete, or download contact methods. For more details, refer to the :ref:`actions page <ps3_edit_delete_download_contact_methods>`.

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_sip_forwarding:

==============
SIP Forwarding
==============

This **SIP Forwarding** section of the **Contact Method** menu in the **Cloud PBX phone.systems™** interface allows you to perform the following tasks:

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create**
      :link: ps3_creating_sip_forwarding
      :link-type: ref
      :text-align: left

      Create SIP Forwarding contact methods.

   .. grid-item-card:: :octicon:`pencil` **Edit**
      :link: ps3_edit
      :link-type: ref
      :text-align: left

      Edit SIP Forwarding contact methods.

   .. grid-item-card:: :octicon:`eye` **Relations**
      :link: ps3_edit_relations
      :link-type: ref
      :text-align: left

      View relations of SIP Forwarding contact methods.

   .. grid-item-card:: :octicon:`trash` **Delete**
      :link: ps3_delete
      :link-type: ref
      :text-align: left

      Delete SIP Forwarding contact methods.

   .. grid-item-card:: :octicon:`download` **Download**
      :link: ps3_download
      :link-type: ref
      :text-align: left

      Download SIP Forwarding contact methods to a CSV file.

----

.. _ps3_creating_sip_forwarding:

Creating SIP Forwarding Contact Methods
-----------------------------------------

To create a SIP Forwarding **Contact Method**, click the |+-symbol| symbol, which will open the SIP Forwarding **Contact Method** creation screen.

.. figure:: https://doc.didww.com/_images/sip_forwarding.webp
  :figclass: align-center
  :alt: SIP Forwarding Contact Methods

  **Fig. 1.** SIP Forwarding Contact Methods

The SIP Forwarding configuration window contains two sections:

1. General
''''''''''

- The **Name** field allows you to enter a descriptive name that identifies the contact method.
- **User** option allows you to select the user for the **Contact Method**.
- **Username** field requires the user part of the SIP URI used for SIP Forwarding (e.g., ``123456789`` in ``sip:123456789@example.com``).
- **Domain** field requires the domain part of the SIP URI used for SIP Forwarding (e.g., ``example.com`` in ``sip:123456789@example.com``).
- **Port** field allows you to specify the port number used for the SIP connection.
- **Network Protocol** option allows you to choose the communication protocol.
- **Process 30X Redirects** toggle enables processing 30X SIP redirects when turned on.

   .. note:: Enabling "Process 30X Redirect" option may impact call routing based on SIP response codes.

.. figure:: https://doc.didww.com/_images/fig35.webp
  :figclass: align-center
  :figwidth: 45%
  :alt: General Configuration

  **Fig. 2.** General Configuration

2. Inbound Calls
''''''''''''''''

The **Inbound Calls** section allows you to configure the DID and internal numbers associated with the SIP forwarding contact method, with the option to configure a fallback routing option to voicemail.

- **DID Number** specifies which DID numbers will perform the SIP forwarding.
- **Internal Number** specifies which internal numbers will perform the SIP forwarding.
- **When Unavailable** option allows you to select how calls are forwarded when the SIP destination is unavailable. You may select:

   - **Do Nothing**: The call is ended if the SIP destination is not responding.
   - **Route to Voicemail**: The call is routed to the selected voicemail audio message.

.. figure:: https://doc.didww.com/_images/fig36.png
  :figclass: align-center
  :figwidth: 45%
  :alt: Inbound Calls

  **Fig. 3.** Inbound Calls

3. Advanced
'''''''''''

You can select the **Codecs** supported by this SIP account. Multiple codecs can be added from the dropdown list, with the following options available:

    - **OPUS**
    - **G722**
    - **G729**
    - **PCMU**
    - **PCMA**
    - **telephone-event**

.. important:: The **telephone-event** codec must be included in the list of **Allowed Codecs** if interactive menus or feature codes requiring digit input are to be used.

The **Allowed Media Types** field specifies the network protocols permitted for transporting media streams (typically audio) during SIP sessions. The following options are available:

    - **RTP**
    - **SRTP-SDES**
    - **SRTP-DTLS**
    - **SRTP-ZRTP**

The **Default Media Type** defines which media transport protocol will be preferred when multiple options are available. It should match one of the values set in the **Allowed Media Types** list. For example:

    - **RTP**
    - **SRTP-SDES**
    - **SRTP-DTLS**
    - **SRTP-ZRTP**

The **Transport Protocol** field allows you to select the protocol used for communication between **phone.systems™** and the end user’s SIP device. Supported transport methods include:

    - **UDP**
    - **TCP**
    - **TLS**
    - **WSS**

.. figure:: https://doc.didww.com/_images/fig38.png
  :figclass: align-center
  :figwidth: 45%
  :alt: Advanced

  **Fig. 4.** Advanced

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_emails:

======
Emails
======

This **Emails** section of the **Contact Method** menu in the **Cloud PBX phone.systems™** interface allows you to perform the following tasks:

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create**
      :link: ps3_creating_emails
      :link-type: ref
      :text-align: left

      Create Email contact methods.

   .. grid-item-card:: :octicon:`pencil` **Edit**
      :link: ps3_edit
      :link-type: ref
      :text-align: left

      Edit Email contact methods.

   .. grid-item-card:: :octicon:`eye` **Relations**
      :link: ps3_edit_relations
      :link-type: ref
      :text-align: left

      View relations of Email contact methods.

   .. grid-item-card:: :octicon:`trash` **Delete**
      :link: ps3_delete
      :link-type: ref
      :text-align: left

      Delete Email contact methods.

   .. grid-item-card:: :octicon:`download` **Download**
      :link: ps3_download
      :link-type: ref
      :text-align: left

      Download Email contact methods to a CSV file.

----

.. _ps3_creating_emails:

Creating Email Contact Methods
'''''''''''''''''''''''''''''''

To create an Email **Contact Method**, click the |+-symbol| symbol, which will open the Email **Contact Method** creation screen.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Email Contact Methods

1. The **User** option allows you to select the user for the **Contact Method**.

2. The **Email** field requires the email address of the user to which notifications will be sent.

Once these details are entered, click on the **Save and Send Verification** button. A verification email will be sent to the specified email address, and the contact method will be activated upon successful verification.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 1.** General Configuration

----

Verification Process
''''''''''''''''''''

After saving the email **Contact Method**, you will receive a verification email at the provided email address.

To verify your email address, click the verification link in the email.

Once verified, the email contact method will be activated, and you will begin receiving notifications.

.. note:: To verify your domain automatically, visit :ref:`Domain Settings <ps3_domains>`.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 1.** Verified Contact Methods

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px



.. _ps3_edit_delete_download_contact_methods:

=======
Actions
=======

This section explains how to **edit**, **delete**, and **download** contact methods from the **Contact Methods** pages. These actions can be completed across all contact methods, including **App Configuration**, **SIP Accounts**, **PSTN Routes**, **SIP Forwarding**, and **Emails**.

The **Name** value helps you identify a contact method in Contact Methods lists and when performing actions.

----

.. raw:: html

   <br>

.. _ps3_edit:

Editing Contact Methods
-----------------------

To edit any **Contact Method**, follow these steps:

1. Navigate to the **Contact Methods** menu and locate the contact method you wish to edit.
2. Click on the **Actions** button next to the contact method and select **Edit** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig28.webp
  :figclass: align-center

  **Fig. 1.** Actions Menu for Editing

3. Update the **Name** or any other editable settings in the **Edit Contact Method** window.
4. After editing the required details, click **Save** to confirm your changes.

.. figure:: https://doc.didww.com/_images/edit.webp
  :figclass: align-center
  :figwidth: 45%

  **Fig. 2.** Editing Contact Methods

.. note:: You can edit the table columns directly by either double-clicking the cell or clicking the pencil icon. This functionality is available for columns where the pencil icon appears when hovering over the cell.

----

.. raw:: html

   <br>

.. _ps3_edit_relations:

Contact Methods and Relations
------------------------------

The **Relations** view provides an overview of all configurations associated with the contact methods.

To access the Relations view, select **Actions**, then choose **Relations**.

.. figure:: https://doc.didww.com/_images/fig28.webp
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 1.** Actions Menu

Depending on the contact method type, the following relations will be displayed:

- **App Configurations**: Displays related call flows and app devices.
- **SIP Accounts, PSTN Forwarding, and SIP Forwarding**: Displays related call flows.
- **Emails**: Displays related delivery methods and subscriptions.

To navigate to a related section, select the |gear| icon next to the relation.

.. figure:: https://doc.didww.com/_images/fig37.png
   :figclass: align-center
   :alt: Contact Methods Relations

   **Fig. 2.** Contact Methods Relations

----

.. raw:: html

   <br>

.. _ps3_delete:

Deleting Contact Methods
------------------------

To delete contact methods, click the **Actions** button next to the contact method and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig28.webp
  :figclass: align-center

  **Fig. 1.** Actions Menu

If the selected contact method has any **relations**, the **Delete Contact Method** dialog shows a warning banner and a **relations counter**. Click the counter to view the full list of related items.

To permanently delete the contact method and its related items, enable the **Delete and unlink relations** toggle, then click **Delete**.

.. note::
   Deleting a contact method also deletes and unlinks all associated relations. Unlinking these relations may disrupt connected services.
   If you prefer not to proceed, close the dialog and update or remove the connections manually.

.. figure:: https://doc.didww.com/_images/fig30.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 2.** Delete Contact Method dialog

----

.. raw:: html

   <br>

.. _ps3_download:

Downloading Contact Methods to a CSV File
-----------------------------------------

To download existing **Contact Methods** to a CSV file, follow these steps:

1. Navigate to the **Contact Methods** menu and select one of the contacts you want to download.
2. Click on the **Download** button located at the top right of the user interface.

.. figure:: https://doc.didww.com/_images/fig26.webp
  :figclass: align-center

  **Fig. 1.** Download Button for Contact Methods

3. A download pop-up screen will be displayed, prompting you to specify a file name and the location where the CSV file will be saved.
4. After providing the necessary information, click **Save** to download the CSV file containing the details of all contact methods.

.. figure:: https://doc.didww.com/_images/fig27.png
  :figclass: align-center

  **Fig. 2.** Downloading Contact Methods to CSV File

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _ps3_numbers:

=======
Numbers
=======

The phone.systems™ PBX allows you to configure third-party **Phone Numbers** and **Internal Numbers** for call handling.

----

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`number` **Phone Numbers**
      :link: phone-numbers
      :link-type: doc
      :text-align: left

      Add, edit, and manage phone numbers for inbound routing, caller ID, and related configurations.

   .. grid-item-card:: :octicon:`hash` **Internal Numbers**
      :link: internal-numbers
      :link-type: doc
      :text-align: left

      Create, edit, and manage internal extensions for routing, caller ID, and PBX configurations.

.. toctree::
  :maxdepth: 1
  :hidden:

  Phone Numbers <phone-numbers.rst>
  Internal Numbers <internal-numbers.rst>


.. _ps3_phone_numbers:

.. raw:: html

   <br>

=============
Phone Numbers
=============

Phone numbers that are to be used by phone.systems™ are managed by accessing the **Numbers** menu from the sidebar.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Phone Numbers

These phone numbers are used for:

-  Configuring **Phone Number** objects, being the phone number to be
   dialed for inbound calling.

-  Setting up **Contact Methods** for both inbound and outbound calls.

-  Selecting the caller ID to be displayed when making outbound calls
   from VoIP devices.

-  Enabling **Call Journaling** for both inbound and outbound calls, allowing interactions to be logged into a connected CRM system.

----

.. raw:: html

   <br>

User Interface Elements
-------------------------------

The filter bar at the top of the user list allows you to filter users by specific criteria. Filter options include:

- **Search By DID number**
- **Incoming call routing**
- **User**

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center
  :figwidth: 70%

  **Fig. 1.** Filter Bar

The table displays a list of users with the following columns:

+--------------------------+---------------------------------------------------------+
| **Field**                | **Description**                                         |
+==========================+=========================================================+
| **DID Number**           | The phone number available for incoming calls.          |
+--------------------------+---------------------------------------------------------+
| **Incoming Call Routing**| Indicates where the incoming calls for this DID are     |
|                          | routed.                                                 |
+--------------------------+---------------------------------------------------------+
| **Assigned to**          | Specifies the user or object the DID is assigned to.    |
+--------------------------+---------------------------------------------------------+
| **Contact Method/Object**| Details the contact method or  object associated with   |
|                          | the DID.                                                |
+--------------------------+---------------------------------------------------------+
| **Inbound Calls**        | Indicates whether inbound **Call Journaling** is        |
| **Call Journaling**      | enabled.                                                |
+--------------------------+---------------------------------------------------------+
| **Outbound Calls**       | Indicates whether outbound **Call Journaling** is       |
| **Call Journaling**      | enabled.                                                |
+--------------------------+---------------------------------------------------------+

.. note:: Call Journaling settings are only available if :ref:`CRM Integration <ps3_crm_integrations>` is active.

____

.. raw:: html

   <br>

.. _ps3_add_3rd_party_phone_numbers:

Add Third Party Phone Numbers
-------------------------------

.. note:: The DIDWW DIDs assigned to a phone.systems trunk through the `DIDWW user panel <https://my.didww.com/#/user_dids>`_ will automatically appear in the phone numbers list.

To add a third party **Phone Number**, follow these steps:

1. **Click on the Add New Phone Number button:**

Press the |+-symbol| button at the bottom right of the screen.

2. **Input the Phone Number**:

You will open a phone number creation screen, where you need to input the phone number in E.164 format.

.. note::  E.164 consists of: ``<CountryCode> <City/AreaCode> <LocalNumber>``

    The country code is 1-3 digits long, while the length of the city/area code and local number may vary. Some examples of phone numbers in E.164 are:

        - 14169233346 for Toronto, Canada
        - 442034116446 for London, United Kingdom.

3. **configure Call Journaling settings**:

-  **Inbound Calls**: Toggle to enable logging inbound calls to the CRM.
-  **Outbound Calls**: Toggle to enable logging outbound calls to the CRM.

.. note:: Call Journaling settings are only available if :ref:`CRM Integration <ps3_crm_integrations>` is active.

4. Click **Save**.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** Creating Phone Numbers

____

.. raw:: html

   <br>

.. _ps3_edit_phone_numbers:

Editing Phone Numbers
-------------------------------

To edit phone numbers, click on the **Actions** button and select **Edit**.

.. figure:: https://doc.didww.com/_images/fig10.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

Edit the phone numbers details and click **Save** to confirm.

.. note:: Call Journaling options will only be visible if :ref:`CRM Integration <ps3_crm_integrations>` is active.

.. figure:: https://doc.didww.com/_images/fig11.png
  :figclass: align-center

  **Fig. 2.** Editing Phone Numbers

.. note:: DIDWW DIDs with a phone.systems trunk assigned via the `DIDWW user panel <https://my.didww.com/#/user_dids>`_ can not be edited.

____

.. raw:: html

   <br>

Locating Phone Numbers
-------------------------------

If a **Phone Number** is placed on a :ref:`Call Flow <ps3_call_flows>`, you may quickly locate it on using the **Locate** feature.

To locate phone numbers, click on the **Actions** button and select **Locate**.

.. figure:: https://doc.didww.com/_images/fig19.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

You will locate that particular object on the phone.systems™ workspace.

.. figure:: https://doc.didww.com/_images/fig12.png
  :figclass: align-center

  **Fig. 2.** Locating The Phone Number

----

.. raw:: html

   <br>

Phone Number Relations
----------------------

The **Relations** view provides an overview of all configurations associated with the phone number.

To access it, click the **Actions** button and select **Relations**.

.. figure:: https://doc.didww.com/_images/fig20.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 1.** Actions Menu

This view shows related inbound calls and outbound CLI configurations.

To navigate to the related section, click on the |gear| symbol next to the relation.

.. figure:: https://doc.didww.com/_images/fig17.png
   :figclass: align-center
   :alt: Phone Number Relations

   **Fig. 2.** Phone Number Relations

____

.. raw:: html

   <br>

Deleting Phone Numbers
-----------------------

To delete phone numbers, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig21.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

If the selected phone number has any **relations**, the **Delete Phone Number** dialog displays a warning banner and a **relations counter**. Click the counter to view the full list of related items.

To permanently delete the phone number and its related items, enable the **Delete and unlink relations** toggle, then click **Delete**.

.. note::
   Deleting a phone number also deletes and unlinks all associated relations. Unlinking these relations may disrupt connected services. If you prefer not to proceed, close the dialog and update or remove the connections manually.

   DIDWW DIDs assigned to a phone.systems™ trunk through the `DIDWW user panel <https://my.didww.com/#/user_dids>`_ cannot be deleted.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** Delete Phone Number dialog

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. _ps3_internal_numbers:

.. raw:: html

   <br>

================
Internal Numbers
================

Internal numbers that are to be used by phone.systems™ are managed by accessing the **Numbers** menu from the sidebar and selecting the Internal Numbers tab.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 1.** Internal Numbers

These internal numbers are used for:

-  Configuring **Internal Number** objects, being the internal number to be
   dialed for internal inbound calling.

-  Setting up **Contact Methods** for both inbound and outbound calls.

-  Selecting the caller ID to be displayed when making internal outbound calls
   from VoIP devices.

----

.. raw:: html

   <br>

User Interface Elements
-------------------------------

The filter bar at the top of the user list allows you to filter users by specific criteria. Filter options include:

- **Search By internal number**
- **Incoming call routing**
- **User**

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center
  :figwidth: 70%

  **Fig. 1.** Filter Bar

The table displays a list of users with the following columns:

+---------------------------+---------------------------------------------------------+
| **Field**                 | **Description**                                         |
+===========================+=========================================================+
| **Internal Number**       | The internal number available for incoming calls.       |
+---------------------------+---------------------------------------------------------+
| **Incoming Call Routing** | Indicates where the incoming calls for this internal    |
|                           | number are routed.                                      |
+---------------------------+---------------------------------------------------------+
| **Assigned to**           | Specifies the user or object the internal number is     |
|                           | assigned to.                                            |
+---------------------------+---------------------------------------------------------+
| **Contact Method/Object** | Details the contact method or  object associated        |
|                           | with the DID.                                           |
+---------------------------+---------------------------------------------------------+

----

.. raw:: html

   <br>

.. _ps3_create_internal_numbers:

Create Internal Numbers
-------------------------------

To create an **Internal Number**, follow these steps:

.. note::
   Internal numbers are limited to a maximum length of **4 digits**.

1. **Click on the Add New Internal Number button:**

press the |+-symbol| button at the bottom right of the screen.

2. **Input the Internal Number**:

You will open an internal number creation screen, where you need to input the **one to four digit** internal number.

Input the internal number and click **Save**.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 2.** Creating Internal Numbers

____

.. raw:: html

   <br>

Editing Internal Numbers
-------------------------------

To edit internal numbers, click on the **Actions** button and select **Edit**

.. figure:: https://doc.didww.com/_images/fig14.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

Edit the internal numbers details and click **Save** to confirm.

.. figure:: https://doc.didww.com/_images/fig15.png
  :figclass: align-center
  :figwidth: 50%

  **Fig. 2.** Editing Internal Numbers

----

.. raw:: html

   <br>

Locating Internal Numbers
-------------------------------

If an **Internal Number** is placed on a :ref:`Call Flow <ps3_call_flows>`, you may quickly locate it on using the **Locate** feature.

To locate phone numbers, click on the **Actions** button and select **Locate**

.. figure:: https://doc.didww.com/_images/fig14.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

You will locate that particular object on the phone.systems™ workspace.

.. figure:: https://doc.didww.com/_images/fig16.png
  :figclass: align-center

  **Fig. 2.** Locating The Internal Number

----

.. raw:: html

   <br>

Internal Number Relations
-------------------------

The **Relations** view provides an overview of all configurations associated with the internal number.

To access it, click the **Actions** button and select **Relations**.

.. figure:: https://doc.didww.com/_images/fig14.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 1.** Actions Menu

This view shows related inbound calls, internal CLI, and call flows configurations.

To navigate to the related section, click on the |gear| symbol next to the relation.

.. figure:: https://doc.didww.com/_images/fig18.png
   :figclass: align-center
   :alt: Internal Number Relations

   **Fig. 2.** Internal Number Relations

----

.. raw:: html

   <br>

Deleting Internal Numbers
--------------------------

To delete internal numbers, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig14.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

If the selected internal number has any **relations**, the **Delete Internal Number** dialog displays a warning banner and a **relations counter**. Click the counter to view the full list of related items.

To permanently delete the internal number and its related items, enable the **Delete and unlink relations** toggle, then click **Delete**.

.. note::
   Deleting an internal number also deletes and unlinks all associated relations. Unlinking these relations may disrupt connected services. If you prefer not to proceed, close the dialog and update or remove the connections manually.

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** Delete Internal Number dialog

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px

.. _ps3_time_schedules:

==============
Time Schedules
==============

The **Time Schedule** lets you define and manage your organization’s working hours and exceptions for call flows during regular business hours, holidays, and special occasions.

When a **Time Schedule** is assigned to a user, it controls call delivery based on defined working hours and exceptions. Calls made outside these hours or during exceptions (e.g., holidays) will skip all contact methods for the user. The call will only attempt delivery during active working hours.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Time Schedule Menu

.. _ps3_create_time_schedule:

.. |br| raw:: html

    <br>

----

.. raw:: html

   <br>

Create Time Schedule
----------------------

To create a **Time Schedule**, follow these steps:

1. **Click on the Add New Time Schedule button:**

Navigate to the **Time Schedules** tab and click on the |+-symbol| symbol on the bottom right of the screen.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Clicking the + symbol

2. **Fill in the Time Schedule Details:**

A form will appear where you need to enter the **Time Schedule** details, such as:

* **Title** |br|
* **Timezone** |br|
* **Working Days** |br|
* **Working Hours**

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** Time Schedule Details

3. **Set working hour exceptions**:

The time scheduler allows you to configure your call flows in a specific manner, avoiding some specific days such as holidays or important personal days. To create working hour exceptions, you must select the following:

+------------------------+----------------------------------------------------------+
| **Field**              | **Description**                                          |
+========================+==========================================================+
| **Name**               | The name for the exception.                              |
+------------------------+----------------------------------------------------------+
| **Type**               |Exception for **Working** or **Non-Working** hours.       |
+------------------------+----------------------------------------------------------+
| **Repeat**             |Choose how often the exception repeats:                   |
|                        |**Once**, **Monthly** or **Yearly**.                      |
+------------------------+----------------------------------------------------------+
| **From**               | Specifies the date and time when the exception           |
|                        | will start.                                              |
+------------------------+----------------------------------------------------------+
| **To**                 | Specifies the date and time when the exception           |
|                        | will end.                                                |
+------------------------+----------------------------------------------------------+

4. **Saving the Time Schedule**:

Click **save** once the configuration is complete.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 3.** Configuring The Working Hour Exceptions

.. _ps3_assign_time_schedule:

----

.. raw:: html

   <br>

Assign Time Schedule
-----------------------

.. note:: To assign a :ref:`time schedule <ps3_create_time_schedule>`, you must have :ref:`active users <ps3_users>`.

1. **Locate the user**:

Go to the existing :ref:`users menu <ps3_users>` and locate the user for whom you want to assign the **Time Schedule**.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Locating The Time Schedule Column

2. **Assigning the time schedule**:

Click on the **Time Schedule** Column for your selected user, and select the wanted time schedule, alternatively, edit the user and assign the **Time Schedule** via the **Edit User** menu.

Once you select the time schedule, it becomes assigned to the user, and all of the users contact methods.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** Assigning The Time Schedule

----

.. raw:: html

   <br>

Remove Time Schedule
------------------------

To remove the time schedule, follow these steps:

1. **Locate the user**:

Go to the existing :ref:`users menu <ps3_users>` and find the user you want to unassign the time schedule to.

2. **Unassign the time schedule**:

click on the assigned time schedule in the users menu and click the |x| button to unassign the **Time Schedule**.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 1.** Removing The Time Schedule

----

.. raw:: html

   <br>

Edit Time Schedule
------------------------

To edit time schedules, click on the **Actions** button and select **Edit**.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

Edit the time schedule details and click **Save** to confirm.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 2.** Edit Time Schedule

----

.. raw:: html

   <br>

Time Schedule Relations
-----------------------

The **Relations** view provides an overview of all configurations associated with the time schedule.

To access it, click the **Actions** button and select **Relations**.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 1.** Actions Menu

This view shows related user configurations..

To navigate to the related section, click on the |gear| symbol next to the relation.

.. figure:: https://doc.didww.com/_images/fig4.png
   :figclass: align-center
   :alt: User Relations

   **Fig. 2.** Time Schedules Relations

----

.. raw:: html

   <br>

Delete Time Schedule
---------------------

To delete time schedules, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 1.** Actions Menu

If the selected time schedule has any **relations**, the **Delete Time Schedule** dialog displays a warning banner and a **relations counter**. Click the counter to view the full list of related items.

To permanently delete the time schedule and its related items, enable the **Delete and unlink relations** toggle, then click **Delete**.

.. note::
   Deleting a time schedule also deletes and unlinks all associated relations. Unlinking these relations may disrupt connected services. If you prefer not to proceed, close the dialog and update or remove the connections manually.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :figwidth: 40%

  **Fig. 2.** Delete Time Schedule dialog

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |x| image:: /phone-systems/assets/img/guide-v2/time_schedule/assign_time_schedule/x.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _ps3_delivery_methods_index:

================
Delivery Methods
================

Easily manage how voicemails, faxes, notifications, and call recordings are delivered with phone.systems™.
Connect your preferred storage or email services, automate file transfers, and keep every message and recording securely organized in one place.

----

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`mail` **Delivery Methods**
      :link: delivery-methods
      :link-type: doc
      :text-align: left

      Set up, edit, or remove delivery methods, connect storage services, and adjust delivery settings.

   .. grid-item-card:: :octicon:`list-unordered` **Delivery Logs**
      :link: delivery-logs
      :link-type: doc
      :text-align: left

      View delivery history, track performance, and resolve failed deliveries.

.. toctree::
   :maxdepth: 1
   :hidden:

   Delivery Methods <delivery-methods.rst>
   Delivery Logs <delivery-logs.rst>


.. |br| raw:: html

  <br>

.. _ps3_delivery_methods:

================
Delivery Methods
================

**Delivery Methods** define how audio and text files generated by phone.systems™ are delivered to users. These files include voicemail, notifications, faxes, and call recordings. Supported methods are **Email, Dropbox, Google Drive, OneDrive, FTP,** and **SFTP**.

.. .. figure:: /phone-systems/assets/img/guide-v2/delivery_methods/fig_index.png
   :figclass: align-center
   :alt: Delivery Methods

   **Fig. 1.** Delivery Methods

.. raw:: html

   <br>

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Add Delivery Method**
      :link: ps3_delivery_methods_add
      :link-type: ref
      :text-align: left

      Add a new delivery method to manage how files and messages are delivered.

   .. grid-item-card:: :octicon:`key` **Edit Delivery Method**
      :link: ps3_delivery_methods_edit
      :link-type: ref
      :text-align: left

      Update delivery method settings or reauthorize third-party connections.

   .. grid-item-card:: :octicon:`eye` **Delivery Method Relations**
      :link: delivery-method-relations
      :link-type: ref
      :text-align: left

      Review how delivery methods are linked to different services and features.

   .. grid-item-card:: :octicon:`trash` **Delete Delivery Method**
      :link: deleting-delivery-method
      :link-type: ref
      :text-align: left

      Delete a delivery method and remove all associated connections.

----

.. raw:: html

   <br>

Supported Features
==================

Delivery methods can be used across various phone.systems™ features, including call flow objects such as **Voicemail**, **Call Recorder**, **Fax**, and **Notification**, as well as **SIP Account Call Recording** for SIP-based calls.

.. list-table::
   :header-rows: 1
   :widths: 28 12 12 12 12 12 12

   * - **phone.systems™ Feature**
     - **Email**
     - **Dropbox**
     - **FTP**
     - **SFTP**
     - **Google Drive**
     - **OneDrive**
   * - :ref:`Voicemail <ps3_object_voicemail>`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
   * - :ref:`Call Recorder <ps3_object_call_recorder>`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
   * - :ref:`Fax <ps3_object_fax>`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
   * - :ref:`Notification <ps3_object_notification>`
     - :octicon:`check-circle`
     - :octicon:`x-circle`
     - :octicon:`x-circle`
     - :octicon:`x-circle`
     - :octicon:`x-circle`
     - :octicon:`x-circle`
   * - :ref:`SIP Account Call Recording <ps3_sip_accounts_call_recording>`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`
     - :octicon:`check-circle`

.. note::
   - Call recordings are delivered to the selected destination once each call ends.
   - When using the **Email** delivery method, large recordings (about 7 MB per hour of audio) may exceed your provider’s size limits and fail to deliver. Check your email provider’s limits, as rejected files can’t be recovered.
   - Recordings are **not stored**, processed, or accessed by phone.systems™. They are delivered directly to the configured destination.

----

.. raw:: html

   <br>

.. _ps3_delivery_methods_add:

Add Delivery Method
========================

Follow these steps to add any delivery method.

Step 1: Create delivery method
----------------------------------

Open the **Delivery Methods** menu and click the |+-symbol| button.

.. figure:: https://doc.didww.com/_images/fig12.png
   :figclass: align-center
   :alt: Add Delivery Method

   **Fig. 1.** Add Delivery Method

.. raw:: html

   <br>

Step 2: Choose Delivery Method type
---------------------------------------

Select one of the supported delivery method types.

.. figure:: https://doc.didww.com/_images/delivery-methods-new.png
   :figclass: align-center
   :alt: Select Method Type

   **Fig. 3.** Select Method Type

.. raw:: html

   <br>

Step 3: Configure Delivery Method Properties
------------------------------------------------

After you select a delivery method type, configure the required settings such as the destination folder, server credentials, or recipient addresses.

.. tab-set::
   :class: my-tabs

   .. tab-item:: **Email**

      Sends delivered files as email attachments directly to the specified recipients.

      .. list-table::
         :widths: 15 62
         :header-rows: 1

         * - Field
           - Description
         * - **Name**
           - Enter a friendly name to identify this delivery method.
         * - **Emails**
           - Add one or more recipient addresses. Each address will display its verification status (e.g., **Verified**).

             .. note:: To select an email, you first need to add it as a :ref:`contact method <ps3_emails>`.

         * - **Subject**
           -  The subject line for the delivery email (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

         * - **Message text**
           - The main body of the email message (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

      .. figure:: https://doc.didww.com/_images/new-email.png
         :figclass: align-center
         :alt: Email Delivery Method Configuration

         **Fig. 2.** Email Delivery Method Configuration

   .. tab-item:: **Dropbox**

      Uploads delivered files to a connected Dropbox account or folder. Authorization is required before use.

      .. list-table::
         :widths: 17 60
         :header-rows: 1

         * - Field
           - Description
         * - **Name**
           - Enter a friendly name to identify this delivery method.
         * - **Connection Status**
           - Shows the current Dropbox connection status.
         * - **File name**
           - Define a file name pattern (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

             .. note:: The **File name** field becomes available after connecting your Dropbox account.

      .. figure:: https://doc.didww.com/_images/delivery-methods-new-dropbox.png
         :figclass: align-center
         :alt: New Dropbox Delivery Method

         **Fig. 3.** New Dropbox Delivery Method

   .. tab-item:: **FTP**

      Uploads files directly to an FTP server.

      .. list-table::
         :widths: 21 60
         :header-rows: 1

         * - Field
           - Description
         * - **Name**
           - Enter a friendly name to identify this delivery method.
         * - **Host**
           - FTP server domain name or IP address.
         * - **Port**
           - FTP server port number.
         * - **Directory**
           - Remote directory (folder path) where files will be uploaded.
         * - **Passive Mode**
           - Enable if required by your FTP server or firewall.
         * - **Anonymous**
           - Enable if your server allows anonymous access (no login required).
         * - **Username**
           - FTP username for authentication.
         * - **Password**
           - FTP password for authentication.
         * - **File name**
           - File name pattern for uploaded files (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

      .. figure:: https://doc.didww.com/_images/delivery-methods-new-ftp.png
         :figclass: align-center
         :alt: FTP configuration

         **Fig. 4.** FTP configuration

   .. tab-item:: **SFTP**

      Securely transfers delivered files to an SFTP server.

      .. list-table::
         :widths: 22 60
         :header-rows: 1

         * - **Name**
           - Enter a friendly name to identify this delivery method.
         * - **Host**
           - SFTP server domain name or IP address.
         * - **Port**
           - SFTP server port number.
         * - **Directory**
           - Folder path where files will be uploaded.
         * - **Username**
           - SFTP username for authentication.
         * - **Password**
           - SFTP password for authentication.
         * - **File name**
           - File name pattern for uploaded files (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

      .. figure:: https://doc.didww.com/_images/delivery-methods-new-sftp.png
         :figclass: align-center
         :alt: SFTP configuration

         **Fig. 5.** SFTP configuration

   .. tab-item:: **Google Drive**

      Uploads delivered files to a connected Google Drive folder. Requires authorization with your Google account.

      .. list-table::
         :widths: 16 60
         :header-rows: 1

         * - **Field**
           - **Description**
         * - **Name**
           - Enter a friendly name to identify this delivery method.
         * - **Directory**
           - Target folder path in Google Drive (e.g., phone.systems).
         * - **Connection Status**
           - Shows the connection status to your Google Drive account. Use **Connect** to authorize.
         * - **File name**
           - Define a file name pattern (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

             .. note:: The **File name** field becomes available after connecting your Google Drive account.

      .. figure:: https://doc.didww.com/_images/delivery-methods-new-google-drive.png
         :figclass: align-center
         :alt: New Google Drive Delivery Method

         **Fig. 6.** New Google Drive Delivery Method

   .. tab-item:: **OneDrive**

      Uploads delivered files to a connected Microsoft OneDrive folder. Requires authorization with your Microsoft account.

      .. list-table::
         :widths: 17 61
         :header-rows: 1

         * - Field
           - Description
         * - **Name**
           - Enter a friendly name to identify this delivery method.
         * - **Connection Status**
           - Shows the current OneDrive connection status.
         * - **Folder**
           - Destination folder path in OneDrive.
         * - **File name**
           - File name pattern for uploaded files (supports :ref:`dynamic fields <ps3_delivery_methods_dynamic_fields>`).

             .. note:: The **File name** field becomes available after connecting your OneDrive account.

      .. figure:: https://doc.didww.com/_images/delivery-methods-new-onedrive.png
         :figclass: align-center
         :alt: New OneDrive Delivery Method

         **Fig. 7.** New OneDrive Delivery Method

.. raw:: html

   <br>

.. _ps3_delivery_methods_dynamic_fields:

Dynamic Fields
~~~~~~~~~~~~~~

Some delivery method input fields support dynamic fields that automatically insert call details such as the number, service, or time into file names, email subjects, or messages.

.. list-table::
   :header-rows: 1
   :widths: 25 70

   * - **Field**
     - **Description**
   * - %{src_number}
     - Caller’s phone number.
   * - %{src_name}
     - Caller’s name.
   * - %{dst_number}
     - Number that was called.
   * - %{service_name}
     - Name of the service or feature that created the file.
   * - %{call_time}
     - Full date and time of the call in the format: **YYYY-MM-DD HH-MM-SS**.

       .. note:: Times are based on your **System time zone** set in **General Settings**.

   * - %{call_year}
     - Year of the call.
   * - %{call_month}
     - Month of the call.
   * - %{call_day}
     - Day of the call.
   * - %{call_hour}
     - Hour of the call.

.. raw:: html

   <br>

Delivered File Name Format
~~~~~~~~~~~~~~~~~~~~~~~~~~

When a file is delivered, its name is automatically created using call details such as the service name, phone numbers, and time of the call.

.. code-block::

    Example file name: Voicemail-12025550123-12025550199-2025-05-07 06-57-38.mp3
    File Name Pattern: %{service_name}-%{src_number}-%{dst_number}-%{call_time}.mp3

.. raw:: html

   <br>

Step 4: Save the Delivery Method
--------------------------------

Once all required fields are completed and the delivery method is configured, click **Save** to finalize the setup.

.. figure:: https://doc.didww.com/_images/save-delivery-method.png
   :figclass: align-center
   :alt: Save the Delivery Method

   **Fig. 8.** Save the Delivery Method

----

.. raw:: html

   <br>

.. _ps3_delivery_methods_edit:

Edit Delivery Methods
========================

Use **Edit** action when you need to change where files are delivered (folder, directory, recipients), update credentials, or adjust file name patterns.

1. Go to **Delivery Methods**.
2. Click the **Actions** button next to the method and choose **Edit**.

.. figure:: https://doc.didww.com/_images/actions.png
   :figclass: align-center
   :alt: Actions Button

   **Fig. 9.** Actions Button

3. Update the required fields.
4. Click **Save**.

.. figure:: https://doc.didww.com/_images/edit.png
   :figclass: align-center
   :alt: Editing Delivery Methods

   **Fig. 10.** Editing Delivery Methods

.. _ps3_re_authorizing:
.. _re-authorizing-3rd-party-delivery-method:

Reconnect Third-Party Delivery Services
----------------------------------------

If access to a connected service (such as **Dropbox**, **Google Drive**, or **OneDrive**) expires, the status will show **Access revoked**.

1. Open the **Delivery Methods** tab, find the delivery method, click **Actions**, and then select **Edit**.
2. In the **Edit Delivery Method** form, click **Reconnect** next to the account status.
3. Sign in and allow access when prompted.
4. Once reconnected, the status updates to **Connected**, and deliveries resume automatically.

.. figure:: https://doc.didww.com/_images/reconnect.png
   :figclass: align-center
   :alt: Reconnecting an expired Dropbox account

   **Fig. 11.** Reconnecting an expired Dropbox account

----

.. raw:: html

   <br>

.. _delivery-method-relations:

Delivery Method Relations
=========================

The **Relations** shows which phone.systems™ objects use a specific delivery method.
Review dependencies and adjust settings if needed to prevent service interruptions before editing or deleting a method.

1. Go to **Delivery Methods**.
2. Click the **Actions** button next to the delivery method.
3. Select **Relations** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/actions.png
   :figclass: align-center
   :alt: Viewing relations for a delivery method

   **Fig. 12.** Viewing relations for a delivery method

A list of all connected objects (such as **Call Flows** and **Contact Methods**) will appear.
To navigate directly to an object for further configuration, click the |gear| icon next to its name.

.. note::
   Relations update in real time. Any changes, re-authorization, or deletion of a delivery method immediately affect all linked services.

.. figure:: https://doc.didww.com/_images/relations.png
   :figclass: align-center
   :alt: Viewing relations for a delivery method

   **Fig. 13.** Viewing relations for a delivery method

----

.. raw:: html

   <br>

.. _deleting-delivery-method:

Delete Delivery Method
==========================

To delete a delivery method, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center

  **Fig. 14.** Actions Menu

If the selected delivery method is associated with any **relations**, the **Delete Delivery Method** dialog displays a warning banner and a **relations counter**. Click the counter to view the complete list of related objects.

Before deletion can proceed, all related services must be unlinked. Once the relations are removed, click **Delete** to permanently delete the delivery method.

.. note::
   Delivery methods that are still in use by other services cannot be deleted. Unlink them first, then try deleting again.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig11.1.png
           :figclass: align-center
           :alt: Delete Delivery Method dialog With Relations

           **Fig. 15.** Delete Delivery Method dialog with relations

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig11.2.png
           :figclass: align-center
           :alt: Delete Delivery Method dialog Without Relations

           **Fig. 16.** Delete Delivery Method dialog without relations

Additional Resources
======================

.. card:: **Delivery Logs**
    :link: ps3_delivery_methods_logs
    :link-type: ref

    Monitor the history of all file deliveries across services.

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px



.. _ps3_delivery_methods_logs:

==============
Delivery Logs
==============

Use **Delivery Logs** to track and review every file delivered by phone.systems™ services (such as **Voicemail**, **Call Recorder**, and **Fax**) to your configured destinations (**Email**, **Dropbox**, **Google Drive**, **OneDrive**, **FTP**, **SFTP**).

----

.. raw:: html

   <br>

Filtering Delivery Records
--------------------------

Use filters to quickly find specific delivery attempts based on time, method, or status.

.. list-table::
   :header-rows: 1
   :widths: 15 76

   * - **Field**
     - **Description**
   * - **Time Range**
     - Predefined or custom range of dates and times to filter the delivery logs (e.g., Today, Last 24 hours, This week, Custom range).
   * - **Delivery Type**
     - Filters deliveries by destination type (**Email**, **Dropbox**, **Google Drive**, **OneDrive**, **FTP**, **SFTP**).
   * - **Delivery Name**
     - Filters results by the friendly name assigned to a delivery method.
   * - **Status**
     - Filters records by delivery result (e.g., *Delivered successfully*, *Failed*).

.. figure:: https://doc.didww.com/_images/delivery-logs-filters.png
   :figclass: align-center
   :alt: Delivery Log Filters

   **Fig. 2.** Delivery Log Filters

----

Delivery Log Details
------------------------------

Each row in the **Delivery Logs** table represents one file delivery attempt and shows detailed information about its progress and result.

.. list-table::
   :header-rows: 1
   :widths: 15 72

   * - **Field**
     - **Description**
   * - **Call Start**
     - The date and time when the related call began.
   * - **Delivery Start**
     - The date and time when phone.systems™ initiated the file delivery.
   * - **Delivered At**
     - The date and time when the delivery was completed.
   * - **Completed In**
     - The total time taken from initiation (**Delivery Start**) to completion (**Delivered At**).
   * - **Delivery Type | Name**
     - The delivery method type and the friendly name assigned to it (e.g., **Email | Voicemail Delivery**).
   * - **Service**
     - The originating service that generated the file (e.g., **App**, **Notification**, **Voicemail**).
   * - **File Name**
     - The name of the delivered file.
   * - **File Size**
     - The size of the delivered file.
   * - **Reason**
     - System message indicating the delivery outcome (e.g., *Delivered successfully* or a delivery error message).
   * - **Source Number**
     - The phone number from which the call originated.
   * - **Source Name**
     - The name associated with the caller, if available.
   * - **Destination Number**
     - The phone number that received the call.

.. figure:: https://doc.didww.com/_images/delivery-logs-fields.png
   :figclass: align-center
   :alt: Delivery Logs Fields

   **Fig. 3.** Delivery Logs Fields

.. _ps3_audio_files:

===========
Audio Files
===========

The Audio Files section in Cloud PBX phone.systems™ lets you manage all sound recordings and announcements used throughout your system.
You can upload, record, edit, and delete audio files in supported formats (.mp3, .m4a, .wav, .flac, .ogg), up to 14 MB each.

These audio files are used by objects such as Voice Menu, Audio Playback, and Ring Group to play messages or music to callers.
You can also organize recordings into playlists for purposes such as music on hold, rotating announcements, or queue messages, enhancing the overall caller experience.

----

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`unmute` **Audio Files**
      :link: audio-files
      :link-type: doc
      :text-align: left

      Learn how to upload, record audio files for greetings, prompts, and other use cases.

   .. grid-item-card:: :octicon:`list-unordered` **Playlists**
      :link: playlists
      :link-type: doc
      :text-align: left

      Organize multiple audio files into playlists for music on hold or announcements.

.. toctree::
  :maxdepth: 1
  :hidden:

  Audio Files <audio-files.rst>
  Playlists <playlists.rst>


.. _ps3_audio_files_audio_files:

.. |br| raw:: html

    <br>

============
Audio files
============

The **Audio Files** section allows you to manage sound recordings and announcements used across your system.
These files can serve as greetings, voicemail messages, IVR prompts, or call announcements.
You can easily **upload**, **record**, **generate**, **edit**, and **delete** audio files directly from the **phone.systems™** user interface.

.. raw:: html

   <br>

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Upload audio file**
      :link: ps3_uploading_audio_files
      :link-type: ref
      :text-align: left

      Add existing recordings (greetings, IVR prompts, announcements) to your library.

   .. grid-item-card:: :octicon:`unmute` **Record audio file**
      :link: ps3_audio_files_recording
      :link-type: ref
      :text-align: left

      Capture new audio using your device’s microphone.

   .. grid-item-card:: :octicon:`typography` **Text to speech**
      :link: ps3_audio_files_text_to_speech
      :link-type: ref
      :text-align: left

      Generate an audio file from text using a voice from the list of available voices.

   .. grid-item-card:: :octicon:`eye` **View audio file relations**
      :link: ps3_audio_files_relations
      :link-type: ref
      :text-align: left

      See where a file is used (Playlists, Call Flows, Contact Methods) before making changes.

   .. grid-item-card:: :octicon:`trash` **Delete audio file**
      :link: ps3_audio_files_delete
      :link-type: ref
      :text-align: left

      Remove an audio file safely after reviewing any linked relations.

----

.. raw:: html

   <br>

.. _ps3_uploading_audio_files:

Upload audio files
---------------------

You can upload existing audio files to quickly reuse professional recordings, greetings, or pre-recorded announcements.
This is ideal for uploading IVR messages, pre-approved company greetings, or multilingual system prompts.

1. Go to the **Audio Files** section.
2. Click the |+-symbol| icon and select **Upload audio file**.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Upload audio file option

3. In the **Upload Audio File** window, browse and select the desired audio file from your local drive, network storage, or external media.

.. note::
   The maximum file size for an audio file is **14 MB**.

.. figure:: https://doc.didww.com/_images/fig10.png
  :figclass: align-center

  **Fig. 2.** File selection window

4. Once the upload is complete, click the **Play** button to preview the file.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 3.** Uploaded audio file playback

----

.. raw:: html

   <br>

.. _ps3_audio_files_recording:

Record audio files
---------------------

You can record audio files directly from your device’s microphone, allowing you to quickly create personalized announcements, greetings, or voicemail messages without needing external software.

1. Open the **Audio Files** section.
2. Click the |+-symbol| icon and select **Record audio file**.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 4.** Recording audio files

3. In the **Record New File** window, enter a name for the recording and click **Record** to begin.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center
  :alt: Recording Interface
  :width: 30%

  **Fig. 5.** Recording interface

4. Speak into your device’s microphone. When finished, click **Stop** to end the recording.

5. Click **Play** to review your recording. If you’re satisfied, click **Save** to store it in your audio library.

.. note::
   The maximum file size for a recorded audio file is **14 MB**.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig4.png
           :figclass: align-center
           :alt: Recording Audio Files and Stop Recording Button

           **Fig. 6.** Recording audio files

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig5.png
           :figclass: align-center
           :alt: Playback and Save Controls

           **Fig. 7.** Playback and save controls

----

.. raw:: html

   <br>

.. _ps3_audio_files_text_to_speech:

Text to speech
--------------

You can generate an audio file from typed text using a voice from the list of available voices.
This is useful for creating greetings, IVR prompts, or announcements without recording audio manually.

1. Open the **Audio Files** section.
2. Click the |+-symbol| icon and select **Text to speech**.

.. figure:: https://doc.didww.com/_images/text_to_speech_option.png
  :figclass: align-center
  :alt: Text to speech option in the Audio Files menu

  **Fig. 8.** Text to speech option

3. In the **Text to speech** window, enter the message in the **Text** field.
4. Select a **Voice** from the list of available voices.

.. note::
   The **Text** field supports up to **250 characters**.

.. figure:: https://doc.didww.com/_images/text_to_speech_voice.png
  :figclass: align-center
  :alt: Selecting a voice for text to speech audio generation

  **Fig. 9.** Selecting a voice

5. Click **Generate** to create the audio preview.
6. In the **Preview** section, click **Play** to review the generated audio.
7. Enter a **Filename** for the audio file.
8. Click **Save** to store the generated file in your audio library.

.. figure:: https://doc.didww.com/_images/text_to_speech_generate.png
  :figclass: align-center
  :alt: Text to speech audio preview and filename field

  **Fig. 10.** Text to speech audio preview

----

.. raw:: html

   <br>

.. _ps3_audio_files_edit:

Edit audio files
-------------------

You can rename existing audio files to keep your library organized and make it easier to identify their purpose (for example, “Main Greeting” or “After-Hours Message”).

1. In the **Audio Files** list, click the **Actions** button next to the file you want to edit.
2. Select **Edit** from the dropdown menu.
3. Update the file name or description as needed.
4. Click **Save** to confirm your changes.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :alt: Actions Button

  **Fig. 11.** Actions button

----

.. raw:: html

   <br>

.. _ps3_audio_files_relations:

View audio file relations
--------------------------

Each audio file may be linked to other configurations, such as **Playlists**, **Call Flows**, or **Contact Methods**.
Viewing relations helps ensure you don’t delete or modify a file that’s currently in use.

1. Click the **Actions** button next to an audio file.
2. Select **Relations** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :alt: Actions Button

  **Fig. 12.** Actions button

The **Relations** window displays all related items grouped by category. Click the |gear| icon next to a relation to navigate directly to its configuration page.

.. figure:: https://doc.didww.com/_images/relations.png
  :figclass: align-center
  :alt: Audio File Relations Overview
  :width: 30%

  **Fig. 13.** Audio file relations overview

----

.. raw:: html

   <br>

.. _ps3_audio_files_delete:

Delete audio files
--------------------

To delete an audio file, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :alt: Actions Button

  **Fig. 14.** Actions button

If the selected audio file has any **relations**, the **Delete Audio File** dialog displays a warning banner and a **relations counter**. Click the counter to view the complete list of related items.

Before deletion can proceed, all related services must be unlinked. Once the relations are removed, click **Delete** to permanently delete the audio file.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/delete1.png
           :figclass: align-center
           :alt: Delete Audio File dialog with relations

           **Fig. 15.** Delete audio file dialog with relations

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/delete2.png
           :figclass: align-center
           :alt: Delete Audio File dialog without relations

           **Fig. 16.** Delete audio file dialog without relations

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _ps3_audio_files_playlists:

.. |br| raw:: html

    <br>

=========
Playlists
=========

The **Playlists** section allows you to organize multiple audio files into playback sequences for use in phone.systems™.
Playlists are typically used for music on hold, rotating announcements, or ring group messages.
You can easily **create**, **edit**, **reorder**, and **delete** playlists directly from the **phone.systems™** user interface.

.. raw:: html

   <br>

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plus` **Create Playlist**
      :link: ps3_create_playlist
      :link-type: ref
      :text-align: left

      Combine multiple audio files into a single playlist for playback or announcements.

   .. grid-item-card:: :octicon:`pencil` **Edit Playlist**
      :link: ps3_edit_playlist
      :link-type: ref
      :text-align: left

      Rename, reorder, or update existing playlists and manage included audio files.

   .. grid-item-card:: :octicon:`eye` **View Playlist Relations**
      :link: ps3_playlists_relations
      :link-type: ref
      :text-align: left

      View how playlists are linked to Call Flows, Ring Groups, or Queues before editing.

   .. grid-item-card:: :octicon:`trash` **Delete Playlist**
      :link: ps3_delete_playlist
      :link-type: ref
      :text-align: left

      Safely remove a playlist after reviewing any associated relations.

----

.. raw:: html

   <br>

.. _ps3_create_playlist:

Create Playlist
-------------------

You can create a new playlist by combining existing audio files from your **Audio Files** library.

1. Open the **Audio Files** menu and select the **Playlists** tab.
2. Click the |+-symbol| icon.

.. figure:: https://doc.didww.com/_images/playlist1.png
  :figclass: align-center
  :alt: Add Playlist button

  **Fig. 1.** Add Playlist button

3. Enter a **Name** for your playlist and click **Add audio files** to include existing files.

.. note::
   Only audio files that already exist in your library can be added to a playlist.

.. figure:: https://doc.didww.com/_images/playlist2.png
  :figclass: align-center
  :alt: Adding audio files to a playlist

  **Fig. 2.** Adding audio files to a playlist

4. (Optional) Drag and drop tracks to change their playback order.

.. figure:: https://doc.didww.com/_images/gif1.gif
  :figclass: align-center
  :alt: Reordering playlist tracks
  :width: 33%

  **Fig. 3.** Reordering playlist tracks

5. Once all desired files are added and ordered, click **Save** to create the playlist.

.. figure:: https://doc.didww.com/_images/playlist3.png
  :figclass: align-center
  :alt: Saving playlist

  **Fig. 4.** Saving a new playlist

----

.. raw:: html

   <br>

.. _ps3_edit_playlist:

Edit Playlist
------------------

You can rename an existing playlist, modify its contents, or adjust the order of the audio files.

1. In the **Playlists** tab, click the **Actions** button next to the playlist you want to edit.
2. Select **Edit** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/playlist_actions.png
  :figclass: align-center
  :alt: Actions button in playlist menu

  **Fig. 5.** Actions button in playlist menu

3. Update the **Name**, **Add** or **Remove** audio files, or **Reorder** them.
4. Click **Save** to confirm your changes.

.. figure:: https://doc.didww.com/_images/playlist_edit.png
  :figclass: align-center
  :alt: Edit Playlist Window

  **Fig. 6.** Edit Playlist Window

----

.. raw:: html

   <br>

.. _ps3_playlists_relations:

View Playlist Relations
-----------------------

Each playlist may be linked to other configurations, such as **Call Flows**, **Ring Groups**, or **Queues**.
Viewing relations helps ensure you don’t delete or modify a playlist that’s currently in use.

1. In the **Playlists** tab, click the **Actions** button next to a playlist.
2. Select **Relations** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/playlist_actions.png
  :figclass: align-center
  :alt: Actions button in playlist menu

  **Fig. 7.** Actions button in playlist menu

The **Relations** window displays all related items grouped by category. Click the |gear| icon next to a relation to navigate directly to its configuration page.

.. figure:: https://doc.didww.com/_images/playlist_relations.png
  :figclass: align-center
  :alt: Playlist relations overview

  **Fig. 8.** Playlist relations overview

----

.. raw:: html

   <br>

.. _ps3_delete_playlist:

Delete Playlist
-------------------

To delete a playlist, click the **Actions** button and select **Delete**.

.. figure:: https://doc.didww.com/_images/playlist_actions.png
  :figclass: align-center
  :alt: Actions button in playlist menu

  **Fig. 9.** Actions button in playlist menu

If the selected playlist has any **relations**, the **Delete Playlist** dialog displays a warning banner and a **relations counter**. Click the counter to view the complete list of related items.

Before deletion can proceed, all related services must be unlinked. Once the relations are removed, click **Delete** to permanently delete the playlist.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/playlist_delete1.png
           :figclass: align-center
           :alt: Delete Playlist dialog with relations

           **Fig. 10.** Delete Playlist dialog with relations

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/playlist_delete2.png
           :figclass: align-center
           :alt: Delete Playlist dialog without relations

           **Fig. 11.** Delete Playlist dialog without relations

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


.. _ps3_trunks_index:

======
Trunks
======

The phone.systems™ platform supports both inbound and outbound trunks, allowing you to set up DID numbers, termination gateways, and routes for efficient call processing.

----

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`plug` **Inbound Trunks**
      :link: inbound-trunks
      :link-type: doc
      :text-align: left

      Manage inbound trunks to receive calls from external networks into your phone system.

   .. grid-item-card:: :octicon:`server` **Termination Gateways**
      :link: termination-gateways
      :link-type: doc
      :text-align: left

      Configure termination gateways to route outbound calls through specific carriers or servers.

   .. grid-item-card:: :octicon:`git-branch` **Termination Routes**
      :link: termination-routes
      :link-type: doc
      :text-align: left

      Define termination routes to control outbound call paths and prioritize carriers.

.. toctree::
  :maxdepth: 1
  :hidden:

  Inbound Trunks <inbound-trunks.rst>
  Termination Gateways <termination-gateways.rst>
  Termination Routes <termination-routes.rst>


.. _ps3_inbound_trunks:

================================
Inbound Trunks in phone.systems™
================================

.. note::  The instructions below apply specifically to phone.systems™ inbound trunks, which are separate from the Inbound Trunks in the main DIDWW user panel — the feature set and setup steps differ.

phone.systems™ Inbound Trunks receive SIP traffic from third-party VoIP providers and deliver incoming calls into the phone.systems™ environment for further processing. Multiple providers can be used, with DIDWW preconfigured as the default.

To access and manage your inbound trunks, click **Trunks** in the sidebar menu and select the **Inbound Trunks** tab.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center

   **Fig. 1.** Inbound Trunks

----

.. raw:: html

   <br>

Inbound Call Forwarding to phone.systems™
-----------------------------------------

When you receive calls from an external VoIP provider, those calls must be forwarded into your phone.systems™ workspace.
To make this possible, phone.systems™ automatically creates a default inbound trunk named Default. You can :ref:`edit <ps3_edit_inbound_trunks>`, :ref:`delete <ps3_delete_inbound_trunks>`, or :ref:`create <ps3_inbound_trunk_create>` additional inbound trunks as needed.

Your VoIP provider must forward SIP traffic to this domain using a SIP URI such as::

   phonenumber@xxxxxxxxxxxxx.in.phone.systems

This SIP URI consists of two components:

- **Phone Number in E.164 format** – The phone number receiving the call (for example, ``14169233346`` for Toronto or ``442034116446`` for London).
  This number :ref:`must also be added <ps3_add_3rd_party_phone_numbers>` to your phone.systems™ workspace so that incoming calls can be properly identified and processed.

- **Inbound trunk domain** – The unique domain assigned to your inbound trunk (for example, ``abcd123456.in.phone.systems``).
  This domain specifies the destination where phone.systems™ expects to receive inbound SIP traffic.

Together, these elements ensure that your VoIP provider correctly delivers inbound calls into the appropriate inbound trunk within phone.systems™, enabling your call flows, routing logic and extensions to handle the calls.

.. note:: Consult your VoIP provider for instructions on forwarding your DID numbers to the SIP URIs used by phone.systems™.

.. _ps3_inbound_trunk_domain:

View Inbound Call Forwarding Trunk Domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Each inbound trunk in phone.systems™ is assigned a unique SIP domain used by your VoIP provider when delivering inbound SIP traffic.

1. In the **Inbound Trunks** list, click the **Actions** button next to the trunk you want to view.
2. Select **Edit** to open the **Edit Inbound Trunk** window.

.. figure:: https://doc.didww.com/_images/actions_menu.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 2.** Opening the Edit window for an inbound trunk

3. The **Domain** appears in the **Edit Inbound Trunk** form at the top of the **General** section.
4. Click the **copy** icon next to the domain field to copy the value.

.. important:: This domain must be used by your VoIP provider when routing inbound calls to your phone.systems™ environment.

.. figure:: https://doc.didww.com/_images/domain_copy.png
   :figclass: align-center
   :alt: Inbound Trunk Domain Field

   **Fig. 3.** Copying the inbound trunk domain

----

.. _ps3_inbound_trunk_create:

.. raw:: html

   <br>

Creating Inbound Trunks
-----------------------

Use inbound trunks to define how incoming SIP traffic from your providers is received and processed by phone.systems™.

To create a new inbound trunk:

1. Go to the **Inbound Trunks** tab under **Trunks**.
2. Click the |+-symbol| button in the lower-right corner to open the **Create Inbound Trunk** window.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: Create Inbound Trunk window

   **Fig. 4.** Creating an inbound trunk

.. _ps3_inbound_trunk_general_settings:

General Settings
^^^^^^^^^^^^^^^^

The **General** section defines the core behavior of the inbound trunk.

.. list-table::
   :header-rows: 1

   * - **Setting**
     - **Description**
   * - **Friendly Name**
     - A descriptive name for the inbound trunk.
   * - **Transport Protocol**
     - Specifies the SIP transport method. Available options are:

        - **UDP**
        - **TCP**
        - **TLS**
   * - **Lookup destination by**
     - Determines how phone.systems™ identifies the destination for incoming calls. Available options are:

        - **R-URI username part** - Uses the **Request-URI** user portion.
        - **To header username part** - Uses the **To** header user portion.
   * - **Allowed Codecs**
     - Multiple codecs may be selected for call negotiation. Options include:

        - **OPUS**
        - **G722**
        - **PCMU**
        - **PCMA**
        - **G729**
        - **GSM**
        - **telephone-event**

.. note::
   The codec priority may be rearranged by dragging the listed codecs into the desired order. The left-most codec has the highest priority.

.. important::
   To use DTMF functions such as Interactive Menu navigation or Feature Codes, ensure that **telephone-event** is included in the Allowed Codecs list.

.. figure:: https://doc.didww.com/_images/general.png
   :figclass: align-center
   :alt: General settings for an inbound trunk

   **Fig. 5.** Inbound trunk general settings

.. _ps3_inbound_trunk_registration_settings:

Registration Settings
^^^^^^^^^^^^^^^^^^^^^

If your provider requires SIP registration, enable **Registration** and enter the parameters supplied by your service provider or system administrator:

.. list-table::
   :header-rows: 1

   * - **Field**
     - **Description**
   * - **Domain**
     - The SIP registrar domain used for registration.
   * - **Port**
     - The SIP registrar port. If left empty, the SRV or A record will be used.
   * - **Username**
     - The SIP username provided by your VoIP service provider.
   * - **Password**
     - The authentication password for SIP registration.
   * - **Contact User**
     - The value that will appear in the Contact header’s user part during registration.

.. note::
   Registration is disabled by default.

.. figure:: https://doc.didww.com/_images/registration.png
   :figclass: align-center
   :alt: Registration settings for an inbound trunk

   **Fig. 6.** Registration settings

.. _ps3_inbound_trunk_cli_rules:

CLI Rules
^^^^^^^^^

**CLI Rules** allow you to override the Source Caller Name or Destination number for calls received on the inbound trunk.
This functionality enables flexible number handling and helps you identify which inbound trunk was used to receive a call.

.. list-table::
   :header-rows: 1

   * - **Field**
     - **Description**
   * - **SRC number rule**
     - Select a predefined rule that normalizes the Source Number (CLI):

         - **Remove + if exist** – Removes the leading ``+`` if the number includes it.
         - **Add + if doesn't exist** – Adds a leading ``+`` if it is missing.
   * - **SRC Name Rewrite Rule**
     - POSIX Regular Expression pattern used to match the Source Caller Name.
   * - **SRC Name Rewrite Result**
     - Replacement text applied when the Rewrite Rule matches.
   * - **DST Rewrite Rule**
     - POSIX Regular Expression pattern used to match the destination number.
   * - **DST Rewrite Result**
     - Replacement text applied when the Rewrite Rule matches.

.. note::
   Knowledge of POSIX Regular Expressions is required to configure CLI Rules.

After completing the CLI Rules configuration, click **Save** to create the inbound trunk.

.. figure:: https://doc.didww.com/_images/cli-rules.png
   :figclass: align-center
   :alt: CLI Rules for an inbound trunk

   **Fig. 7.** CLI Rules

----

.. raw:: html

   <br>

.. _ps3_edit_inbound_trunks:

Editing Inbound Trunks
----------------------

To update the configuration of an existing inbound trunk:

1. In the **Inbound Trunks** list, click the **Actions** button next to the trunk you want to modify.
2. Select **Edit** to open the **Edit Inbound Trunk** window.

.. figure:: https://doc.didww.com/_images/actions_menu.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 8.** Opening the Edit window for an inbound trunk

3. Adjust the settings in the **General**, **Registration**, or **CLI Rules** sections as required.
4. Click **Save** to apply your changes.

.. figure:: https://doc.didww.com/_images/edit.png
   :figclass: align-center
   :alt: Edit Inbound Trunk window

   **Fig. 9.** Editing an inbound trunk

----

.. raw:: html

   <br>

.. _ps3_delete_inbound_trunks:

Deleting Inbound Trunks
-----------------------

To delete an existing inbound trunk:

1. In the **Inbound Trunks** list, click the **Actions** button next to the trunk you want to remove.
2. Select **Delete** to open the **Delete Inbound Trunk** dialog.

.. figure:: https://doc.didww.com/_images/actions_delete.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 10.** Opening the Delete dialog for an inbound trunk

3. To permanently delete the inbound trunk and unlink its relations, enable the **Delete and unlink relations** toggle.
4. Click **Delete** to confirm.

.. note::
   Deleting an inbound trunk also removes all linked relations.
   This may disrupt existing call routing or connected services.
   If you prefer not to proceed, close the dialog and update or remove the related items manually.

.. figure:: https://doc.didww.com/_images/delete.png
   :figclass: align-center
   :alt: Delete Inbound Trunk dialog

   **Fig. 11.** Delete Inbound Trunk dialog

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_outbound_gateways:

====================
Termination Gateways
====================

**Termination Gateways** define how phone.systems™ sends outbound SIP traffic to external destinations, such as third-party SIP termination providers or PSTN networks.

Each termination gateway represents a connection to a provider used for outbound calling and is configured under the **Trunks** section.

To access and manage termination gateways, click **Trunks** in the sidebar menu and select the **Termination Gateways** tab.

.. figure:: https://doc.didww.com/_images/fig1.png
   :figclass: align-center

   **Fig. 1.** Termination Gateways

----

.. raw:: html

   <br>

Creating Termination Gateways
-----------------------------

To create a new termination gateway:

1. Go to the **Termination Gateways** tab under **Trunks**.
2. Click the |+-symbol| button in the lower-right corner to open the **Create Termination Gateway** window.

.. figure:: https://doc.didww.com/_images/create-gateway.png
   :figclass: align-center
   :alt: Create Termination Gateway window

   **Fig. 2.** Creating a termination gateway

.. _ps3_termination_gateway_general_settings:

General Settings
^^^^^^^^^^^^^^^^

The **General Settings** section defines the core connectivity and authentication parameters used for outbound calls.

.. list-table::
   :header-rows: 1

   * - **Setting**
     - **Description**
   * - **Name**
     - A friendly name for this gateway.
   * - **Network Protocol**
     - Specifies the network protocol configuration:

        - **IPv4 Only** – Only IPv4 addresses are supported.
        - **IPv6 Only** – Only IPv6 addresses are supported.
        - **Dualstack** – Supports both IPv4 and IPv6.
        - **IPv4 Preferred** – IPv4 is preferred, but IPv6 can be used if needed.
        - **IPv6 Preferred** – IPv6 is preferred, but IPv4 can be used if needed.
   * - **Transport Protocol**
     - Specifies the SIP transport method. Available options are:

        - **UDP**
        - **TCP**
        - **TLS**
   * - **Username**
     - The username used to authenticate the gateway.
   * - **Password**
     - The password used for authenticating the gateway.
   * - **Host**
     - The IP address or domain name of the gateway.
   * - **Port**
     - The port used on this gateway. Defaults to ``5060`` if not provided.
   * - **Allowed Codecs**
     - Multiple codecs may be selected for call negotiation. Options include:

        - **OPUS**
        - **G722**
        - **PCMU**
        - **PCMA**
        - **G729**
        - **GSM**
        - **telephone-event**

.. note::
   The codec priority may be arranged by dragging the listed codecs into the required position,
   with the left-most codec being of the highest priority.

.. important::
   To use DTMF functions such as Interactive Menu options or Feature Codes,
   ensure that **telephone-event** is included in the Allowed Codecs list.

.. figure:: https://doc.didww.com/_images/fig2.png
   :figclass: align-center
   :alt: Termination gateway general settings

   **Fig. 3.** Termination gateway general settings

.. _ps3_termination_gateway_cli_rules:

CLI Rules
^^^^^^^^^

**CLI Rules** are used to automatically modify the source and destination numbers sent to the termination gateway.
This allows you to add or remove prefixes, or rewrite numbers per gateway.

.. list-table::
   :header-rows: 1

   * - **Field**
     - **Description**
   * - **SRC Name Rewrite Rule**
     - POSIX Regular Expression pattern used to match the Source Caller Name.
   * - **SRC Name Rewrite Result**
     - Replacement text applied when the Rewrite Rule matches.
   * - **DST Rewrite Rule**
     - POSIX Regular Expression pattern used to match the destination number.
   * - **DST Rewrite Result**
     - Replacement text applied when the Rewrite Rule matches.

.. note::
   Knowledge of POSIX Regular Expressions is required to configure CLI Rules.

After completing the configuration, click **Save** to create the termination gateway.

.. figure:: https://doc.didww.com/_images/fig3.png
   :figclass: align-center
   :alt: CLI Rules for a termination gateway

   **Fig. 4.** CLI Rules

----

.. raw:: html

   <br>

.. _ps3_edit_termination_gateways:

Editing Termination Gateways
----------------------------

1. In the **Termination Gateways** list, click the **Actions** button next to the gateway you want to modify.
2. Select **Edit** to open the **Edit Termination Gateway** window.

.. figure:: https://doc.didww.com/_images/fig8.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 5.** Opening the Edit window for a termination gateway

3. Adjust the settings in the **General Settings** or **CLI Rules** sections as required.
4. Click **Save** to apply your changes.

.. figure:: https://doc.didww.com/_images/edit_window.png
   :figclass: align-center
   :alt: Edit Termination Gateway window

   **Fig. 6.** Editing a termination gateway

----

.. raw:: html

   <br>

.. _ps3_gateway_relations:

Termination Gateway Relations
-----------------------------

The **Relations** view provides an overview of all configurations associated with the termination gateway.

To access it:

1. In the **Termination Gateways** list, click the **Actions** button next to the gateway.
2. Select **Relations**.

.. figure:: https://doc.didww.com/_images/fig8.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 7.** Opening Relations for a termination gateway

This view shows related configurations, such as **Termination Routes**.
To navigate to the related section, click the |gear| icon next to the relation.

.. figure:: https://doc.didww.com/_images/relations.png
   :figclass: align-center
   :alt: Termination Gateway Relations

   **Fig. 8.** Termination gateway relations

----

.. raw:: html

   <br>

.. _ps3_delete_termination_gateways:

Deleting Termination Gateways
-----------------------------

1. In the **Termination Gateways** list, click the **Actions** button next to the gateway you want to remove.
2. Select **Delete** to open the **Delete Termination Gateway** dialog.

.. figure:: https://doc.didww.com/_images/fig8.png
   :figclass: align-center
   :alt: Actions Menu

   **Fig. 9.** Opening the Delete dialog for a termination gateway

3. To permanently delete the termination gateway and unlink its relations, enable the **Delete and unlink relations** toggle.
4. Click **Delete** to confirm.

.. note::

   Deleting a termination gateway also deletes and unlinks all associated relations.
   Unlinking these relations may disrupt connected services.
   If you prefer not to proceed, close the dialog and update or remove the connections manually.

.. figure:: https://doc.didww.com/_images/delete_dialog.png
   :figclass: align-center
   :figwidth: 45%
   :alt: Delete Termination Gateway dialog

   **Fig. 10.** Delete Termination Gateway dialog

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |gear| image:: ../assets/img/guide-v2/inline-img/gear.svg
   :class: inline-img no-shadow
   :width: 20px
   :height: 20px


==================
Termination Routes
==================

Comprehensive and flexible route configuration options are available,
with multiple routes being able to share outbound gateways if required.
Routes add flexibility for routing outbound calls, such as using
different service providers when calling specific countries so as to
minimize calling costs or to localize dialing patterns when calling a
specific country.

At least one route must be created and assigned to a previously
configured outbound gateway.

To access and manage your termination routes, click **Trunks** in the sidebar menu and select the **Termination Routes** tab.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 1.** Termination Routes

____

Adding and Configuring Termination Routes
--------------------------------------------------------------------------

**Step 1.**  To add a new termination route, click on the |+-symbol| button. Alternatively, click on the **Edit** button to modify a previously configured route.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center

  **Fig. 1.** Editing And Creating Termination Routes

**Step 2:**  Input the **General Settings**:

-  **Name:** a friendly name to identify the route.

-  **SRC Prefix (optional):** The source prefix which defines the outbound
   CLI that will cause this route to be selected. Leaving this field
   empty implies that this route may be used with any CLI. If several
   routes are added with the same starting prefix digit (for example 3,
   37, 371), then the route with the closest match to the CLI will be
   used for the call.

-  **DST Prefix (optional):** The called destination prefix that will cause
   this route to be selected (for example dialing 44 for the United
   Kingdom). If this route may be used for calling any destination, then
   the DST Prefix should be left blank. If several routes are added with
   the same starting prefix digit (for example 3, 37, 371), then the
   route with the closest DST prefix match will be used for the call.

-  **Gateway:** The outbound gateway that is assigned to this route.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 2.** Configuring Termination Routes

**Step 3:** Configure CLI Rules (Optional):

The **CLI Rules** are available for the modification of source and destination numbers, allowing users to include rewrite rules such as adding prefixes to numbers or deleting country codes from numbers on a per-route basis.

-  **SRC Rewrite Rule/Result (optional):** Modifies the source number that
   phone.systems™ sends to the provider’s termination gateway.

-  **DST Rewrite Rule/Result (optional):** Modifies the calling destination
   number that is sent to the provider’s gateway.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center

  **Fig. 3.** CLI Rules

If no changes are required to be made to the numbers when making
outbound calls, then the Rule and Result fields should be left blank.

.. Note:: Knowledge in using POSIX Regular Expressions is required in order to use this feature.

**Step 4:** Click **Save** to finalize and create or edit your termination routes.

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. _ps3_call_analytics:

==============
Call Analytics
==============

Review call activity, outcomes, and performance in one place.

**Call Analytics** provides access to call records and aggregated statistics in **phone.systems™**. Use it to investigate specific calls, understand how calls were routed, and track overall inbound and outbound call performance over time. It is most useful for troubleshooting delivery issues, validating call outcomes, and preparing operational reports.

----

.. grid:: 1 1 2 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`list-unordered` **Call History**
      :link: call-history
      :link-type: doc
      :text-align: left

      Review and manage call detail records (CDRs) for calls handled by phone.systems™.

   .. grid-item-card:: :octicon:`arrow-right` **Routing Attempts**
      :link: routing-attempts
      :link-type: doc
      :text-align: left

      Review individual routing attempts performed during call processing.

   .. grid-item-card:: :octicon:`graph` **Call Statistics**
      :link: call-statistics
      :link-type: doc
      :text-align: left

      Analyze aggregated inbound and outbound call metrics and trends over time.

   .. grid-item-card:: :octicon:`person` **User Statistics**
      :link: user-statistics
      :link-type: doc
      :text-align: left

      Compare inbound call offers and outbound call performance for individual users.

.. toctree::
   :maxdepth: 1
   :hidden:

   Call History <call-history.rst>
   Routing Attempts <routing-attempts.rst>
   Call Statistics <call-statistics.rst>
   User Statistics <user-statistics.rst>


.. _ps3_call_flow_cdrs:
.. _ps3_call_history:

.. |br| raw:: html

   <br />

============
Call History
============

Review and manage call detail records (CDRs) for calls handled by **phone.systems™**.

**Call History** shows call direction, endpoints, timing, and outcome for each record.
Use it to find calls by time range, status, or numbers, then open a record to confirm what happened (for example, why a call was lost or how it ended).
It also shows assigned call tags and available attachments such as notes, recordings, voicemail, fax, and AI insights.
You can also download filtered CDRs for reporting and resolve lost calls when required.

.. important::
   The date and time displayed in Call History are based on the time zone settings of the device in use.
   For example, if the device is set to UTC+1, the CDRs will appear in the UTC+1 time zone.

.. .. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`list-unordered` **Call Detail Records**
      :link: ps3_call_history_call_records
      :link-type: ref
      :text-align: left

      Understand the Call History table layout, column meanings, and how call direction, source, and destination are represented.

   .. grid-item-card:: :octicon:`filter` **Filters**
      :link: ps3_call_history_filters
      :link-type: ref
      :text-align: left

      Filter call records by time range, status, direction, source, destination, numbers, tags, and note or attachment availability.

   .. grid-item-card:: :octicon:`gear` **Call History Actions**
      :link: ps3_call_history_actions
      :link-type: ref
      :text-align: left

      Download filtered records, reload the current view, and navigate pages using pagination and page size controls.

   .. grid-item-card:: :octicon:`eye` **View Call Detail Record Details**
      :link: ps3_call_history_view_record
      :link-type: ref
      :text-align: left

      Open a single call detail record to view full timing, endpoints, status, end codes, tags, and attachments.

   .. grid-item-card:: :octicon:`issue-opened` **Call Outcome**
      :link: ps3_call_history_call_outcome
      :link-type: ref
      :text-align: left

      Learn how call status and end codes are determined and how lost calls can be resolved.

   .. grid-item-card:: :octicon:`paperclip` **Attachments**
      :link: ps3_call_history_attachments
      :link-type: ref
      :text-align: left

      Access notes, AI call insights, recordings, voicemail messages, and fax files linked to a call.

----

.. _ps3_call_history_filters:

Filters
-------

.. list-table::
   :header-rows: 1
   :widths: 20 70

   * - **Filter**
     - **Description**
   * - **Time range**
     - Filter records by selecting a predefined period or setting a custom start and end date and time.
   * - **Numbers**
     - Filter inbound and outbound call records by entering one or more phone numbers. For outbound calls, each entered number is matched against the source number. For inbound calls, each entered number is matched against the destination number.
   * - **Status**
     - Filter by call status (**Answered**, **Lost**, or **Resolved**).
   * - **Type**
     - Filter by call direction (**Inbound**, **Outbound**, or **Internal**).
   * - **Source**
     - Filter by the source type and value (for example, **User** or **Incoming trunk**).
   * - **Source number**
     - Filter by the caller phone number.
   * - **Destination**
     - Filter by the destination type and value (for example, **User**, **Call Flow**, **PSTN**, or **Call Pick-Up**).
   * - **Destination number**
     - Filter by the dialed (destination) phone number.
   * - **Source contact method**
     - Filter by the source-side contact method (for example, **Application**, **SIP Account**, **SIP Forwarding**, or **PSTN Forwarding**).
   * - **Global tag**
     - Filter by the selected global tag.
   * - **Tags**
     - Filter by one or more call tags assigned to the call.
   * - **Has note**
     - Show only records with a saved call note.
   * - **Has recording**
     - Show only records with a call recording.
   * - **Has voicemail**
     - Show only records with a voicemail message.
   * - **Has fax**
     - Show only records with a fax attachment.
   * - **Has AI call insights**
     - Show only records with AI call insights.

.. note::

   - Filters can be used individually or in combination. When multiple filters are applied,
     only call records that match all selected criteria are shown.
   - If you do not see all available filters, click **More filters** and add the filters you need.
   - The **Numbers** filter accepts multiple values separated by commas or spaces
     (for example, ``12025550123, 12025550124`` or ``12025550123 12025550124``).
   - The selected time range is retained when you navigate between **Call History**,
     **Routing Attempts**, and **Call Statistics**. It resets when you leave **Call Analytics**.
   - The **Source** and **Destination** filters display additional fields based on the selected type:

     - Selecting **Source: User** shows the **Source user** filter.
     - Selecting **Source: Incoming trunk** shows the **Inbound trunk** filter.
     - Selecting **Destination: User** shows the **Destination user** filter.
     - Selecting **Destination: Call Flow** shows the **Call Flow** filter.

     Use these additional filters to select a specific user, inbound trunk, or call flow.

----

.. _ps3_call_history_call_records:

Call History Table
-------------------------

The Call History table displays one record per call detail record (CDR) processed by **phone.systems™**.

.. list-table::
   :header-rows: 1
   :widths: 20 70

   * - **Column**
     - **Description**
   * - **Type**
     - Icon that indicates the call direction.
       :ref:`Learn more about Call Direction <ps3_call_direction>`.
   * - **Time start**
     - The date and time when the call was initiated.
   * - **Wait time**
     - The duration between call initiation and connection.
   * - **Talk time**
     - The duration of the call after it was connected.
   * - **Source**
     - The call origin displayed as a single cell with stacked details.
       :ref:`Learn more about Source <ps3_call_source>`.
   * - **Source number**
     - The phone number from which the call originated.
   * - **Destination number**
     - The phone number the call was routed to.
   * - **Destination**
     - The call destination displayed as a single cell with stacked details.
       :ref:`Learn more about Destination <ps3_call_destination>`.
   * - **End code**
     - The reason the call ended.
       :ref:`Learn more about End codes <ps3_call_history_end_codes>`.
   * - **Status**
     - The current or final call status.
       :ref:`Learn more about Status <ps3_call_history_call_status>`.
   * - **Resolved by**
     - Resolution details for lost or resolved calls.
       :ref:`Learn how to resolve lost calls <ps3_call_history_resolve_lost_calls>`.
   * - **Tags**
     - Assigned call tags displayed for the call record :ref:`Learn more about tags <ps3_settings_call_tags>`.
   * - **Attachments**
     - Indicators for available notes, AI insights, or media files.
       :ref:`Learn more about Call attachments <ps3_call_history_attachments>`.
   * - **Routing attempt**
     - The number of routing attempts made for the call.
   * - **Call ID**
     - The unique identifier of the call record.

.. note::
   Some columns display icons and stacked labels to show related information in a single cell,
   such as :ref:`Source <ps3_call_source>`, :ref:`Destination <ps3_call_destination>`, Tags, and :ref:`Attachments <ps3_call_history_attachments>`.

----

Call History Table Column Details
---------------------------------

The Call History table includes several columns that use labels, icons, or stacked values to represent call direction, endpoints, outcomes, and available attachments. Use these definitions when you need to interpret a record accurately for example, to confirm who initiated the call, where it was routed, why it ended, or whether recordings and other media are available.

.. raw:: html

   <br>

.. _ps3_call_direction:

Type: Call Direction
^^^^^^^^^^^^^^^^^^^^

Call direction explains what kind of call the record represents: inbound to your organization, outbound from a user, or internal between users.
Use it when filtering call records, investigating missed calls, or confirming whether a call came from outside the organization or was placed by a user.

The **Type** column indicates the call direction from the system perspective, based on how the call enters and exits **phone.systems™**.

- **Inbound** - A call received by a phone.systems™ :ref:`user <ps3_users>`.
- **Outbound** - A call initiated by a phone.systems™ :ref:`user <ps3_users>`.
- **Internal** - A call between users using :ref:`internal numbers <ps3_internal_numbers>`.

.. figure:: https://doc.didww.com/_images/type.png
   :figclass: align-center
   :alt: Type column showing inbound, outbound, and internal call directions
   :width: 100%

   **Fig. 1.** Type column showing call direction

.. raw:: html

   <br>

.. _ps3_call_source:

Source
^^^^^^

Source shows where the call came from and how it entered **phone.systems™**.
Use it to confirm whether the call was initiated by an internal user or received through an inbound trunk, especially when troubleshooting call issues or validating call origin.

The Source value is displayed differently depending on its type.

.. tab-set::
   :class: my-tabs

   .. tab-item:: User

      User source type means the call was initiated by a user in your organization using a configured contact method.

      The source cell is displayed as a stacked value:

          - The top line shows the user name.
          - The second line shows the contact method used to place the call
            (for example, **Application** or **SIP Account**).

      .. note:: If a user no longer exists, the user is shown as **Deleted**.

      .. figure:: https://doc.didww.com/_images/source_user.png
         :figclass: align-center
         :alt: Source column showing a user with a contact method
         :width: 100%

         **Fig. 2.** Source column for a user-originated call

   .. tab-item:: Incoming trunk

      Incoming trunk source type means the call entered **phone.systems™** from the PSTN through an inbound trunk.

      The source cell is displayed as a stacked value:

           - The top line shows the inbound trunk name.
           - The second line shows the source type (for example, **Inbound trunk**).

      This source type indicates that the call was received from the PSTN,
      either through a DIDWW-managed trunk or a third-party trunk
      connected to **phone.systems™**.

      .. note::
         - The default DIDWW-managed phone.systems™ trunk is shown as **System**.
         - If an inbound trunk no longer exists, the trunk is also shown as **Deleted**.

      .. figure:: https://doc.didww.com/_images/source_trunk.png
         :figclass: align-center
         :alt: Source column showing an incoming trunk
         :width: 100%

         **Fig. 3.** Source column for a call received via an incoming trunk

.. raw:: html

   <br>

.. _ps3_call_destination:

Destination
^^^^^^^^^^^

Destination shows where the call was routed by **phone.systems™**.
Use it to confirm which user, number, or routing component received the call—for example, when troubleshooting missed calls, validating call flow behavior, or checking where an inbound call was forwarded.

The Destination value is displayed differently depending on its type.

.. note::
   - Destination may be empty if the call is rejected by the system (for example, when calling a non-existing number).
   - If the referenced user, call flow, or contact method no longer exists, the value is shown as **unknown**.

.. tab-set::
   :class: my-tabs

   .. tab-item:: User

      User destination type means the call was routed to a user in your organization.

      The destination cell is displayed as a stacked value:

      - The top line shows the user name.
      - The second line shows the destination contact method (for example, **Application** or **PSTN Forwarding**).

      .. figure:: https://doc.didww.com/_images/destination_user.png
         :figclass: align-center
         :alt: Destination column showing a user with a contact method
         :width: 100%

         **Fig. 4.** Destination column for a user

   .. tab-item:: PSTN

      PSTN destination type means the call was routed to a public phone number.

      .. figure:: https://doc.didww.com/_images/destination_pstn.png
         :figclass: align-center
         :alt: Destination column showing a PSTN number
         :width: 100%

         **Fig. 5.** Destination column for a PSTN destination

   .. tab-item:: Call Flow

      Call Flow destination type means the call was routed to a call flow.

      The destination cell is displayed as a stacked value:

      - The top line shows the call flow name.
      - The second line shows the destination type (**Call Flow**).

      .. figure:: https://doc.didww.com/_images/destination_callflow.png
         :figclass: align-center
         :alt: Destination column showing a call flow
         :width: 100%

         **Fig. 6.** Destination column for a call flow

   .. tab-item:: Call Pick-Up

      Call Pick-Up destination type means the call was handled through a call pick-up configuration and it is triggered using a feature code.
      For configuration and usage details, see
      :ref:`Call Pickup feature code <ps3_feature_code_call_pickup>`.

      .. figure:: https://doc.didww.com/_images/destination_callpickup.png
         :figclass: align-center
         :alt: Destination column showing a call pick-up destination
         :width: 100%

         **Fig. 7.** Destination column for a call pick-up destination

.. raw:: html

   <br>

.. _ps3_call_history_end_codes:

End Codes
^^^^^^^^^

End codes explain why a call ended in **phone.systems™**.
Use them to troubleshoot call issues and understand the final result of a call—for example, whether the caller hung up, the call timed out, a redirect failed, or routing was blocked.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Reason**
     - **Description**
   * - Connected to agent
     - The call was successfully connected to a live agent.
   * - Waiting timeout
     - The caller waited too long without being connected and timed out.
   * - Disconnect from originator
     - The caller disconnected before the call was picked up.
   * - Pick-up
     - The call was picked up by the recipient.
   * - Redirect
     - The call was redirected to another destination.
   * - Redirect Failed
     - The call could not be redirected to the intended destination.
   * - Not allowed by scheduler
     - Call redirected to voicemail by the scheduler due to restrictions.
   * - User not available
     - Destination contact method not registered, no response, or error.
   * - Too many redirects
     - The call was redirected too many times, causing a failure.
   * - Failed
     - Generic failure without a detailed error code.
   * - Channels Overload
     - Too many concurrent calls, resulting in a channel capacity issue.
   * - Account blocked
     - The account is blocked.
   * - PSTN termination blocked
     - PSTN termination is blocked.
   * - External calls not allowed
     - Outbound number not set for the calling device, blocking the call.
   * - PSTN Termination error
     - Call failed due to a disconnect reason from PSTN forwarding.
   * - PSTN Termination billing error
     - Call failed due to a billing issue from PSTN services.
   * - Wrong Number
     - The number is incorrect, causing routing to fail.

.. raw:: html

   <br>

.. _ps3_call_history_call_status:

Status
^^^^^^^^^^^

Status shows the current or final outcome of a call in **Call History**.
Use it to quickly identify answered calls, missed calls that require follow-up (**Lost**), and calls that have already been handled (**Resolved**), especially when filtering records or tracking missed-call resolution.

Each call in Call History is assigned a **status** that reflects its current or final outcome.

- **Answered** - The call was successfully connected, and media was exchanged between the caller and the destination.
- **Lost** - The call was not answered by the destination. This status remains until the call is resolved automatically (for example, after a successful callback) or manually by a user. :ref:`Learn how to resolve lost calls <ps3_call_history_resolve_lost_calls>`.
- **Resolved** - A call that was previously **Lost** and later resolved, either automatically or manually.
- **Processing** - A temporary state while the system determines the final outcome of the call.

.. raw:: html

   <br>

.. _ps3_call_history_attachments:

Attachments
^^^^^^^^^^^

The **Attachments** column provides access to additional data associated with a call, such as notes, AI analysis, recordings, voicemail messages, and fax files.

.. note::
   Media attachments such as AI insights, recordings, voicemail, and fax are shown in **Call History** only when
   :ref:`cloud storage <ps3_cloud_storage_integrations>` is enabled.

.. tab-set::
   :class: my-tabs

   .. tab-item:: AI Call Insights

      .. _ps3_call_history_ai:

      AI Call Insights provide automated analysis for recorded calls, including summaries, sentiment analysis, key topics, and full transcripts.
      Use them to quickly review what was discussed on a call without listening to the entire recording.

      .. note::
         - AI Call Insights are available only when they are :ref:`enabled in AI Settings <ps3_ai_settings_enable>`.
         - AI processing begins once the call has been connected for at least 15 seconds. Calls shorter than 15 seconds, or with an audio file exceeding 25 MB, are not processed.

      To view AI insights for a call:

      1. In **Call Analytics → Call History**, locate a call record with the AI icon.
      2. Click the **AI** icon in the **Attachments** column.

      The **AI Call Insights** view opens and displays the analysis results for that call.

      .. figure:: https://doc.didww.com/_images/ai_overview.png
         :figclass: align-center
         :alt: AI Call Insights overview
         :width: 100%

         **Fig. 8.** AI Call Insights overview

   .. tab-item:: Call Recording

      .. _ps3_call_flow_cdrs_recording:
      .. _ps3_call_history_recording:

      Call recordings let you review the audio of a call directly from **Call History**.
      Use them to verify what was said, confirm call handling, or support troubleshooting and quality checks.

      .. note::
         Call recordings are shown in **Call History** only when
         :ref:`cloud storage <ps3_cloud_storage_integrations>` is enabled.

      To listen to a call recording:

      1. In **Call Analytics → Call History**, locate a call record that has a recording available.
      2. Click the **Recording** (microphone) icon in the **Attachments** column.

      The **Call Recording** window opens, where you can play the recording and download the file.

      .. figure:: https://doc.didww.com/_images/recording_listen.png
         :figclass: align-center
         :alt: Call Recording window
         :width: 100%

         **Fig. 9.** Call Recording window with playback and download controls

   .. tab-item:: Voicemail

      .. _ps3_call_flow_cdrs_voicemail:
      .. _ps3_call_history_voicemail:

      Voicemail messages let you review missed-call messages directly from **Call History**.
      Use them to capture caller information and follow up without returning the call immediately.

      .. note::
         Voicemails are shown in **Call History** only when
         :ref:`cloud storage <ps3_cloud_storage_integrations>` is enabled.

      To listen to a voicemail message:

      1. In **Call Analytics → Call History**, locate a call record that has a voicemail available.
      2. Click the **Voicemail** icon in the **Attachments** column.

      The **Voicemail** window opens, where you can play the message and download the file.

      .. figure:: https://doc.didww.com/_images/voicemail_listen.png
         :figclass: align-center
         :alt: Voicemail playback window
         :width: 100%

         **Fig. 10.** Voicemail playback window with controls

   .. tab-item:: Fax

      .. _ps3_call_flow_cdrs_fax:
      .. _ps3_call_history_fax:

      Fax attachments let you download fax documents as part of a call record.
      Use them when you need to retrieve the original fax file for processing, storage, or follow-up.

      To download a fax document:

      1. In **Call Analytics → Call History**, locate a call record that has a fax available.
      2. Click the **Fax** icon in the **Attachments** column.

      .. figure:: https://doc.didww.com/_images/attachments_fax.png
         :figclass: align-center
         :alt: Fax icon in Attachments column
         :width: 100%

         **Fig. 11.** Fax indicator in the Attachments column

   .. tab-item:: Notes

      .. _ps3_call_history_notes:

      Notes let you add and review text details associated with a call directly from **Call History**.
      Use notes to store conversation summaries, follow-up reminders, or other context that is not captured in call metadata.

      To view a call note:

      1. In **Call Analytics → Call History**, locate a call record with the **Note** icon in the **Attachments** column.
      2. Click the **Note** icon to open the saved note for that call.

      .. figure:: https://doc.didww.com/_images/attachments_note.png
         :figclass: align-center
         :alt: Note in the Attachments column
         :width: 100%

         **Fig. 12.** Note in the Attachments column

----

.. _ps3_call_history_view_record:

View Call Detail Record Details
-------------------------------

Viewing a single call record allows you to inspect its call detail record (CDR) in a dedicated details view.

Use this view when you need to investigate a specific call in more detail for example, to confirm who called whom, when the call started, how it ended, which tags are assigned, and whether any attachments are available. It helps you validate the call outcome, review timing and endpoints, and access related data such as notes, recordings, voicemail, fax, or AI insights.

To view a call detail record:

1. Go to **Call Analytics → Call History**.
2. Locate the required call in the table.
3. Click **Actions → View**.

The call detail record (CDR) displays the same call direction, timing, endpoints, outcome, tags, and attachments described in the :ref:`Call History Table <ps3_call_history_call_records>` section.

.. figure:: https://doc.didww.com/_images/cdr_details.png
   :figclass: align-center
   :alt: Call detail record window
   :width: 100%

   **Fig. 13.** Call detail record window

----

.. _ps3_call_history_resolve_lost_calls:

Resolve Lost Calls
-------------------

A call is marked as **Lost** when it is not answered by the destination (for example, the user did not pick up, rejected the call, or the call timed out while ringing). To resolve a lost call, choose one of the options below to update the status in Call History.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Callback

      .. _ps3_call_history_resolve_lost_calls_auto:

      A lost call is resolved automatically when a successful callback is made to the number associated with the lost call.

      .. note::
         - The callback must successfully connect to an agent.
         - After a successful callback, the lost call is resolved within 72 hours.

   .. tab-item:: Resolve manually

      .. _ps3_call_history_resolve_lost_calls_manual:

      Resolve a lost call manually when the missed call was handled outside the automatic callback flow (for example, the caller was contacted through another channel or the issue was already addressed).

      To resolve a lost call manually:

      1. In **Call Analytics → Call History**, locate the call record with the **Lost** status.
      2. Click the **Actions** button for that call record.
      3. Select **Resolve**.
      4. In the confirmation pop-up, click **Confirm**.

      .. note::
         This action cannot be undone and will apply to all related lost calls.

      .. figure:: https://doc.didww.com/_images/resolve-confirmation.png
         :figclass: align-center
         :alt: Resolve confirmation
         :width: 100%

         **Fig. 14.** Resolve confirmation

----

.. _ps3_call_history_actions:

Call History Page Actions
--------------------------

Use the actions in Call History to download records, reload the view, and navigate through pages.

.. _ps3_call_history_download:

.. tab-set::
   :class: my-tabs

   .. tab-item:: Download CDRs

      Download the currently filtered Call History records as a CSV file.

      1. Apply the required filters to narrow down the records.
      2. Click the **Download** icon in the top-right corner of the table.
      3. Choose a destination on your device and confirm the download.

      .. figure:: https://doc.didww.com/_images/download-button.png
         :figclass: align-center
         :alt: Download icon in Call History table
         :width: 100%

         **Fig. 15.** Download Call History

   .. tab-item:: Reload

      Refresh the current view without changing your filters.

      To reload the Call History page, click the **reload** icon in the top-right corner of the page.

      .. figure:: https://doc.didww.com/_images/refresh.png
         :figclass: align-center
         :alt: Reload icon in Call History
         :width: 100%

         **Fig. 16.** Reload Call History view

   .. tab-item:: Pagination and page size

      Call History displays results across multiple pages. By default, each page shows **50** records.
      If you want to see more results at once, increase the page size up to **100**.
      Use the pagination controls to move to the next or previous page.

      .. figure:: https://doc.didww.com/_images/pagination.png
         :figclass: align-center
         :alt: Page size and pagination controls in Call History
         :width: 100%

         **Fig. 17.** Pagination controls


.. _ps3_routing_attempts:

.. |br| raw:: html

   <br />

================
Routing Attempts
================

Review how calls were routed, step by step.

**Routing Attempts** lists one record for each attempt **phone.systems™** makes while routing a call.
Use it to troubleshoot delivery issues (for example, failed or disconnected calls) by checking where the call was sent,
which route and gateway were used, and which disconnect code was returned.
It is also useful when you need to verify routing behavior for a specific destination or time period.

.. important::
   Times and timestamps are shown in the time zone of the device you are using. For example, if your device is set to UTC+1,
   Routing Attempts displays times in UTC+1.

----

.. _ps3_routing_attempts_filters:

Filters
-------

.. .. figure:: /phone-systems/assets/img/guide-v2/call_logs_charts_statistics/routing_attempts/filters.png
   :figclass: align-center
   :alt: Routing Attempts filters
   :width: 100%

   **Fig. 2.** Routing Attempts filter bar

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Filter**
     - **Description**
   * - **Time range**
     - Filters routing attempts by selecting a predefined period or setting a custom start and end date and time.
   * - **Numbers**
     - Filters routing attempts for inbound and outbound calls by entering one or more phone numbers. For outbound calls, each entered number is matched against the source number. For inbound calls, each entered number is matched against the destination number.
   * - **Destination**
     - Filters by destination type (for example, **User** or **PSTN number**).
   * - **Gateway**
     - Filters by the termination gateway.
   * - **Route**
     - Filters by the outbound route.
   * - **Source number**
     - Filters by the calling number.
   * - **Destination number**
     - Filters by the called number.
   * - **Disconnect code**
     - Filters by the disconnect code.
   * - **Global tag**
     - Filters by the system global tag.

.. note::

   - Filters can be used individually or in combination.
   - If you do not see all available filters, click **More filters** to add additional filters to the filter bar.
   - The **Numbers** filter accepts multiple values separated by commas or spaces
     (for example, ``12025550123, 12025550124`` or ``12025550123 12025550124``).
   - The selected time range is retained when you navigate between **Call History**,
     **Routing Attempts**, and **Call Statistics**. It resets when you leave **Call Analytics**.

----

.. _ps3_routing_attempts_records:

Routing Attempt Table
-----------------------

The Routing Attempts table displays one record per routing attempt performed by **phone.systems™**.

.. .. figure:: /phone-systems/assets/img/guide-v2/call_logs_charts_statistics/routing_attempts/table.png
   :figclass: align-center
   :alt: Routing Attempts table
   :width: 100%

   **Fig. 1.** Routing Attempts table

The following columns are available:

.. list-table::
   :header-rows: 1
   :widths: 25 70

   * - **Column**
     - **Description**
   * - **Time start**
     - The date and time when the routing attempt started.
   * - **Waiting time**
     - The time between the start of the routing attempt and the connection attempt.
   * - **In call time**
     - The duration of the call for this routing attempt, if the call connected.
   * - **Source**
     - The source used for this routing attempt (for example, a Call Flow).
   * - **Source number**
     - The calling number used for this routing attempt.
   * - **Destination**
     - The destination entity for this routing attempt (for example, a user or a PSTN number).
   * - **Destination number**
     - The number the call was routed to during this routing attempt.
   * - **Disconnect code**
     - The disconnect code returned when the routing attempt ended.
   * - **Outbound route**
     - The outbound route used for the routing attempt.

----

.. _ps3_routing_attempts_view_record:

View Routing Attempt Details
----------------------------

Viewing a single routing attempt allows you to inspect its routing attempt record
in a dedicated details view.

Use this view when you need to investigate a specific call attempt in more detail for example, to confirm why it succeeded or failed and how it was routed. It helps you validate the call outcome, review timing and participants, and cross-check routing information while troubleshooting or preparing reports.

To view a routing attempt:

1. Go to **Call Analytics → Routing Attempts**.
2. Locate the required routing attempt in the table.
3. Click **Actions → View**.

.. .. figure:: /phone-systems/assets/img/guide-v2/call_logs_charts_statistics/routing_attempts/actions.png
   :figclass: align-center
   :alt: Actions menu in Routing Attempts
   :width: 100%

   **Fig. 6.** Actions menu for a routing attempt

The routing attempt details view provides the same information shown in the Routing Attempts table
and includes additional fields grouped into sections, such as timing, result, participant details,
and routing information.

.. figure:: https://doc.didww.com/_images/routing_attempt_details.png
   :figclass: align-center
   :alt: Routing attempt details window
   :width: 100%

   **Fig. 7.** Routing attempt details window

Open Related Records
^^^^^^^^^^^^^^^^^^^^

In the routing information section of the routing attempt details view, you can open related records linked to the same call using a shared **Global tag**.

Use these links to quickly trace a specific call across views without reapplying filters. This is useful when you need to review what happened to a call (outcome, duration, routing path) or when investigating failed/short calls and verifying how the system routed them.

To open related records:

1. In **Call Analytics → Routing Attempts**, locate the required routing attempt.
2. Click **Actions → View**.
3. In the details window, click **View** next to:

   - **Related call history** to open **Call History**
   - **Related routing attempts** to open **Routing Attempts**

phone.systems™ opens the selected page with the corresponding **Global tag** filter applied, showing the related record(s).

.. figure:: https://doc.didww.com/_images/related_call_histories.png
   :figclass: align-center
   :alt: Related record links in Routing Attempt Details
   :width: 100%

   **Fig. 8.** Related record links

----

.. _ps3_routing_attempts_actions:

Routing Attempts Page Actions
------------------------------

Use the actions in Routing Attempts to reload the view and navigate through pages.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Reload

      Use **Reload** to refresh the list and fetch the latest routing attempts while keeping your current filters and page selection.
      This is useful if new records may have appeared since you opened the page or after you changed something and want to see updated results.

      To reload the Routing Attempts page, click the **reload** icon in the top-right corner.

      .. figure:: https://doc.didww.com/_images/reload.png
         :figclass: align-center
         :alt: Reload icon in Routing Attempts
         :width: 100%

         **Fig. 4.** Reload Routing Attempts view

   .. tab-item:: Pagination and page size

      Routing Attempts displays results across multiple pages. By default, each page shows **50** records. If you want to see more results at once, increase the page size up to **100**.
      Use the pagination controls to move to the next or previous page.

      .. figure:: https://doc.didww.com/_images/pagination.png
         :figclass: align-center
         :alt: Pagination controls in Routing Attempts
         :width: 100%

         **Fig. 5.** Pagination controls


.. _ps3_call_statistics:

===============
Call Statistics
===============

The **Call Statistics** page provides a high-level view of call performance for calls handled by **phone.systems™**.
Use it to review total call activity, call outcomes, duration-based metrics, and time-based trends for the selected period.

Call Statistics are based on the final outcome of completed calls and aggregated over the selected time period and filters.
Individual routing attempts are not displayed as separate records.

.. important::
   The date and time shown in **Call Statistics** follow the time zone used by the interface on the device in use.

----

Filters
=======

Use the filters at the top of the page to narrow down the displayed statistics.

.. list-table::
   :header-rows: 1
   :widths: 20 70

   * - **Filter**
     - **Description**
   * - **Time range**
     - Filter statistics by selecting a predefined period or setting a custom start and end date and time.
   * - **Numbers**
     - Filter statistics for inbound and outbound calls by entering one or more phone numbers. For outbound calls, each entered number is matched against the source number. For inbound calls, each entered number is matched against the destination number.
   * - **Source**
     - Filter by source type and value. Available source types are **User** and **Inbound trunk**.
   * - **Destination**
     - Filter by destination type and value. Available destination types are **User**, **PSTN**, **Call Flow**, and **Call Pick-up**.
   * - **Type**
     - Filter by call direction (**Inbound**, **Outbound**, or **Internal**).
   * - **Source number**
     - Filter by the caller phone number.
   * - **Destination number**
     - Filter by the callee phone number.

.. note::

   - Filters can be used individually or in combination. When multiple filters are applied,
     only statistics for calls that match all selected criteria are shown.
   - If you do not see all available filters, click **More filters** and add the filters you need.
   - The **Numbers** filter accepts multiple values separated by commas or spaces
     (for example, ``12025550123, 12025550124`` or ``12025550123 12025550124``).
   - The selected time range is retained when you navigate between **Call History**,
     **Routing Attempts**, and **Call Statistics**. It resets when you leave **Call Analytics**.
   - The **Source** and **Destination** filters display additional fields based on the selected type:

     - Selecting **Source: User** shows a user selector.
     - Selecting **Source: Inbound trunk** shows an inbound trunk selector.
     - Selecting **Destination: User** shows a user selector.
     - Selecting **Destination: Call Flow** shows a call flow selector.

     Use these additional filters to select a specific user, inbound trunk, or call flow.

----

Key metrics
===========

The summary cards at the top of the page display the main metrics for the selected period.

.. list-table::
   :header-rows: 1
   :widths: 24 76

   * - **Metric**
     - **Description**
   * - **Total calls**
     - The total number of calls included in the selected period and filter set.
   * - **Inbound calls**
     - The number of inbound calls included in the selected period.
   * - **Outbound calls**
     - The number of outbound calls included in the selected period.
   * - **Internal calls**
     - The number of internal calls included in the selected period.
   * - **Total call duration**
     - The combined call duration of all calls in the selected period.
   * - **Average call duration (ACD)**
     - The average call duration per call.
   * - **Average wait time (AWT)**
     - The average time callers waited before the call reached its final outcome.
   * - **Answer rate (ASR)**
     - The percentage of calls that were answered successfully.
   * - **AI billing**
     - The AI billing amount for the selected period when AI-related billing data is available.

.. figure:: https://doc.didww.com/_images/key-metrics.png
   :figclass: align-center
   :alt: Key metric cards in Call Statistics
   :width: 100%

   **Fig. 1.** Key metrics

Call outcomes
=============

The **Conversations** summary groups calls by their final outcome:

- **Answered** - The call was successfully connected and media was exchanged.
- **Lost** - The call was not answered by the destination.
- **Resolved** - A call that was previously lost and was later resolved.

These outcomes are also used in the **Call Volume** chart.

.. figure:: https://doc.didww.com/_images/call-outcomes.png
   :figclass: align-center
   :alt: Conversations summary showing answered, lost, and resolved call outcomes
   :width: 100%

   **Fig. 2.** Call outcomes summary

----

Charts
======

The charts on the **Call Statistics** page visualize how key metrics change over the selected period.

Chart navigation
----------------

Use the controls above the charts to change how data is displayed over time.

The available grouping tabs are:

- **Hour** - Groups values by hour.
- **Day** - Groups values by day.
- **Week** - Groups values by week.
- **Month** - Groups values by month.

Select a tab to update all charts to the chosen time grouping.

.. figure:: https://doc.didww.com/_images/time-grouping.png
   :figclass: align-center
   :alt: Time grouping tabs in Call Statistics
   :width: 100%

   **Fig. 3.** Time grouping tabs

You can zoom in to focus on a specific time range. Click and drag across the chart to select the period you want to view.

.. figure:: https://doc.didww.com/_images/zooming-in.gif
   :figclass: align-center
   :alt: Zooming in on a time range in Call Statistics charts
   :width: 100%

   **Fig. 4.** Zooming in on charts

Available charts
----------------

.. list-table::
   :header-rows: 1
   :widths: 24 76

   * - **Chart**
     - **Description**
   * - **Call Volume**
     - Shows the number of calls over time, grouped by final call outcome. The chart displays **Answered**, **Lost**, and **Resolved** values for each time bucket.
   * - **Average Call Duration (ACD, sec)**
     - Shows how average call duration changes over time.
   * - **Average Wait Time (AWT, sec)**
     - Shows how average wait time changes over time.
   * - **Answer Rate (ASR %)**
     - Shows how answer rate changes over time.
   * - **AI Billing amount (USD)**
     - Shows AI billing values for the selected period when AI-related billing data is available.

.. figure:: https://doc.didww.com/_images/charts.png
   :figclass: align-center
   :alt: Charts shown in Call Statistics
   :width: 100%

   **Fig. 5.** Available charts


.. _ps3_user_statistics:

===============
User Statistics
===============

Review inbound and outbound call performance for individual **phone.systems™** users.

The **User Statistics** page summarizes how many inbound call offers each user received and how many outbound calls each user made. Use it to compare user activity, answer rates, wait times, and call duration over a selected period.

Inbound calls are measured as **offers** because one call can be offered to a user without being answered. Outbound activity is measured as **calls** initiated by the user.

.. important::
   The date and time shown in **User Statistics** follow the time zone used by the interface on the device in use.

----

Filters
=======

The filters at the top of the page apply to both the **Inbound Calls** and **Outbound Calls** tables.

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Filter**
     - **Description**
   * - **Time range**
     - Required date and time range for the displayed statistics. The maximum range is the last 3 months.
   * - **User**
     - Filters the tables by one or more selected users. Leave the filter set to **Any** to include all users.

----

Inbound Calls
=============

The **Inbound Calls** table summarizes call offers presented to each user during the selected period. An offer is counted each time **phone.systems™** attempts to deliver an inbound call to a user.

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Column**
     - **Description**
   * - **User**
     - User who received the inbound call offers.
   * - **Total offers**
     - Total number of inbound call offers presented to the user.
   * - **Answered offers**
     - Number of inbound call offers answered by the user.
   * - **Average wait time**
     - Average time callers waited before the call offer reached its final outcome.
   * - **Average call duration**
     - Average call duration per answered offer.
   * - **Answer rate**
     - Percentage of call offers that were answered successfully.

.. figure:: https://doc.didww.com/_images/user-statistics-inbound.png
   :alt: Inbound Calls table with offer counts, wait times, call durations, and answer rates by user
   :figclass: align-center

   **Fig. 1.** Inbound Calls statistics

----

Outbound Calls
==============

The **Outbound Calls** table summarizes calls initiated by each user during the selected period.

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - **Column**
     - **Description**
   * - **User**
     - User who initiated the outbound calls.
   * - **Total calls**
     - Total number of outbound calls initiated by the user.
   * - **Answered calls**
     - Number of the user's outbound calls that were answered.
   * - **Average wait time**
     - Average time callers waited before the call reached its final outcome.
   * - **Average call duration**
     - Average call duration per answered call.
   * - **Answer rate**
     - Percentage of outbound calls that were answered successfully.

.. figure:: https://doc.didww.com/_images/user-statistics-outbound.png
   :alt: Outbound Calls table with call counts, wait times, call durations, and answer rates by user
   :figclass: align-center

   **Fig. 2.** Outbound Calls statistics


.. _ps3_contacts:

========
Contacts
========

The **Contacts** section is your central address book within the phone.systems™ platform. It is designed to help you efficiently store, organize, and manage all the contact information essential for your organization's communications.

Use the following guides to manage your contacts effectively:

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`list-unordered` **User Interface Elements**
      :link: ps3_viewing_contacts
      :link-type: ref
      :text-align: left

      Navigate the contact list and use filters.

   .. grid-item-card:: :octicon:`person-add` **Creating Contacts**
      :link: ps3_creating_contacts
      :link-type: ref
      :text-align: left

      Add new contacts to your address book manually.

   .. grid-item-card:: :octicon:`upload` **Importing Contacts**
      :link: ps3_importing_contacts
      :link-type: ref
      :text-align: left

      Bulk-upload contacts using a CSV file.

   .. grid-item-card:: :octicon:`book` **Phonebooks**
      :link: ps3_phonebook
      :link-type: ref
      :text-align: left

      Learn how to assign contacts to the Phonebook.

   .. grid-item-card:: :octicon:`pencil` **Editing and Deleting Contacts**
      :link: ps3_editing_deleting_contacts
      :link-type: ref
      :text-align: left

      Modify or remove existing contact information.

.. raw:: html

    <br>

----

.. _ps3_viewing_contacts:

User Interface Elements
-----------------------

The main **Contacts** screen provides an overview of all your stored contacts, along with powerful tools for searching and making quick edits.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: The Contacts menu.

  **Fig. 1.** The Contacts menu.

Using the Filter Bar
^^^^^^^^^^^^^^^^^^^^

Use the filter bar to search for contacts by:

    - Full name
    - Company name
    - Job title
    - Phone numbers
    - Emails
    - Source
    - Type
    - Phonebook

Click **Filter** to apply.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Using the filter bar to search for contacts.

  **Fig. 2.** Using the filter bar to search for contacts.

The Contact List
^^^^^^^^^^^^^^^^

The table displays your contacts with the following columns:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Field
     - Description
   * - First Name
     - The contact's first name.
   * - Last Name
     - The contact's last name.
   * - Company Name
     - Associated organization.
   * - Job Title
     - Contact's role or title.
   * - Phone Numbers
     - Primary contact number(s).
   * - Emails
     - Primary email address(es).
   * - Source
     - Origin of the contact (e.g., manual, import).
   * - Type
     - Contact category (e.g., Lead, Customer).
   * - Phonebook
     - Visibility assignment (Company or User).

.. note::
   You can perform inline edits for some of the columns directly in the table. Simply double-click a cell or click the pencil icon that appears on hover to modify the information in that field.

.. figure:: https://doc.didww.com/_images/fig4.1.png
  :figclass: align-center
  :alt: Contact List.

  **Fig. 3.** Contact List.

.. raw:: html

    <br>

----

.. _ps3_creating_contacts:

Creating Contacts Manually
--------------------------

To create a new contact:

    1.  Click the **Add New Contact** button (|+-symbol|) in the bottom right corner of the screen.

    .. figure:: https://doc.didww.com/_images/fig11.png
      :figclass: align-center
      :alt: The Add New Contact Button.

      **Fig. 4.** The Add New Contact Button.

    .. raw:: html

        <br>

    2.  A form will appear. Fill in the **Contact details**:

    .. list-table::
       :header-rows: 1
       :widths: 20 80

       * - **Field**
         - **Description**
       * - **First Name**
         - The first name of the contact (required).
       * - **Last Name**
         - The last name of the contact (required).
       * - **Company Name**
         - The organization or company the contact is associated with.
       * - **Job Title**
         - The contact's job position or title.
       * - **Phonebook**
         - Assigns the contact's visibility. Select **Company Phonebook** to make it visible to all users, or select a specific user's name to make it private to them.

    3.  In the **Numbers** section, click **Add a phone number** to enter one or more phone numbers for the contact.
    4.  In the **Emails** section, click **Add an email** to enter one or more email addresses for the contact.
    5.  Click the **Save** button to create the new contact.

    .. figure:: https://doc.didww.com/_images/fig6.png
      :figclass: align-center
      :alt: The Create Contact form.
      :width: 35%

      **Fig. 5.** The Create Contact form.

.. raw:: html

    <br>

----

.. _ps3_importing_contacts:

Importing Contacts from a CSV File
----------------------------------

To import multiple contacts at once, you can upload a CSV file:

    1.  Click the **Add New Contact** button (|+-symbol|) and select **Import CSV**.

    .. figure:: https://doc.didww.com/_images/fig11.png
      :figclass: align-center
      :alt: The Add New Contact Button.

      **Fig. 6.** The Add New Contact Button.

    2.  In the **Import Users** screen, either click to select a CSV file from your computer or drag and drop the file onto the screen.

    .. figure:: https://doc.didww.com/_images/fig8.png
      :figclass: align-center
      :alt: The CSV file import screen.
      :width: 35%

      **Fig. 7.** The CSV file import screen.

    3.  A pop-up window will appear. You must agree that you have a prior relationship with the contacts in the list. Check the box and click **Submit** to proceed.

        .. admonition:: Your CSV must:
           :class: warning

           - Use commas as separators.
           - Include headers.
           - Be under 20MB in size.
           - Include only contacts who have opted in or are known.

    .. figure:: https://doc.didww.com/_images/fig10.png
      :figclass: align-center
      :alt: The import confirmation pop-up.
      :width: 35%

      **Fig. 8.** The import confirmation pop-up.

    4.  Choose whether to **Merge Duplicates** to prevent creating contacts that already exist.
    5.  On the **Match contact properties**, match the columns from your CSV file to the corresponding properties in phone.systems™.
    6.  Click **Next** to complete the import.

    .. figure:: https://doc.didww.com/_images/fig12.png
      :figclass: align-center
      :width: 35%
      :alt: Import Contacts Window.

      **Fig. 9.** Import Contacts Window.

    .. list-table:: **CSV File Format Example**
       :header-rows: 1
       :widths: auto

       * - First Name
         - Last Name
         - Email
         - Phone Number
         - Job Title
       * - Mike
         - Brown
         - ``Mike.Brown@businessdev.com``
         - +1-555-1234567
         - Business Development Manager
       * - Pete
         - Smith
         - ``Pete.Smith@ithelpdesk.com``
         - +1-555-9876543
         - IT Support Engineer
       * - Jane
         - Smith
         - ``Jane.Smith@finance.com``
         - +1-555-5551111
         - Financial Analyst
       * - Sarah
         - Johnson
         - ``Sarah.Johnson@marketing.com``
         - +1-555-2223333
         - Digital Marketing Strategist
       * - John
         - Doe
         - ``John.Doe@engineering.com``
         - +1-555-4447777
         - Software Development Lead

:download:`Download the example CSV file here. <csv_file_format_example.csv>`

.. raw:: html

    <br>

----

.. _ps3_phonebook:

Phonebooks
----------

The **Phonebook** feature controls contact visibility in the :ref:`phone.systems™ App Contacts <ps3_application_contacts>`. Contacts can be public to your organization or private to a specific user.

When creating a contact, specify the phonebook to which the contact will be assigned to.

    - **Company Phonebook:** Contacts assigned here are visible to all users in your organization.

     .. note:: By default, all new contacts are assigned to the Company Phonebook unless changed manually.

    - **User Phonebook:** Contacts assigned to a specific user are only visible to that user in their private phonebook. You can manage the list of available :ref:`Users <ps3_users>` in the Users section, and see how these contacts appear in the :ref:`phone.systems™ App Contacts <ps3_application_contacts>` guide.

    .. figure:: https://doc.didww.com/_images/phonebook.png
      :figclass: align-center
      :width: 35%
      :alt: Assigning a contact to a phonebook during contact creation.

      **Fig. 10.** Assigning a contact to a phonebook during contact creation.

.. raw:: html

    <br>

----

.. _ps3_editing_deleting_contacts:

Editing and Deleting Contacts
-----------------------------

You can modify or remove contacts at any time using the **Actions** menu available next to each entry in the contact list.

.. _ps3_editing_contacts:

Editing a Contact
^^^^^^^^^^^^^^^^^

1. Click the **Actions** menu next to the contact.
2. Select **Edit**.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: The Actions menu for a contact.

   **Fig. 11.** The Actions menu for a contact.

3. Modify any contact details, including the Phonebook assignment.
4. Click **Save** to apply changes.

.. figure:: https://doc.didww.com/_images/fig7.png
   :figclass: align-center
   :alt: Editing an existing contact's details.
   :width: 35%

   **Fig. 12.** Editing an existing contact's details.

.. _ps3_deleting_contacts:

Deleting a Contact
^^^^^^^^^^^^^^^^^^

1. Click the **Actions** menu next to the contact.
2. Select **Delete**.

.. warning::
   Deleting a contact is permanent. The entry will be immediately removed and cannot be restored.

.. figure:: https://doc.didww.com/_images/fig5.png
   :figclass: align-center
   :alt: The Actions menu for a contact.

   **Fig. 13.** The Actions menu for a contact.

.. |+-symbol| image:: ../assets/img/guide-v2/inline-img/+-symbol.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_settings:

========
Settings
========

The **Settings** section provides an overview of the essential configurations that shape the functionality and behavior of your PBX system. Here, you can customize various parameters, manage feature codes, and access detailed technical information to optimize your phone.systems™ according to your specific requirements.

Each subsection is dedicated to a particular aspect of system settings, ensuring that you have full control over your PBX environment.

----

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`gear` **General Settings**
      :link: general-settings
      :link-type: doc
      :text-align: left

      Configure core PBX preferences, system options, and default behaviors.

   .. grid-item-card:: :octicon:`globe` **Domains**
      :link: domain
      :link-type: doc
      :text-align: left

      Manage SIP domains used for registrations and call routing.

   .. grid-item-card:: :octicon:`code` **Feature Codes**
      :link: feature-codes
      :link-type: doc
      :text-align: left

      Access and customize feature codes for quick actions and call control.

   .. grid-item-card:: :octicon:`briefcase` **CRM Integrations**
      :link: crm-integrations
      :link-type: doc
      :text-align: left

      Connect and sync your PBX with CRM platforms for enhanced workflows.

   .. grid-item-card:: :octicon:`cloud` **Cloud Storage Integrations**
      :link: cloud-storage-integrations
      :link-type: doc
      :text-align: left

      Integrate cloud storage providers for file sharing and backups.

   .. grid-item-card:: :octicon:`cpu` **AI Settings**
      :link: ai-settings
      :link-type: doc
      :text-align: left

      Configure AI features for intelligent call handling and automation.

   .. grid-item-card:: :octicon:`tag` **Call Tags**
      :link: call-tags
      :link-type: doc
      :text-align: left

      Create and manage tags used to classify calls in Call History.

   .. grid-item-card:: :octicon:`device-mobile` **App Activation Settings**
      :link: app-activation-settings
      :link-type: doc
      :text-align: left

      Control app activation limits and manage connected user devices.

   .. grid-item-card:: :octicon:`info` **Technical Information**
      :link: technical-information
      :link-type: doc
      :text-align: left

      Access technical details and system specifications for advanced configuration.

.. toctree::
  :maxdepth: 1
  :hidden:

  General Settings <general-settings.rst>
  Domains <domain.rst>
  Feature Codes <feature-codes.rst>
  CRM Integrations <crm-integrations.rst>
  Cloud Storage Integrations <cloud-storage-integrations.rst>
  AI Settings <ai-settings.rst>
  Call Tags <call-tags.rst>
  App Activation Settings <app-activation-settings.rst>
  Technical Information <technical-information.rst>


.. _ps3_general_settings:

================
General Settings
================

Configure the general settings for the **phone.systems™** interface.

----

Language
^^^^^^^^

Select a language for the **phone.systems™** user interface. The available options are:

    - **English**
    - **Lithuanian**
    - **Latvian**

----

System Time Zone
^^^^^^^^^^^^^^^^

Set the system time zone to be used for routing calls when the **System Time Zone** option is selected in the :ref:`Time Router <ps3_object_time_router>` object.

The system time zone is also the default option for :ref:`Time Schedules <ps3_time_schedules>`.

----

System emails
^^^^^^^^^^^^^

Set the email address that will be used to send notifications about specific events occurring in the **phone.systems™** account.

.. note::

   This is a **mandatory field**. A valid email address **must** be provided to save the general settings.

   Follow the guide in the :ref:`Emails section <ps3_creating_emails>` to set up an email contact method.

System notifications are sent when:

1. **A delivery method’s access is revoked**
        - If a cloud storage delivery method (**Google Drive, Dropbox, or OneDrive**) gets the :ref:`Access Revoked <ps3_re_authorizing>` status, the system sends an email notification.

2. **A delivery fails**
        - If the system detects a failed delivery to a configured delivery method, it sends an email notification.
        - If failures continue, follow-up emails are sent every 24 hours.

----

Insufficient channel decline code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Select the decline code that will be sent to the caller if a call fails due to insufficient channel capacity.

By default, the system uses **480 - Temporarily Unavailable**, but you can choose from the following decline codes:

    .. list-table::
       :header-rows: 1
       :widths: 20 80

       * - **Code**
         - **Description**
       * - **403**
         - Forbidden
       * - **480**
         - Temporarily Unavailable (default)
       * - **486**
         - Busy Here
       * - **600**
         - Busy Everywhere
       * - **603**
         - Decline


.. _ps3_ai_settings:

AI Settings
===========

AI settings allow you to configure the delivery and analysis of call recordings, providing insights into inbound, outbound, and internal calls. By analyzing call details, these insights help you better understand conversations and optimize your communication strategies.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :width: 100%

  **Fig. 1.** AI Settings

.. _ps3_ai_settings_enable:

Enable AI Call Insights
++++++++++++++++++++++++++

To enable AI Call Insights for your Phone.systems™ account, navigate to the `Cloud Phone System <https://my.didww.com/#/phone_systems>`_ section and select the checkbox labeled **AI Call Insights** to activate the feature.

.. figure:: https://doc.didww.com/_images/fig8.png
   :figclass: align-center
   :width: 100%

   **Fig. 1.** Cloud Phone System

A pop-up window will provide important information about call recording and pricing. To continue, click **Enable AI Call Insights**.

.. figure:: https://doc.didww.com/_images/fig9.png
   :figclass: align-center
   :width: 100%

   **Fig. 2.** Enabling AI Call Insights

Key Features
++++++++++++

- **Call Summary**: Provides a quick way to understand the overall content of the conversation.
- **Sentiment Analysis**: Analyzes and identifies the emotional tone of both calling parties.
- **Key Topics**: Automatically extracts key discussion points from recorded calls.
- **Full Call Transcript**: Generates a complete written record of the conversation.
- **Talk-to-Listen Ratio**: Measures and compares the time each participant spends talking versus listening.
- **Multilingual Support**: Access AI features in multiple languages.

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center
  :width: 100%

  **Fig. 1.** AI Features

Language Support
++++++++++++++++

Phone.systems™ AI supports the following languages for its AI-powered features:

- Global English
- Australian English
- British English
- US English
- Spanish
- French
- German
- Italian
- Portuguese
- Dutch
- Hindi
- Japanese
- Chinese
- Finnish
- Korean
- Polish
- Russian
- Turkish
- Ukrainian
- Vietnamese

.. note::
   AI Processing Conditions:

   - AI generation and charging begin once the call has been connected for at least **15 seconds**. Calls shorter than **15 seconds** are not processed.
   - AI processing will also be skipped if the **audio file size** exceeds **25 MB**.

Call Summary
++++++++++++

Call Summaries are written overviews that capture the key details from a phone call. This feature allows you to quickly grasp the main points of the conversation without listening to the entire call.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :width: 45%

  **Fig. 1.** Call Summary

Key Topics
++++++++++

Key Topics is a feature that automatically recognizes, identifies, and extracts the main discussion points from recorded calls.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center
  :width: 45%

  **Fig. 1.** Key Topics

Talk-to-Listen Ratio
++++++++++++++++++++

The Talk-to-Listen Ratio measures the amount of time a person spends talking compared to listening during a conversation. This metric provides insights into the balance or imbalance of the interaction, which can be valuable for improving communication skills and ensuring effective conversations.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :width: 45%

  **Fig. 1.** Talk-to-Listen Ratio

Sentiment Analysis
++++++++++++++++++

Sentiment Analysis helps you understand the emotions expressed during a conversation. It analyzes the words used and classifies them into three categories: **positive**, **negative**, and **neutral**.

This analysis considers the feelings of both the caller and the agent. You can view these results in each **Call Detail Record (CDR)** to better understand their interactions.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center
  :width: 45%

  **Fig. 4.** Sentiment Analysis

Full Call Transcript
++++++++++++++++++++

Full Call Transcripts capture all spoken words during a conversation, providing a complete written record of the call from start to finish. This feature helps you analyze discussions, understand customer needs, and improve service quality.

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center
  :width: 45%

  **Fig. 1.** Full Call Transcript



.. _ps3_app_activation_settings:

=======================
App Activation Settings
=======================

The **App Activation Settings** page in phone.systems™ allows you to configure email invitation expiration and manage the maximum number of active applications per user. These settings help control user access and resource allocation.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center
  :alt: App Activation Settings
  :width: 100%

  **Fig. 1.** App Activation Settings

----

.. raw:: html

   <br>

Invitation expiration
---------------------

This setting defines how long an email invitation remains valid before it expires, measured **in days**. Users must activate their account before the invitation expires.

Choose an expiration period that balances security requirements with user onboarding convenience.

.. note:: The maximum invitation expiration period is 365 days.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :alt: Invitation Expiration App Settings
  :width: 100%

  **Fig. 2.** Invitation Expiration App Settings

----

.. raw:: html

   <br>

Active app limit
----------------

This setting controls how many applications a single user can have active at the same time.

- Limits the **maximum number of active applications per user**
- Helps prevent excessive or unintended resource usage
- Reduces the risk of a single user account being shared across multiple end-users

Adjust this value according to your organization’s security and usage policies.

.. note:: The maximum number of active applications allowed per user is 100.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center
  :alt: Active app limit App Settings
  :width: 100%

  **Fig. 3.** Active app limit App Settings

----

.. raw:: html

   <br>

Update App Activation Settings
------------------------------

To update your **App Activation Settings**, follow these steps:

1. Navigate to **Settings** in phone.systems™.
2. Open the **App Activation Settings** tab.
3. Modify the **Invitation expiration** and **Active app limit** values.
4. Click **Save** to apply the changes.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center
  :alt: Update App Activation Settings
  :width: 100%

  **Fig. 4.** Update App Activation Settings

.. _ps3_settings_call_tags:

=========
Call Tags
=========

The **Call tags** page lets you create and manage reusable tags for calls in your
phone.systems™ App. Tags help you organize calls by category, make them
easier to identify, and support call handling scenarios where labels are used
across the system.

Use call tags when you want to:

- Categorize calls by purpose, team, or workflow
- Apply consistent labels such as Support, Potential Leads, or Callback
- Make tagged calls easier to identify visually
- Maintain a reusable set of call labels in one place

----

.. _ps3_manage_call_tags:

Manage Call Tags
================

.. grid:: 1 1 2 4
   :gutter: 2
   :padding: 0
   :class-row: surface

   .. grid-item-card:: **Add a New Call Tag**
      :link: ps3_call_tags_add
      :link-type: ref
      :text-align: left

      Create a new call tag with a predefined or custom color.

   .. grid-item-card:: **Edit Call Tag**
      :link: ps3_call_tags_edit
      :link-type: ref
      :text-align: left

      Update an existing tag name or change its color.

   .. grid-item-card:: **Enable or Disable Call Tag**
      :link: ps3_call_tags_toggle
      :link-type: ref
      :text-align: left

      Control whether a tag is available for use without deleting it.

   .. grid-item-card:: **Delete Call Tag**
      :link: ps3_call_tags_delete
      :link-type: ref
      :text-align: left

      Remove a tag that is no longer needed.

----

.. _ps3_call_tags_add:

Add a New Call Tag
==================

Create a call tag to make it available for use in your phone.systems™
configuration.

Step 1: Open the Create Tag Window
----------------------------------

1. Go to **Settings -> Call tags**.
2. Click **Add a new tag**.

.. figure:: https://doc.didww.com/_images/call-tags-add-button.png
   :figclass: align-center
   :alt: Add a new tag button on the Call tags page
   :width: 100%

   **Fig. 1.** Open the Create Tag window.

Step 2: Configure and Save the Tag
----------------------------------

1. Select one of the **predefined** colors or select **Custom** to define your own color.
2. Enter the tag name in **Title**.
3. Click **Save**.

After the tag is created, it appears in the tag list with its color, name, and current status.

.. figure:: https://doc.didww.com/_images/call-tags-create-dialog.png
   :figclass: align-center
   :alt: Create Tag window with color and title fields
   :width: 100%

   **Fig. 2.** Configure and save the new tag.

----

.. _ps3_call_tags_edit:

Edit Call Tag
=============

Edit a call tag to update its name or color.

Step 1: Open the Edit Tag Window
--------------------------------

1. Go to **Settings -> Call tags**.
2. Locate the tag you want to edit.
3. Click **Actions -> Edit tag** to open the edit window.

.. figure:: https://doc.didww.com/_images/call-tags-actions-edit.png
   :figclass: align-center
   :alt: Tag actions menu in the Call tags list
   :width: 100%

   **Fig. 3.** Open the Edit Tag window.

Step 2: Update and Save the Tag
-------------------------------

1. Update the required fields such as **Color** or **Title**
2. Click **Save**.

After the tag is updated, the changes appear in the tag list and phone.systems™ App.

.. figure:: https://doc.didww.com/_images/call-tags-actions-edit-screen.png
   :figclass: align-center
   :alt: Edit Tag window
   :width: 100%

   **Fig. 4.** Update and save the tag.

----

.. _ps3_call_tags_toggle:

Enable or Disable Call Tag
==========================

Use this action to control whether a call tag is available for use without deleting it.

1. Go to **Settings -> Call tags**.
2. Locate the tag you want to enable or disable.
3. In the **Enabled** column, turn the toggle on or off.

.. figure:: https://doc.didww.com/_images/call-tags-enable-disable.png
   :figclass: align-center
   :alt: Call tags list with Enabled toggle switches
   :width: 100%

   **Fig. 5.** Enable or disable a call tag using the toggle.

----

.. _ps3_call_tags_delete:

Delete Call Tag
===============

Delete a call tag when it is no longer needed.

.. note::

   Deleting a tag permanently removes it from the **Call tags** list and from all related call logs.

1. Go to **Settings -> Call tags**.
2. Locate the tag you want to delete.
3. Click **Actions -> Delete tag**.
4. Confirm the deletion in the pop-up window

.. figure:: https://doc.didww.com/_images/call-tags-actions-delete-screen.png
   :figclass: align-center
   :alt: Tag actions menu in the Call tags list
   :width: 100%

   **Fig. 6.** Select Delete tag from the actions menu.


.. _ps3_cloud_storage_integrations:

##########################
Cloud Storage Integrations
##########################

The **Cloud Storage Integrations** feature in phone.systems™ allows users to manage where call recordings and voicemail data are stored by connecting to supported cloud storage solutions. Users can choose from the following options:

 1. **phone.systems™ cloud storage**:
     - A convenient built-in storage option that doesn’t require additional configuration.

 2. **Third-Party cloud storage providers**:
     - Amazon Web Services (AWS)
     - Microsoft Azure
     - S3

----

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`cloud` **phone.systems™ Cloud Storage**
      :link: cloud-storage-integrations/phone-systems
      :link-type: doc
      :text-align: left

      Use the built-in cloud storage option for hassle-free recording and voicemail management.

   .. grid-item-card:: :octicon:`server` **Amazon Web Services (AWS)**
      :link: cloud-storage-integrations/aws
      :link-type: doc
      :text-align: left

      Integrate AWS S3 for secure, scalable cloud storage of call recordings and voicemail.

   .. grid-item-card:: :octicon:`device-desktop` **Microsoft Azure**
      :link: cloud-storage-integrations/azure
      :link-type: doc
      :text-align: left

      Connect Microsoft Azure for enterprise-grade storage and centralized data management.

   .. grid-item-card:: :octicon:`database` **S3**
      :link: cloud-storage-integrations/minio
      :link-type: doc
      :text-align: left

      Configure S3-compatible storage solutions for flexible data hosting and retrieval.

.. toctree::
  :maxdepth: 1
  :hidden:

  phone.systems™ cloud storage <cloud-storage-integrations/phone-systems.rst>
  Amazon Web Services (AWS) <cloud-storage-integrations/aws.rst>
  Microsoft Azure <cloud-storage-integrations/azure.rst>
  S3 <cloud-storage-integrations/minio.rst>


.. _ps3_phonesystems_cloudstorage:

.. |br| raw:: html

    <br>

phone.systems™ Cloud Storage
############################

phone.systems™ Cloud Storage is a fully integrated solution that requires no external credentials or configurations, making it an ideal choice for users seeking simplicity.

.. note::
   Call recordings and voicemail data stored in the **phone.systems™ cloud storage** are retained for a maximum of **three months**.

----

Activating phone.systems™ Cloud Storage
---------------------------------------

To activate this option follow the step below:

 1. Go to **Settings > Cloud Storage Integrations**.
 2. Locate **phone.systems™ cloud storage** in the list of integrations.
 3. Click **Connect**.

.. figure:: https://doc.didww.com/_images/1_connect_phonesystems_cloudstorage.png
   :figclass: align-center
   :alt: Activating phone.systems™ Cloud Storage
   :width: 100%

   **Fig. 1.** Activating phone.systems™ Cloud Storage

Once connected, the status will change to **Connected**, and the storage is immediately ready for use.

.. figure:: https://doc.didww.com/_images/active_phonesystems_cloud_storage.png
   :figclass: align-center
   :alt: Active phone.systems™ Cloud Storage
   :width: 100%

   **Fig. 2.** Active phone.systems™ Cloud Storage


.. _ps3_aws_integration:

.. |br| raw:: html

    <br>

phone.systems™ with AWS Cloud Storage
#####################################

Connecting phone.systems™ with AWS Cloud Storage allows you to store call recordings and voicemail data securely in your AWS environment.

.. note::
   Ensure that you have the required AWS credentials and access to your S3 bucket before starting the integration.

----

.. raw:: html

   <br>

Step 1: Launch phone.systems™ and create AWS Cloud Storage connection
---------------------------------------------------------------------

Follow these steps to create the AWS Cloud Storage connection:

 1. Log in to your DIDWW account, and launch phone.systems™.
 2. In phone.systems™, go to **Settings > Cloud Storage Integrations**.
 3. Under AWS Cloud Storage, click **Connect**.

.. figure:: https://doc.didww.com/_images/1_create_aws_connection_in_phonesystems.png
  :figclass: align-center
  :alt: Create AWS Cloud Storage Connection
  :width: 100%

  **Fig. 1.** Create AWS Cloud Storage Connection

A new page will open, where it is required to enter the following details:

 1.	**Bucket Region**: The AWS region where your S3 bucket is hosted (e.g., us-east-1, eu-west-1).
 2.	**Bucket Name**: The name of your S3 bucket.
 3.	**Access Key ID**: The unique identifier for your IAM user’s access key.
 4.	**Secret Access Key**: The secret component of your IAM user’s access key pair.

.. figure:: https://doc.didww.com/_images/1_requirements_for_aws_connection.png
  :figclass: align-center
  :alt: Requirements to Activate AWS Cloud Storage
  :width: 100%

  **Fig. 2.** Requirements to Activate AWS Cloud Storage

Step 2: Retrieve Bucket Region and Bucket Name
-----------------------------------------------

1. Sign in to the `AWS Management Console <https://aws.amazon.com/console/>`_.

2. Open the S3 service by typing ``S3`` in the search bar at the top of the AWS Management Console and selecting the **S3** service.

3. Locate your bucket.

   - Find your bucket in the list of S3 buckets.
   - The **Bucket Name** is displayed in the "Name" column.
   - The **Bucket Region** is displayed in the "Region" column.

Step 3: Retrieve the Access Key ID and Secret Access Key
--------------------------------------------------------

1. Open the IAM service by typing ``IAM`` in the search bar of the AWS Management Console and selecting the **IAM** service.

2. Locate your IAM user.

   - In the IAM Console, select **Users** in the navigation pane.
   - If you already have an IAM user with S3 permissions, click the user’s name.
   - If you need to create a new IAM user, follow the steps in the `AWS documentation <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html>`_.

3. Generate or retrieve access keys.

   - Select the **Security credentials** tab for the IAM user.
   - Under **Access keys**, click **Create access key** to generate a new access key.
   - Copy the **Access Key ID** and **Secret Access Key**.

.. warning::
 The Secret Access Key is displayed only once. Save it securely before leaving the page.

Step 4: Connect the phone.systems™ AWS Cloud Storage
--------------------------------------------------------

To establish the connection to AWS Cloud Storage, click **Connect** on the phone.systems™ page.
After the connection is complete, AWS Cloud Storage will appear under **Active Integrations** with the status **Connected**.

.. figure:: https://doc.didww.com/_images/active_aws_cloud_storage.png
  :figclass: align-center
  :alt: Activate AWS Cloud Storage
  :width: 100%

  **Fig. 3.** Activate AWS Cloud Storage

Additional Resources
--------------------

.. card:: Setting Up Amazon S3
    :link: https://docs.aws.amazon.com/AmazonS3/latest/userguide/setting-up-s3.html
    :link-type: url

    Learn how to configure and manage Amazon S3, including bucket creation and permissions.

.. card:: Managing Access Keys for IAM Users
    :link: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html
    :link-type: url

    Understand how to create, manage, and secure AWS IAM access keys for users.


.. _ps3_azure_integration:

.. |br| raw:: html

    <br>

phone.systems™ with Azure Cloud Storage
#######################################

Connecting phone.systems™ with Azure Cloud Storage allows you to store call recordings and voicemail data securely in your Azure environment.

.. note::
   Ensure that you have the required Azure credentials and access to your Azure Storage account before starting the integration.

----

.. raw:: html

   <br>

Step 1: Launch phone.systems™ and create Azure Cloud Storage connection
-----------------------------------------------------------------------

Follow these steps to create the Azure Cloud Storage connection:

 1. Log in to your DIDWW account, and launch phone.systems™.
 2. In phone.systems™, go to **Settings > Cloud Storage Integrations**.
 3. Under Azure Cloud Storage, click **Connect**.

.. figure:: https://doc.didww.com/_images/1_create_azure_connection_in_phonesystems.png
  :figclass: align-center
  :alt: Create Azure Cloud Storage Connection
  :width: 100%

  **Fig. 1.** Create Azure Cloud Storage Connection

A new page will open, where it is required to fill in the details from your Azure Blob Storage credentials:

 1. **Storage Account Name**: Enter the name of your Azure Storage account.
 2. **Storage Access Key**: Enter the key used to access your Azure Storage account.
 3. **Container Name**: Enter the name of the container within your Azure Storage account where the data will be stored.

.. figure:: https://doc.didww.com/_images/1_requirements_for_azure_connection.png
  :figclass: align-center
  :alt: Requirements to Activate Azure Cloud Storage
  :width: 100%

  **Fig. 2.** Requirements to Activate Azure Cloud Storage

Step 2: Retrieve Storage Account Name and Container Name
--------------------------------------------------------

1. Sign in to the `Azure Portal <https://portal.azure.com/>`_.

2. Open the **Storage accounts** service by typing ``Storage accounts`` in the search bar at the top of the Azure Portal and selecting the service.

3. Locate your storage account.

   - Find your storage account in the list of accounts.
   - The **Storage Account Name** is displayed in the "Name" column.

4. Retrieve the container name.

   - Open your storage account and navigate to **Containers** under the **Data storage** section.
   - Locate the container name or create a new container if needed.

Step 3: Retrieve the Account Key
--------------------------------

1. Open your storage account in the Azure Portal.

2. Navigate to **Access keys** under the **Security + networking** section.

3. Copy the **Key1** or **Key2** under **Key**.

.. warning::
 The account key provides full access to your storage account. Save it securely and do not share it with unauthorized users.

Step 4: Connect the phone.systems™ Azure Cloud Storage
------------------------------------------------------

To establish the connection to Azure Cloud Storage, click **Connect** on the phone.systems™ page.
After the connection is complete, Azure Cloud Storage will appear under **Active Integrations** with the status **Connected**.

.. figure:: https://doc.didww.com/_images/active_azure_cloud_storage.png
  :figclass: align-center
  :alt: Activate Azure Cloud Storage
  :width: 100%

  **Fig. 3.** Activate Azure Cloud Storage

Additional Resources
--------------------

.. card:: Azure Storage Documentation
    :link: https://learn.microsoft.com/en-us/azure/storage/common/storage-introduction
    :link-type: url

    Learn about Azure Storage services, including Blob, Queue, Table, and File storage.

.. card:: Manage Storage Account Keys
    :link: https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage
    :link-type: url

    Understand how to securely manage and rotate Azure Storage account access keys.


.. _ps3_minio_integration:

.. |br| raw:: html

    <br>

phone.systems™ with S3 Cloud Storage
####################################

Connecting phone.systems™ with S3 Cloud Storage allows you to store call recordings and voicemail data securely in your S3 environment.

.. note::
   Ensure that you have the required S3 credentials and access to your bucket before starting the integration.

----

.. raw:: html

   <br>

S3 Compatibility
----------------

Amazon Simple Storage Service (S3) is a widely used object storage protocol that allows seamless data storage and retrieval. Various cloud storage solutions implement the S3 API to enable interoperability across different platforms.

For this documentation, we will demonstrate the integration of **phone.systems™** with **MinIO**, an S3-compatible object storage solution.

.. important:: The same principles can generally be applied to other S3-compatible storage providers with minor modifications.

----

.. raw:: html

   <br>

Step 1: Launch phone.systems™ and create S3 Cloud Storage connection
--------------------------------------------------------------------

Follow these steps to create the MinIO Cloud Storage connection:

 1. Log in to your DIDWW account, and launch phone.systems™.
 2. In phone.systems™, go to **Settings > Cloud Storage Integrations**.
 3. Under S3 Cloud Storage, click **Connect**.

.. figure:: https://doc.didww.com/_images/1_create_minio_connection_in_phonesystems.png
  :figclass: align-center
  :alt: Create MinIO Cloud Storage Connection
  :width: 100%

  **Fig. 1.** Create S3 Cloud Storage Connection

A new page will open, where it is required to fill in the details from your S3 IAM credentials:

 1. **Endpoint**: Enter the S3 server endpoint (e.g., ``https://play.min.io``).
 2. **Bucket Region**: Enter the region configured for your S3 bucket (e.g., ``eu-west-1``).
 3. **Bucket Name**: Enter the name of your bucket.
 4. **Access Key ID**: Enter your IAM user’s access key ID.
 5. **Secret Access Key**: Enter your IAM user’s secret access key.

.. figure:: https://doc.didww.com/_images/1_requirements_for_minio_connection.png
  :figclass: align-center
  :alt: Requirements to Activate MinIO Cloud Storage
  :width: 100%

  **Fig. 2.** Requirements to Activate MinIO Cloud Storage

Step 2: Retrieve Endpoint, Bucket Region, and Bucket Name
---------------------------------------------------------

1. Open your MinIO server or the `MinIO Console <https://min.io/>`_.

2. Locate the endpoint.

   - The **Endpoint** is the URL where your MinIO server is hosted (e.g., ``https://play.min.io``).

3. Retrieve the bucket region.

   - The **Bucket Region** is the region configured for your S3 bucket (e.g., ``eu-west-1``).

   .. note:: In MinIO or another S3-compatible storage provider, this value depends on your bucket or server configuration. If you are unsure which region to use, check your storage settings or contact your storage administrator.

4. Retrieve the bucket name.

   - In the MinIO Console, navigate to **Buckets**.
   - Find the bucket name in the list or create a new bucket if needed.

Step 3: Retrieve Access Key ID and Secret Access Key
-----------------------------------------------------

1. Open the MinIO Console and sign in with your credentials.

2. Navigate to **Identity > Users** in the MinIO Console.

   - Locate the IAM user associated with your application.
   - If you need to create a new IAM user, follow the steps in the `MinIO IAM User Guide <https://min.io/docs/minio/linux/administration/identity-access-management/minio-user-management.html>`_.

3. Generate or retrieve access keys.

   - Copy the **Access Key ID** and **Secret Access Key** associated with the IAM user.

.. warning::
 The Secret Access Key is displayed only once when generated. Save it securely before leaving the page.

Step 4: Connect the phone.systems™ S3 Cloud Storage
---------------------------------------------------

To establish the connection to S3 Cloud Storage, click **Connect** on the phone.systems™ page.
After the connection is complete, S3 Cloud Storage will appear under **Active Integrations** with the status **Connected**.

.. figure:: https://doc.didww.com/_images/active_minio_cloud_storage.png
  :figclass: align-center
  :alt: Activate MinIO Cloud Storage
  :width: 100%

  **Fig. 3.** Activate MinIO Cloud Storage

Additional Resources
--------------------

.. card:: MinIO Documentation
    :link: https://min.io/docs/minio/linux/administration/minio-console.html
    :link-type: url

    Learn how to manage MinIO using the MinIO Console, including configuration, monitoring, and administration.

.. card:: MinIO IAM User Guide
    :link: https://min.io/docs/minio/linux/administration/identity-access-management/minio-user-management.html
    :link-type: url

    Understand MinIO Identity and Access Management (IAM), including user roles, permissions, and authentication.


.. _ps3_crm_integrations:

################
CRM Integrations
################

Phone.systems™ CRM integrations automate customer communication by synchronizing contact details, logging calls, and storing call data within platforms such as **HubSpot**, **Zendesk**, **Pipedrive**, **Salesforce**, and **Zoho**. This ensures all interactions are tracked across these systems for improved efficiency.

.. note::
   Only one integration can be active at a time.

----

.. grid:: 1 1 1 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: |hubspot| **HubSpot**
      :link: crm_integrations/hubspot
      :link-type: doc
      :text-align: left

      Integrate HubSpot CRM to sync contacts, track calls, and streamline customer engagement.

   .. grid-item-card:: |zendesk| **Zendesk**
      :link: crm_integrations/zendesk
      :link-type: doc
      :text-align: left

      Connect Zendesk for call logging, ticketing, and improved customer support workflows.

   .. grid-item-card:: |pipedrive| **Pipedrive**
      :link: crm_integrations/pipedrive
      :link-type: doc
      :text-align: left

      Link Pipedrive CRM to log calls, track deals, and manage communication efficiently.

   .. grid-item-card:: |salesforce| **Salesforce**
      :link: crm_integrations/salesforce
      :link-type: doc
      :text-align: left

      Integrate Salesforce CRM to automate call tracking and boost sales productivity.

   .. grid-item-card:: |zoho| **Zoho**
      :link: crm_integrations/zoho
      :link-type: doc
      :text-align: left

      Connect Zoho CRM for synchronized contact management and call activity insights.

   .. grid-item-card:: |monday| **Monday**
      :link: crm_integrations/monday
      :link-type: doc
      :text-align: left

      Connect monday CRM to sync contacts, log calls, and manage recordings seamlessly.

   .. grid-item-card:: |activecampaign| **ActiveCampaign**
      :link: crm_integrations/activecampaign
      :link-type: doc
      :text-align: left

      Connect ActiveCampaign to sync contacts, log calls, and automatically create contacts from calls.

.. toctree::
  :maxdepth: 1
  :hidden:

  HubSpot <crm_integrations/hubspot.rst>
  Zendesk <crm_integrations/zendesk.rst>
  Pipedrive <crm_integrations/pipedrive.rst>
  Salesforce <crm_integrations/salesforce.rst>
  Zoho <crm_integrations/zoho.rst>
  monday <crm_integrations/monday.rst>
  ActiveCampaign <crm_integrations/activecampaign.rst>

.. |hubspot| image:: /img/phone_systems/crm-icons/hubspot.svg
   :class: inline-img no-shadow no-border
   :width: 24px
   :height: 24px

.. |zendesk| image:: /img/phone_systems/crm-icons/zendesk.svg
   :class: inline-img no-shadow no-border
   :width: 24px
   :height: 24px

.. |pipedrive| image:: /img/phone_systems/crm-icons/pipedrive.svg
   :class: inline-img no-shadow no-border
   :width: 24px
   :height: 24px

.. |salesforce| image:: /img/phone_systems/crm-icons/salesforce.svg
   :class: inline-img no-shadow no-border
   :width: 24px
   :height: 24px

.. |zoho| image:: /img/phone_systems/crm-icons/zoho-logo-white.svg
   :class: inline-img no-shadow no-border no-top-margin black-end-white-zoho

.. |monday| image:: /img/phone_systems/crm-icons/monday.svg
   :class: inline-img no-shadow no-border
   :width: 24px
   :height: 24px

.. |activecampaign| image:: /img/phone_systems/crm-icons/activecampaign.svg
   :class: inline-img no-shadow no-border
   :width: 18px
   :height: 40px

.. raw:: html

    <style>

    img.inline-img.no-shadow.black-end-white-zoho {
        filter: invert(1);
        height: 37px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.no-border {
        border-radius: 0px !important;
    }

    img.inline-img.no-shadow.no-top-margin.wide-img {
        height: 74px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
        max-height: 74px;                 /* Prevent vertical expansion */
        margin-top: 0 !important;         /* Remove top margin */
        padding-top: 0 !important;        /* Remove top padding */
        line-height: 0;                   /* Prevents line-height gaps */
        vertical-align: middle;           /* Align inline properly */
        object-fit: contain;              /* Ensures no distortion */
    }

    </style>


.. _ps3_hubspot_integration_index:

======================================
HubSpot and phone.systems™ Integration
======================================

Connecting **phone.systems™** with **HubSpot CRM** allows you to manage customer
calls and synchronize CRM data. The integration includes the following
features:

- **Contact and company synchronization**: Import HubSpot contacts and
  companies into the phone.systems™ address book.
- **Call journaling**: Log inbound and outbound calls for associated users in
  HubSpot.
- **Automatic contact creation**: Create HubSpot contacts for calls involving
  unknown numbers.
- **Call recordings**: Add links to available call recordings to HubSpot call
  logs.
- **AI call insights**: Add available call summaries, topics, sentiment,
  transcription, and other AI insights to HubSpot call logs.
- **User association**: Match HubSpot users with phone.systems™ users so calls
  are logged for the correct users.

.. grid:: 1 1 2 2
   :gutter: 3
   :padding: 0

   .. grid-item-card:: Current HubSpot integration
      :link: hubspot/current-integration
      :link-type: doc

      Create and connect a HubSpot developer platform app. Use this setup for
      new phone.systems™ integrations.

   .. grid-item-card:: Legacy HubSpot integration
      :link: hubspot/legacy-integration
      :link-type: doc

      Maintain or reconnect an existing HubSpot Legacy Public App integration
      with phone.systems™.

.. toctree::
   :maxdepth: 1
   :hidden:

   Current integration <hubspot/current-integration.rst>
   Legacy integration <hubspot/legacy-integration.rst>


.. _ps3_hubspot_current_integration:

============================
Current HubSpot Integration
============================

Create and upload a HubSpot developer platform project, then use the generated
app credentials to connect HubSpot with phone.systems™.

.. note::

   This integration requires creating a HubSpot developer platform project and
   uploading it to HubSpot using the HubSpot CLI.

Before you begin
----------------

- A HubSpot account with **Super Admin** permissions is required.
- Access to **Settings > CRM Integrations** in phone.systems™ is required.

Step 1: Download the HubSpot app template
-----------------------------------------

Download the phone.systems HubSpot app template and extract the archive on the computer that you will use to upload the app to HubSpot:

.. button-link:: /_static/downloads/phone-systems-hubspot.zip
   :class: didww-download-button

   :octicon:`download` Download template

The extracted ``phone-systems-hubspot`` directory contains the complete HubSpot
project.

.. note::

   Do not remove or rename any files in the extracted project directory.

The required project structure:

.. code-block:: text

   phone-systems-hubspot/
   ├── hsproject.json
   ├── package.json
   └── src/app/
       ├── app-hsmeta.json
       └── webhooks/webhooks-hsmeta.json

Open the ``phone-systems-hubspot`` directory when running the commands in this
guide. Do not run them from the parent directory or from ``src``.

- ``hsproject.json`` identifies the directory as a HubSpot project.
- ``src/app/app-hsmeta.json`` defines the app, OAuth settings, and permissions.
- ``src/app/webhooks/webhooks-hsmeta.json`` defines the webhook subscriptions
  used to synchronize HubSpot records with phone.systems™.

Step 2: Install Node.js
-----------------------

The template uses the HubSpot CLI to validate and upload the app. The CLI
requires Node.js.

1. Open a terminal.
2. Check the installed Node.js version:

   .. code-block:: console

      node --version

3. If the command returns version ``v22`` or later, continue to the next step.
4. If Node.js is unavailable or an earlier version is installed, download and
   install `Node.js 22 or later <https://nodejs.org/en/download>`_.
5. Run ``node --version`` again to confirm the installation.

Step 3: Install the HubSpot CLI
-------------------------------

Open a terminal in the extracted ``phone-systems-hubspot`` directory. The
commands in this guide must be run from this directory, which contains
``hsproject.json``.

Install the HubSpot CLI dependency included in the template:

.. code-block:: console

   npm install
   npx hs --version

``npm install`` installs the HubSpot CLI locally for this project. The
``npx hs --version`` command confirms that the CLI is available. Continue only
after the command returns a version number.

For installation details, see the official `HubSpot CLI documentation
<https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli>`_.

Step 4: Authenticate the HubSpot CLI
------------------------------------

1. From the ``phone-systems-hubspot`` directory, run:

   .. code-block:: console

      npx hs account auth

2. In the browser window opened by the CLI, select the HubSpot account in which
   the project will be created and click **Continue with this account**.

.. figure:: https://doc.didww.com/_images/current-select-cli-account.webp
   :figclass: align-center
   :alt: HubSpot account selection opened by the HubSpot CLI authentication command

   **Fig. 1.** Select the HubSpot account for the CLI

3. Review the permissions requested for the personal access key. Keep the
   permissions selected by the CLI, including **Developer Projects**.
4. Click **Generate and send to CLI**. HubSpot generates the personal access
   key and sends it directly to the waiting CLI process.

.. figure:: https://doc.didww.com/_images/current-generate-cli-access-key.webp
   :figclass: align-center
   :alt: Generate and send to CLI button on the HubSpot Personal Access Key page

   **Fig. 2.** Generate the personal access key and send it to the CLI

5. Return to the terminal and enter a unique name for the HubSpot account when
   prompted. This name identifies the account in the CLI.
6. When prompted, enter ``Y`` to set it as the default account.

   .. code-block:: console

      Enter a unique name to reference this account in the CLI: my_phone_systems_integration
      Set my_phone_systems_integration as your default account? [--default] Yes

7. Confirm that the account is available to the CLI:

   .. code-block:: console

      npx hs account list

The personal access key authenticates local HubSpot CLI commands. It is stored
on the local computer and is not entered in phone.systems™. For details, see
`Authenticate the HubSpot CLI
<https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/personal-access-key>`_.

Step 5: Validate and upload the HubSpot project
------------------------------------------------

1. Return to the terminal in the ``phone-systems-hubspot`` directory.
2. Validate the project configuration:

   .. code-block:: console

      npx hs project validate

3. Correct any validation errors before continuing.
4. Upload the project:

   .. code-block:: console

      npx hs project upload

5. During the first upload, enter ``Y`` when prompted to create the
   ``phone-systems-hubspot`` project in the authenticated HubSpot account.

   The upload creates a project in the authenticated HubSpot account and starts
   a build. Wait until the CLI reports that the build and deployment have
   completed successfully. The deployed project contains the OAuth app and its
   webhook subscriptions.

6. Open the uploaded project in HubSpot:

   .. code-block:: console

      npx hs project open

7. Confirm that the latest build and deployment show **Succeeded**.

.. figure:: https://doc.didww.com/_images/current-project-deployed.webp
   :figclass: align-center
   :alt: Successfully deployed phone.systems HubSpot project and its project components

   **Fig. 3.** Confirm successful project deployment

   The HubSpot account used to upload the project is approved automatically for
   the app installation.

8. Under **Project Components**, click **phone.systems CRM**.

.. figure:: https://doc.didww.com/_images/current-open-app-component.webp
   :figclass: align-center
   :alt: phone.systems CRM app highlighted under HubSpot project components

   **Fig. 4.** Open the phone.systems CRM app

For details about validation, upload, build status, and other commands, see the
official `HubSpot project commands
<https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/project-commands>`_.

Step 6: Copy the app credentials
--------------------------------

1. Open the **Auth** tab.
2. Under **Client credentials**, copy the following values:

   - **Client ID**
   - **Client secret**

   .. figure:: https://doc.didww.com/_images/current-copy-app-credentials.webp
      :figclass: align-center
      :alt: Client ID and concealed client secret on the HubSpot app Auth tab

      **Fig. 5.** Copy the app credentials

Store the client secret securely. Do not expose it in screenshots, tickets, or
other shared material. For details about the app management page, see `Manage
apps in HubSpot
<https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#locate-your-app-s-client-credentials-and-redirect-urls>`_.

Step 7: Connect phone.systems™
------------------------------

1. In phone.systems™, go to **Settings > CRM Integrations**.
2. Click **Connect** for HubSpot.
3. Paste the OAuth **Client ID** and **Client secret** copied from HubSpot.
4. Enable **Synchronize from contacts**, **Synchronize from companies**, or
   both to import the selected existing records during connection.
5. Click **Connect**.

.. note::
   phone.systems™ manages OAuth token renewal automatically. The webhook
   subscriptions were created when the project was uploaded; no separate webhook
   configuration is required in HubSpot.

.. figure:: https://doc.didww.com/_images/current-connect-app.webp
   :figclass: align-center
   :alt: HubSpot connection form with app credentials and synchronization options in phone.systems

   **Fig. 6.** Enter the HubSpot app credentials and connect

6. In the HubSpot authorization window, select the account used to upload the
   project, then click **Choose Account**.

.. figure:: https://doc.didww.com/_images/current-choose-account.webp
   :figclass: align-center
   :alt: HubSpot account selection during phone.systems CRM authorization

   **Fig. 7.** Choose the HubSpot account

7. Review the requested permissions. Select the checkbox acknowledging that
   the app is unverified, then click **Connect app**.

.. figure:: https://doc.didww.com/_images/current-approve-app.webp
   :figclass: align-center
   :alt: HubSpot permission review and unverified app acknowledgement

   **Fig. 8.** Review the permissions and connect the app

.. important::

   A developer test account cannot be used for the phone.systems™ connection.

   HubSpot displays the unverified-app notice because this is a privately
   distributed app created in your account.

HubSpot returns the authorization response to the redirect URL. phone.systems™
then exchanges it for OAuth tokens and the integration status changes to
**Connected**.

.. figure:: https://doc.didww.com/_images/16_active_hubspot_connection.png
   :figclass: align-center
   :alt: Connected HubSpot integration in phone.systems

   **Fig. 9.** Connected HubSpot integration

.. _ps3_hubspot_associate_users:

Associate users for HubSpot
===========================

After the HubSpot integration is successfully connected, you can associate
HubSpot users with their corresponding **phone.systems™** users.

User association enables call journaling by ensuring that inbound and outbound
calls are logged for the correct users in HubSpot. Calls handled by users who
are not associated will not receive call details in HubSpot.

1. Go to phone.systems™ **Settings**, then open **CRM Integrations**.
2. Under **Active Integrations** at the top of the page, locate **HubSpot** marked as **Connected**.
3. Click **Associate users**.

.. figure:: https://doc.didww.com/_images/17_associate_users.png
   :figclass: align-center
   :alt: Associate HubSpot users button
   :width: 100%

   **Fig. 10.** Associate HubSpot users button

The **Associate HubSpot users** page opens, where you can link **HubSpot users**
with corresponding **phone.systems™ users**.

4. Match each HubSpot user with the appropriate phone.systems™ user.
5. Click **Save** to apply the changes.

.. figure:: https://doc.didww.com/_images/17_associate_hubspot_users.png
   :figclass: align-center
   :alt: Associate HubSpot users with phone.systems™ users
   :width: 100%

   **Fig. 11.** Associate HubSpot users with phone.systems™ users

.. _ps3_hubspot_sync:

Synchronizing Contacts and Companies
====================================

After connecting, you can perform a one-time synchronization to import your existing contacts and companies from HubSpot into your phone.systems™ address book.

1.  Navigate to **Settings > CRM Integrations**.
2.  Locate the active HubSpot integration and click the actions menu icon.
3.  Select **Change synchronization options** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/17_sync_options.png
   :figclass: align-center
   :alt: Synchronization options menu for the HubSpot integration
   :width: 100%

   **Fig. 12.** Synchronization options

4.  In the **Synchronize contacts from** window, use the toggles to select whether you want to import **Contacts**, **Companies**, or both.
5.  Click **Submit** to begin the synchronization.

.. note::
   This is a one-time import. For ongoing, automatic creation of new contacts from calls, see the **Auto Contact Creation** settings below.

.. figure:: https://doc.didww.com/_images/18_sync_modal.png
   :figclass: align-center
   :alt: Synchronization window for contacts and companies
   :width: 100%

   **Fig. 13.** Synchronization window

.. _ps3_hubspot_settings:

Configuring HubSpot Settings
============================

Once the integration is active, you can customize how data is synced between phone.systems™ and HubSpot. To access these options, navigate to **Settings > CRM Integrations** and click the settings icon next to your HubSpot connection.

.. figure:: https://doc.didww.com/_images/19.1_hubspot_settings_button.png
   :figclass: align-center
   :alt: HubSpot integration settings button
   :width: 100%

   **Fig. 14.** HubSpot integration settings button

.. important::
   The following settings apply **only** to numbers with **Call journaling** enabled. Call journaling must be configured separately for each number on the :ref:`Edit phone numbers page <ps3_edit_phone_numbers>`.

.. figure:: https://doc.didww.com/_images/19_hubspot_settings.png
   :figclass: align-center
   :alt: HubSpot integration settings in phone.systems™
   :width: 100%

   **Fig. 15.** HubSpot integration settings

Auto Contact Creation
---------------------

This feature automatically creates a new contact in HubSpot when a call is received from or made to a number that does not match an existing contact in your CRM.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - When enabled, a new contact will be created in HubSpot for all inbound calls from unknown numbers.
   * - **Outbound calls**
     - When enabled, a new contact will be created in HubSpot for all outbound calls to unknown numbers.
   * - **Contact type**
     - Select the default HubSpot contact type to be assigned when a new contact is created automatically.

Other Settings
--------------

Manage which call-related data is automatically uploaded to your HubSpot contacts’ activity timelines.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Upload call recordings to CRM**
     - When enabled, a link to the call recording will be automatically added to the call log in HubSpot.

       .. note:: To utilize this feature, call recording must be enabled for your :ref:`contact method <ps3_contact_methods>`.

   * - **Upload AI call insights results**
     - When enabled, detailed analytics from our AI engine will be added to the call log. This can include:

       - **Key topics:** A summary of the main topics discussed.
       - **Call summary:** A concise, AI-generated summary of the conversation.
       - **Talk to listen ratio:** A breakdown of how much each party spoke.
       - **Sentiment analysis:** An analysis of the emotional tone of the call.
       - **Transcription:** A full, written transcript of the call.

       .. note:: To utilize the AI features, :ref:`AI Call Insights <ps3_ai_settings_enable>` must be enabled.

After configuring these options, click **Save** to apply your changes.

Troubleshooting
===============

.. dropdown:: Redirect URL mismatch

   Confirm that ``redirectUrls`` in ``src/app/app-hsmeta.json`` exactly
   matches the **Redirect URL** shown in phone.systems™.

   Upload the project again after changing the file.

.. dropdown:: Project validation or upload fails

   Run ``npx hs project validate`` and ``npx hs doctor`` from the directory
   containing ``hsproject.json``.

   Correct the reported errors and upload the project again.

.. dropdown:: Connection stops working

   Confirm that the HubSpot app remains installed and that its access has not
   been revoked.

   Reauthorize the connection if required.

.. dropdown:: Permission error

   Restore any required scopes removed from ``app-hsmeta.json``.

   Upload the project again and reauthorize the connection.


.. _ps3_hubspot_integration:

=============================================
Legacy HubSpot Integration
=============================================

.. important::
   This guide documents the discontinued **HubSpot Legacy Public App** setup.
   HubSpot no longer permits the creation of Legacy Public Apps, so this
   procedure cannot be used to create a new integration.

   Use this guide only to review, maintain, or reconnect an existing
   phone.systems™ integration that was created with a Legacy Public App.
   Existing Legacy Public Apps continue to work and are not automatically
   migrated to the current HubSpot Projects framework.

   To create a new integration, follow the :doc:`current HubSpot integration
   guide <current-integration>`.

   For details about this change, see the official `HubSpot changelog
   <https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset>`_.

Connecting phone.systems™ with HubSpot
======================================

This guide provides detailed steps on integrating phone.systems™ with HubSpot using the **HubSpot developer account**. Follow the instructions below to complete the setup process.

.. note::
   To connect phone.systems™ with HubSpot, you will need the **Client ID**, **Client Secret**, and **Developer API Key**, which are obtained from a **legacy app** created in your **HubSpot developer account**.

Step 1: Sign in or sign up to a HubSpot developer account
---------------------------------------------------------

To get started, go to the `HubSpot Developer Account page <https://app.hubspot.com/signup-hubspot/developers?uuid=c57d8b68-6de0-4399-a539-04eb6ecc005f&step=landing_page>`_ and sign in to an existing developer account or create a new one.

Step 2: Open the Legacy Apps page in HubSpot
--------------------------------------------

After signing in to HubSpot in the first browser tab:

1. Open the **Development** section.
2. Open the **Legacy Apps** tab.
3. Click **Create legacy app**.

.. figure:: https://doc.didww.com/_images/2_open_legacy_apps.png
   :figclass: align-center
   :alt: Open Development, Legacy Apps, and Create legacy app in HubSpot
   :width: 100%

   **Fig. 1.** Open the Legacy Apps page in HubSpot

Step 3: Create a public legacy app
----------------------------------

In the **Create Legacy App** pop-up, click **Public**.

.. figure:: https://doc.didww.com/_images/3_create_public_legacy_app.png
   :figclass: align-center
   :alt: Create a public legacy app in HubSpot
   :width: 100%

   **Fig. 2.** Create a public legacy app

Step 4: Enter app information
-----------------------------

On the HubSpot app page:

1. Enter a name in the **Public app name** field.
2. Open the **Auth** tab.

.. figure:: https://doc.didww.com/_images/4_enter_app_info_and_open_auth.png
   :figclass: align-center
   :alt: Enter the public app name and open the Auth tab
   :width: 100%

   **Fig. 3.** Enter app information and open the Auth tab

Step 5: Launch phone.systems™ and create HubSpot connection
-----------------------------------------------------------

Open a second browser tab, then create the HubSpot connection form in phone.systems™:

1. Log in to your DIDWW account and launch `phone.systems™ <https://my.didww.com/#/phone_systems>`_.
2. Go to **Settings > CRM Integrations**.
3. Click **Connect** to link HubSpot with phone.systems™.

.. figure:: https://doc.didww.com/_images/4_create_hubspot_connection.png
   :figclass: align-center
   :alt: Create HubSpot connection in phone.systems™
   :width: 100%

   **Fig. 4.** Create HubSpot connection in phone.systems™

Step 6: Copy the Redirect URL from phone.systems™ and paste it into HubSpot
---------------------------------------------------------------------------

On the **Connect HubSpot** page in phone.systems™, copy the **Redirect URL** value.

.. figure:: https://doc.didww.com/_images/5_copy_redirect_url.webp
   :figclass: align-center
   :alt: Copy the redirect URL from the Connect HubSpot form in phone.systems™
   :width: 100%

   **Fig. 5.** Copy the redirect URL from phone.systems™

Return to the first browser tab in HubSpot and paste the copied value into the **Redirect URLs** field.

.. figure:: https://doc.didww.com/_images/6_add_redirect_url.png
   :figclass: align-center
   :alt: Paste the redirect URL into the HubSpot Auth settings
   :width: 100%

   **Fig. 6.** Paste the redirect URL into HubSpot

Step 7: Add the required scopes
-------------------------------

Continue in the HubSpot Auth tab to configure the scopes that determine the permissions your app has to access data or perform actions in HubSpot.

In the **Scopes** block, click **+ Add new scope** to define the **required** permissions for your app:

- ``oauth``
- ``tickets``
- ``timeline``
- ``files``
- ``crm.objects.owners.read``
- ``crm.objects.companies.read``
- ``crm.objects.companies.write``
- ``crm.objects.contacts.read``
- ``crm.objects.contacts.write``

.. figure:: https://doc.didww.com/_images/7_scopes.png
   :figclass: align-center
   :alt: Add the required HubSpot scopes
   :width: 100%

   **Fig. 7.** Add the required scopes

Step 8: Create the app and copy the Client ID and Client secret
---------------------------------------------------------------

On the same **Auth** page click **Create app**.

.. figure:: https://doc.didww.com/_images/8_create_app.png
   :figclass: align-center
   :alt: Create the HubSpot legacy app
   :width: 100%

   **Fig. 8.** Create the HubSpot app

After the app is created, stay on the **Auth** tab, then copy and save:

- **Client ID**
- **Client secret**

.. note:: Click **Show** before copying the **Client secret**

.. figure:: https://doc.didww.com/_images/8_copy_app_credentials.png
   :figclass: align-center
   :alt: Copy the Client ID and Client secret from HubSpot
   :width: 100%

   **Fig. 9.** Copy the app credentials from HubSpot

Step 9: Create and copy the HubSpot Developer API Key
------------------------------------------------------

Return to the first browser tab in HubSpot. If you do not already have an active developer API key:

1. Open **Keys**.
2. Open **Developer API Key** and click **Create key**.

.. figure:: https://doc.didww.com/_images/8_open_or_create_developer_api_key.png
   :figclass: align-center
   :alt: Open the Developer API Key page in HubSpot
   :width: 100%

   **Fig. 10.** Open or create the HubSpot Developer API Key

On the **Developer API Key** page click **Show** and  **Copy** in the **Active API Key** block.

.. figure:: https://doc.didww.com/_images/9_copy_developer_api_key.png
   :figclass: align-center
   :alt: Show and copy the HubSpot Developer API Key
   :width: 100%

   **Fig. 11.** Show and copy the Developer API Key

Step 10: Paste the HubSpot app details into phone.systems™
----------------------------------------------------------

Return to the phone.systems™ Connect HubSpot page and paste:

- **Client ID**
- **Client secret**
- **Developer API key**

Keep the **Synchronize from contacts** and **Synchronize from companies** enabled and click **Connect**.

.. figure:: https://doc.didww.com/_images/9_paste_details.png
   :figclass: align-center
   :alt: Paste the Client ID, Client secret, and Developer API key into phone.systems™
   :width: 100%

   **Fig. 12.** Paste the HubSpot app details into phone.systems™

Step 11: Authorize the HubSpot connection
-----------------------------------------

In the HubSpot pop-up window:

1. Choose an account and click **Choose account**.

.. important::
   Developer accounts cannot connect with this app. Select a non-developer HubSpot account when authorizing the integration.

.. figure:: https://doc.didww.com/_images/10_connect_hubspot_form.png
   :figclass: align-center
   :alt: Choose the HubSpot account for the integration
   :width: 100%

   **Fig. 13.** Choose the HubSpot account

2. After selecting your HubSpot account, you will be asked to review and approve access. If you agree, click **Connect app**.

.. figure:: https://doc.didww.com/_images/12_connect_hubspot_app.png
   :figclass: align-center
   :alt: Connect the unverified HubSpot app
   :width: 100%

   **Fig. 14.** Click Connect app in HubSpot

3. Enter ``I accept the risk`` in the confirmation field and click the active **Connect** button.

.. figure:: https://doc.didww.com/_images/13_confirm_unverified_app.png
   :figclass: align-center
   :alt: Confirm the unverified HubSpot app connection
   :width: 100%

   **Fig. 15.** Confirm the unverified app connection

After the authorization is complete, the HubSpot integration status in phone.systems™ changes from **Waiting authorization** to **Connected**.

.. note::
   phone.systems™ will automatically synchronize data and establish a connection with your main HubSpot account. The app will also be installed in HubSpot CRM.

.. figure:: https://doc.didww.com/_images/16_active_hubspot_connection.png
   :figclass: align-center
   :alt: Active HubSpot connection in phone.systems™
   :width: 100%

   **Fig. 16.** Active HubSpot connection in phone.systems™

----

.. raw:: html

   <br>

Associate users for HubSpot
===========================

After the HubSpot integration is successfully connected, you can associate
HubSpot users with their corresponding **phone.systems™** users.

User association enables call journaling by ensuring that inbound and outbound
calls are logged for the correct users in HubSpot. Calls handled by users who
are not associated will not receive call details in HubSpot.

1. Go to phone.systems™ **Settings**, then open **CRM Integrations**.
2. Under **Active Integrations** at the top of the page, locate **HubSpot** marked as **Connected**.
3. Click **Associate users**.

.. figure:: https://doc.didww.com/_images/17_associate_users.png
   :figclass: align-center
   :alt: Associate HubSpot users button
   :width: 100%

   **Fig. 17.** Associate HubSpot users button

The **Associate HubSpot users** page opens, where you can link **HubSpot users**
with corresponding **phone.systems™ users**.

4. Match each HubSpot user with the appropriate phone.systems™ user.
5. Click **Save** to apply the changes.

.. figure:: https://doc.didww.com/_images/17_associate_hubspot_users.png
   :figclass: align-center
   :alt: Associate HubSpot users with phone.systems™ users
   :width: 100%

   **Fig. 18.** Associate HubSpot users with phone.systems™ users

----

.. raw:: html

   <br>

Synchronizing Contacts and Companies
====================================

After connecting, you can perform a one-time synchronization to import your existing contacts and companies from HubSpot into your phone.systems™ address book.

1.  Navigate to **Settings > CRM Integrations**.
2.  Locate the active HubSpot integration and click the actions menu icon.
3.  Select **Change synchronization options** from the dropdown menu.

.. figure:: https://doc.didww.com/_images/17_sync_options.png
   :figclass: align-center
   :alt: Synchronization options menu for the HubSpot integration
   :width: 100%

   **Fig. 19.** Synchronization options

4.  In the **Synchronize contacts from** window, use the toggles to select whether you want to import **Contacts**, **Companies**, or both.
5.  Click **Submit** to begin the synchronization.

.. note::
   This is a one-time import. For ongoing, automatic creation of new contacts from calls, see the **Auto Contact Creation** settings below.

.. figure:: https://doc.didww.com/_images/18_sync_modal.png
   :figclass: align-center
   :alt: Synchronization window for contacts and companies
   :width: 100%

   **Fig. 20.** Synchronization window

----

.. raw:: html

   <br>

Configuring HubSpot Settings
============================

Once the integration is active, you can customize how data is synced between phone.systems™ and HubSpot. To access these options, navigate to **Settings > CRM Integrations** and click the settings icon next to your HubSpot connection.

.. figure:: https://doc.didww.com/_images/19.1_hubspot_settings_button.png
   :figclass: align-center
   :alt: HubSpot integration settings button
   :width: 100%

   **Fig. 21.** HubSpot integration settings button

.. important::
   The following settings apply **only** to numbers with **Call journaling** enabled. Call journaling must be configured separately for each number on the :ref:`Edit phone numbers page <ps3_edit_phone_numbers>`.

.. figure:: https://doc.didww.com/_images/19_hubspot_settings.png
   :figclass: align-center
   :alt: HubSpot integration settings in phone.systems™
   :width: 100%

   **Fig. 22.** HubSpot integration settings

Auto Contact Creation
---------------------

This feature automatically creates a new contact in HubSpot when a call is received from or made to a number that does not match an existing contact in your CRM.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - When enabled, a new contact will be created in HubSpot for all inbound calls from unknown numbers.
   * - **Outbound calls**
     - When enabled, a new contact will be created in HubSpot for all outbound calls to unknown numbers.
   * - **Contact type**
     - Select the default HubSpot contact type to be assigned when a new contact is created automatically.

Other Settings
--------------

Manage which call-related data is automatically uploaded to your HubSpot contacts’ activity timelines.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Upload call recordings to CRM**
     - When enabled, a link to the call recording will be automatically added to the call log in HubSpot.

       .. note:: To utilize this feature, call recording must be enabled for your :ref:`contact method <ps3_contact_methods>`.

   * - **Upload AI call insights results**
     - When enabled, detailed analytics from our AI engine will be added to the call log. This can include:

       - **Key topics:** A summary of the main topics discussed.
       - **Call summary:** A concise, AI-generated summary of the conversation.
       - **Talk to listen ratio:** A breakdown of how much each party spoke.
       - **Sentiment analysis:** An analysis of the emotional tone of the call.
       - **Transcription:** A full, written transcript of the call.

       .. note:: To utilize the AI features, :ref:`AI Call Insights <ps3_ai_settings_enable>` must be enabled.

After configuring these options, click **Save** to apply your changes.


.. _ps3_zendesk_integration:

Zendesk and phone.systems™ Integration
######################################

Connecting **phone.systems™** with **Zendesk CRM** allows you to manage customer calls and track important information. The integration includes the following features:

- **Sync contacts automatically**: Keep customers (end users) updated in phone.systems™.
- **Call journaling**: All incoming and outgoing calls are logged in Zendesk for tracking and reference.
- **Create new contacts automatically**: When an unknown number calls, a new customer (end user) is created in Zendesk automatically.
- **User association for call journaling**: Associating users enables call journaling between phone.systems™ and Zendesk. Unassociated users will not receive call details in Zendesk.

----

.. raw:: html

   <br>

Connecting phone.systems™ with Zendesk
======================================

This guide provides detailed steps on integrating phone.systems™ with Zendesk CRM. Follow the instructions below to complete the setup process.

.. note::
 To connect phone.systems™ with Zendesk, you need **Unique Identifier**, **Secret**, and **Subdomain**. Generate these values by creating a connected app in your Zendesk admin account.

Step 1: Sign In to a Zendesk account
------------------------------------

To get started, go to the `Zendesk page <https://www.zendesk.com/>`_ and **Sign In** to access an existing account or create a new one.

Step 2: Create an app in Zendesk
--------------------------------

Once you’re logged in, click the Zendesk products |zendesk_products_icon| icon on the right side, then select **Admin Center**.

.. figure:: https://doc.didww.com/_images/1_open_admin_center.png
  :figclass: align-center
  :alt: Open Zendesk Admin Center
  :width: 100%

  **Fig. 1.** Open Zendesk Admin Center

On the new page, go to the left sidebar menu. Expand **Apps and integrations** and select **OAuth clients** under the **APIs** menu. On the custom integration setup page, agree to the **Zendesk Terms of Service and Application Development and API License Agreement**, and select **Get started**.

.. figure:: https://doc.didww.com/_images/2_confirm_to_open_zendesk_api.png
   :figclass: align-center
   :alt: Start Building Custom Integration
   :width: 100%

   **Fig. 2.** Start Building Custom Integration

Click **Add OAuth client**.

.. figure:: https://doc.didww.com/_images/3_create_an_app.png
   :figclass: align-center
   :alt: Add OAuth client
   :width: 100%

   **Fig. 3.** Add OAuth client

Step 3: Enter app client basic information
------------------------------------------

In the first section, enter the **Name**, **Description** and any other optional information you want to include.

.. figure:: https://doc.didww.com/_images/4_enter_client_name.png
  :figclass: align-center
  :alt: Enter app basic information
  :width: 100%

  **Fig. 4.** Enter app basic information

Step 4: Set the Client kind
---------------------------

Scroll down until you see the **Client kind** section. Select **Confidential**.

.. figure:: https://doc.didww.com/_images/4_client_kind.png
  :figclass: align-center
  :alt: Set the Client kind
  :width: 100%

  **Fig. 5.** Set the Client kind

Step 5: Launch phone.systems™ and create Zendesk connection
-----------------------------------------------------------

 1. Open a new browser tab, log in to your DIDWW account, and launch `phone.systems™ <https://my.didww.com/#/phone_systems>`_.
 2.	In phone.systems™, go to Settings > CRM Integrations.
 3.	Click **Connect** to link Zendesk app with phone.systems™.

.. figure:: https://doc.didww.com/_images/5_create_zendesk_connection_in_phone_systems.png
   :figclass: align-center
   :alt: Create Zendesk connection in phone.systems™
   :width: 100%

   **Fig. 6.** Create Zendesk connection in phone.systems™

Step 6: Copy the Redirect URL from phone.systems™ and paste it in Zendesk
-------------------------------------------------------------------------

On the phone.systems™ Zendesk connection page, copy the **Redirect URL**.

.. figure:: https://doc.didww.com/_images/6_copy_redirect_url.png
   :figclass: align-center
   :alt: Copy the Redirect URL
   :width: 100%

   **Fig. 7.** Copy the Redirect URL

Open the Zendesk app creation page, scroll to the bottom, paste the **Redirect URL**, and **Save** the settings.

.. figure:: https://doc.didww.com/_images/7_paste_redirect_url.png
   :figclass: align-center
   :alt: Paste the Redirect URL
   :width: 100%

   **Fig. 8.** Paste the Redirect URL

Step 7: Copy the Unique Identifier and Secret from Zendesk and paste it in phone.systems™
-----------------------------------------------------------------------------------------

After saving the basic settings, a **Secret** will be generated. Copy the **Secret** immediately, as you will only see it once. If needed, you can generate a new **Secret** later.

Once the **Secret** is copied and saved, copy the **Identifier**.

.. warning:: Copy and store this secret. It won't be shown in full again after you click Save or leave this page.

.. figure:: https://doc.didww.com/_images/8_copy_secret_and_unique_identifier.png
  :figclass: align-center
  :alt: Copy the Unique Identifier and Secret
  :width: 100%

  **Fig. 9.** Copy the Unique Identifier and Secret

Open the phone.systems™ Zendesk connection page, and paste the **Unique Identifier** and **Secret** into the corresponding fields.

.. figure:: https://doc.didww.com/_images/9_paste_secret_and_unique_identifier.png
  :figclass: align-center
  :alt: Paste the Unique Identifier and Secret
  :width: 100%

  **Fig. 10.** Paste the Unique Identifier and Secret

Step 8: Copy the Subdomain from Zendesk and paste it in phone.systems™
-----------------------------------------------------------------------

Open the Zendesk app creation page and locate the subdomain name in the top-left corner or in the first part of the website URL, as shown in the figure below.

.. figure:: https://doc.didww.com/_images/10_2_copy_subdomain_value.png
  :figclass: align-center
  :alt: Copy the Subdomain
  :width: 100%

  **Fig. 11.** Copy the Subdomain

Then, open the phone.systems™ Zendesk connection page and paste the **Subdomain** into the corresponding field.

.. figure:: https://doc.didww.com/_images/11_2_paste_subdomain.png
  :figclass: align-center
  :alt: Copy the Subdomain
  :width: 100%

  **Fig. 12.** Paste the Subdomain

Step 9: Connect the phone.systems™ Zendesk app
-----------------------------------------------

To complete the connection between phone.systems™ and Zendesk, open the phone.systems™ page and click **Connect**.

When the access permissions page appears, click **Allow**.

.. figure:: https://doc.didww.com/_images/13_allow_access.png
  :figclass: align-center
  :alt: Allow Access
  :width: 100%

  **Fig. 13.** Allow Access

After you click **Allow**, you will be redirected back to the phone.systems™ CRM Integrations page. Zendesk will appear under **Active Integrations** with the status **Connected**.

.. note::
   phone.systems™ will automatically synchronize data and establish a connection with your main Zendesk account. The app will also be installed in Zendesk CRM.

.. figure:: https://doc.didww.com/_images/14_active_zendesk_connection.png
      :figclass: align-center
      :alt: Active Zendesk connection in phone.systems™
      :width: 100%

      **Fig. 14.** Active Zendesk connection in phone.systems™

----

.. raw:: html

   <br>

Configuring Zendesk Settings
============================

Once the integration is active, you can customize its behavior. To access these options, navigate to **Settings > CRM Integrations** and click the **Settings** icon next to your Zendesk connection.

.. figure:: https://doc.didww.com/_images/15_settings_button.png
   :figclass: align-center
   :alt: Zendesk integration settings button.
   :width: 100%

   **Fig. 15.** Zendesk integration settings button.

.. important::
   The following settings apply **only** to numbers with **Call journaling** enabled. Call journaling must be configured separately for each number on the :ref:`Edit phone numbers page <ps3_edit_phone_numbers>`.

.. figure:: https://doc.didww.com/_images/16_zendesk_settings.png
   :figclass: align-center
   :alt: Zendesk integration settings in phone.systems™
   :width: 100%

   **Fig. 16.** Zendesk integration settings.

Call Journaling
---------------

This section provides important information about how calls are logged in Zendesk.

.. note::
   Tickets in Zendesk will be created **only for incoming lost calls**.

Auto Contact Creation
---------------------

This feature automatically creates a new user (end user) in Zendesk when a call is handled from a number that does not match an existing contact in your CRM.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - When enabled, a new user will be created in Zendesk for all inbound calls from unknown numbers.
   * - **Outbound calls**
     - When enabled, a new user will be created in Zendesk for all outbound calls to unknown numbers.

After configuring these options, click **Save** to apply your changes.

.. |zendesk_products_icon| image:: /img/phone_systems/crm_integrations/zendesk/zendesk_products_icon.png
   :class: inline-img no-shadow

.. _ps3_pipedrive_integration:

Pipedrive and phone.systems™ Integration
########################################

Connecting **phone.systems™** with **Pipedrive CRM** allows you to manage customer calls and track important information. The integration includes the following features:

- **Sync contacts automatically**: Keep contacts and company details updated in phone.systems™ and Pipedrive.
- **Call journaling**: All incoming and outgoing calls are logged in Pipedrive for tracking and reference.
- **Create new contacts automatically**: When an unknown number calls, a new contact or company is created in Pipedrive automatically.
- **Store call recordings**: Call recordings are uploaded to Pipedrive for easy access and review.
- **User association for call journaling**: Associating users enables call journaling between phone.systems™ and Pipedrive. Unassociated users will not receive call details in Pipedrive.

----

.. raw:: html

   <br>

Connecting phone.systems™ with Pipedrive
========================================

This guide provides detailed steps for integrating **phone.systems™** with **Pipedrive** using a Pipedrive developer account. Follow the instructions below to complete the setup process.

.. note::
   To connect phone.systems™ with Pipedrive, you will need the **Client ID** and **Client Secret**, which can be obtained from the **Pipedrive developer account**.

Step 1: Log in or request a Pipedrive developer account
-----------------------------------------------------------

To get started, go to the `Pipedrive Developer Account page <https://developers.pipedrive.com/>`_  and **Sign In** to access an existing account or create a new one.

Step 2: Create an app in Pipedrive
----------------------------------

Once you're logged in, click on the account settings button in the top-right corner to open the dropdown menu. Then, select **Developer Hub**. On the Developer Hub page, click the **Create an app** button.

.. figure:: https://doc.didww.com/_images/1_create_an_app.png
  :figclass: align-center
  :alt: Create an app in Pipedrive
  :width: 100%

  **Fig. 1.** Create an app in Pipedrive

A pop-up screen will appear. Select private app type and click **Create private app**.

.. figure:: https://doc.didww.com/_images/2_create_private_app.png
  :figclass: align-center
  :alt: Select create private app
  :width: 100%

  **Fig. 2.** Select create private app

Step 3: Enter app basic information
-----------------------------------

In the **Basic info** section, enter your **App name**.

.. figure:: https://doc.didww.com/_images/3_enter_app_name.png
  :figclass: align-center
  :alt: Enter app name
  :width: 100%

  **Fig. 3.** Enter app name

Step 4: Launch phone.systems™ and create Pipedrive connection
-------------------------------------------------------------

After entering the app name, you will need to enter the **Callback URL**, which can be retrieved from the phone.systems™ Pipedrive connection page.

 1. Open a new browser tab, log in to your DIDWW account, and launch `phone.systems™ <https://my.didww.com/#/phone_systems>`_.
 2.	In phone.systems™, go to Settings > CRM Integrations.
 3.	Click **Connect** to link Pipedrive app with phone.systems™.

.. figure:: https://doc.didww.com/_images/5_create_pipedrive_connection_in_phone_systems.png
   :figclass: align-center
   :alt: Create Pipedrive connection in phone.systems™
   :width: 100%

   **Fig. 4.** Create Pipedrive connection in phone.systems™

Step 5: Copy the Redirect URL from phone.systems™ and paste it in your Pipedrive app
------------------------------------------------------------------------------------

On the phone.systems™ Pipedrive connection page, copy the **Redirect URL**.

.. figure:: https://doc.didww.com/_images/6_copy_redirect_url.png
   :figclass: align-center
   :alt: Copy the redirect URL
   :width: 100%

   **Fig. 5.** Copy the redirect URL

Open the Pipedrive app creation page, paste the **Redirect URL** into the **Callback URL** input field, and click **Save**

.. figure:: https://doc.didww.com/_images/7_paste_the_redirect_url.png
   :figclass: align-center
   :alt: Paste the redirect URL
   :width: 100%

   **Fig. 6.** Paste the redirect URL

Step 6: Add the required scopes to define app permissions
---------------------------------------------------------

After saving the basic information, the **OAuth & Access Scopes** section opens. Configure permissions to allow phone.systems™ read data from your Pipedrive app.

.. note::
   This setup is essential for establishing the connection and synchronizing data between both systems.

Enable the following access scopes:

1. **Activities** – Enable and select **Full access**.
2. **Contacts** – Enable and select **Full access**.
3. **Read users data** – Enable.
4. **Leads** – Enable and select **Full access**.
5. **Call logs** – Enable and select **Full access**.
6. **Webhooks** – Enable and select **Full access**.

.. figure:: https://doc.didww.com/_images/8_access_scopes_selected.png
   :figclass: align-center
   :alt: Enabled access scopes in Pipedrive
   :width: 100%

   **Fig. 7.** Enabled access scopes in Pipedrive

Step 7: Copy the Client ID and Client secret from Pipedrive and paste it in phone.systems™
------------------------------------------------------------------------------------------

After you have enabled the required permissions, scroll down the page to find and copy the generated app credentials (**Client ID** and **Client Secret**).

   .. figure:: https://doc.didww.com/_images/9_copy_client_id_client_secret.png
      :figclass: align-center
      :alt: Copy the Client ID and Client secret
      :width: 100%

      **Fig. 8.** Copy the Client ID and Client secret

Open the phone.systems™ Pipedrive connection page, and paste the **Client ID** and **Client secret** into the corresponding fields.

   .. figure:: https://doc.didww.com/_images/10_paste_client_id_client_secret.png
      :figclass: align-center
      :alt: Paste the Client ID and Client secret
      :width: 100%

      **Fig. 9.** Paste the Client ID and Client secret

Step 8: Save the application and change to live mode
----------------------------------------------------

.. note::

   To link the main (non-sandbox) Pipedrive account with phone.systems™, you must switch the app status to "Live". This step establishes a connection with the main Pipedrive account and grants the necessary permissions for synchronization between Pipedrive and phone.systems™.

1. On the Pipedrive app settings page, save the configuration by clicking **Save** in the top-right corner.

2. Click **Change to live** to transition the draft app from Sandbox to Live mode.

   .. figure:: https://doc.didww.com/_images/11_save_and_change_to_live_pipedrive_app.png
      :figclass: align-center
      :alt: Save and change the draft app from Sandbox to Live mode
      :width: 100%

      **Fig. 10.** Save and change the draft app from Sandbox to Live mode

Step 9: Connect the phone.systems™ Pipedrive app
------------------------------------------------

To complete the connection between phone.systems™ and Pipedrive, open the **phone.systems™** page and click **Connect**.

When the access permissions page appears, select your main Pipedrive account and click **Allow and Install**.

.. figure:: https://doc.didww.com/_images/12_1_select_the_main_pipedrive_account.png
  :figclass: align-center
  :alt: Select Pipedrive account
  :width: 100%

  **Fig. 11.** Select Pipedrive account

After clicking **Allow and Install**, access will be granted and you will return back to the **phone.systems™ CRM Integrations** page, where Pipedrive will appear under **Active Integrations** with the status **Connected**.

.. note::
   phone.systems™ will automatically synchronize data and establish a connection with your main Pipedrive account. The app will also be installed in Pipedrive CRM.

.. figure:: https://doc.didww.com/_images/12_2_pipedrive_connected.png
      :figclass: align-center
      :alt: Active Pipedrive connection in phone.systems™
      :width: 100%

      **Fig. 12.** Active Pipedrive connection in phone.systems™

----

.. raw:: html

   <br>

Configuring Pipedrive Settings
==============================

Once the integration is active, you can customize its behavior. To access these options, navigate to **Settings > CRM Integrations** and click the **Settings** icon next to your Pipedrive connection.

.. figure:: https://doc.didww.com/_images/13_settings_button.png
   :figclass: align-center
   :alt: Pipedrive integration settings button.
   :width: 100%

   **Fig. 13.** Pipedrive integration settings button.

.. important::
   The following settings apply **only** to numbers with **Call journaling** enabled. Call journaling must be configured separately for each number on the :ref:`Edit phone numbers page <ps3_edit_phone_numbers>`.

.. figure:: https://doc.didww.com/_images/14_pipedrive_settings.png
   :figclass: align-center
   :alt: Pipedrive integration settings in phone.systems™
   :width: 100%

   **Fig. 14.** Pipedrive integration settings.

Auto Contact Creation
---------------------

This feature automatically creates a new contact in Pipedrive when a call is handled from a number that does not match an existing contact in your CRM.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - When enabled, a new contact will be created in Pipedrive for all inbound calls from unknown numbers.
   * - **Outbound calls**
     - When enabled, a new contact will be created in Pipedrive for all outbound calls to unknown numbers.

Other Settings
--------------

These settings control what additional call-related data is automatically uploaded to your Pipedrive contacts' activity timelines.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Upload call recordings to CRM**
     - When enabled, a link to the call recording will be automatically added to the call log in Pipedrive.

       .. note:: To utilize this feature, call recording must be enabled for your :ref:`contact method <ps3_contact_methods>`.

   * - **Upload AI call insights results**
     - When enabled, detailed analytics from our AI engine will be added to the call log. This can include:

       - **Key topics:** A summary of the main topics discussed.
       - **Call summary:** A concise, AI-generated summary of the conversation.
       - **Talk to listen ratio:** A breakdown of how much each party spoke.
       - **Sentiment analysis:** An analysis of the emotional tone of the call.
       - **Transcription:** A full, written transcript of the call.

       .. note:: To utilize the AI features, :ref:`AI Call Insights <ps3_ai_settings_enable>` must be enabled.

After configuring these options, click **Save** to apply your changes.



.. _ps3_salesforce_integration:

Salesforce and phone.systems™ Integration
#########################################

Connecting **phone.systems™** with **Salesforce CRM** allows you to manage customer calls and track important information. The integration includes the following features:

- **Sync contacts automatically**: Keep contacts, leads and company details updated in phone.systems™ and Salesforce.
- **Call journaling**: All incoming and outgoing calls are logged in Salesforce for tracking and reference.
- **Create new contacts automatically**: When an unknown number calls, a new contact, lead or company is created in Salesforce automatically.
- **User association for call journaling**: Associating users enables call journaling between phone.systems™ and Salesforce. Unassociated users will not receive call details in Salesforce.

----

.. raw:: html

   <br>

Connecting phone.systems™ with Salesforce
=========================================

This guide provides detailed steps on integrating phone.systems™ with Salesforce CRM. Follow the instructions below to complete the setup process.

.. note::
 To connect phone.systems™ with Salesforce, you need the **Consumer Key** and **Consumer Secret**. Generate these values by creating an External Client App in your Salesforce account.

Step 1: Login to a Salesforce account
-------------------------------------

To get started, go to the `Salesforce page <https://www.salesforce.com/>`_ and **Login** to access an existing account or create a new one.

Step 2: Create an app in Salesforce
-----------------------------------

1. Click the |settings_gear_icon| icon in the top-right corner
2. Select **Setup**.
3. In the left sidebar, expand **Apps** and select **App Manager**.

.. figure:: https://doc.didww.com/_images/1_open_app_manager_page.png
  :figclass: align-center
  :alt: Open Salesforce Platform Tools App Manager page
  :width: 100%

  **Fig. 1.** Open Salesforce Platform Tools App Manager page

On the app manager setup page, click **New External Client App**.

.. figure:: https://doc.didww.com/_images/2_1_click_new_connected_app.png
   :figclass: align-center
   :alt: Click New External Client App
   :width: 100%

   **Fig. 2.** Click New External Client App

Step 3: Enter app basic information
-----------------------------------

In the **Basic Information** section, enter the required fields:

    - **External Client App Name**
    - **API Name**
    - **Contact Email**

    .. note:: Leave the **Distribution State** on the default **local** value.

.. figure:: https://doc.didww.com/_images/3_create_app_basic_info.png
  :figclass: align-center
  :alt: Enter app required basic information
  :width: 100%

  **Fig. 3.** Enter app required basic information

Step 4: Launch phone.systems™ and create Salesforce connection
--------------------------------------------------------------

 1. Open a new browser tab, log in to your DIDWW account, and launch `phone.systems™ <https://my.didww.com/#/phone_systems>`_.
 2.	In phone.systems™, go to Settings > CRM Integrations.
 3.	Click **Connect** to link Salesforce app with phone.systems™.

.. figure:: https://doc.didww.com/_images/4_create_salesforce_connection_in_phone_systems.png
   :figclass: align-center
   :alt: Create Salesforce connection in phone.systems™
   :width: 100%

   **Fig. 4.** Create Salesforce connection in phone.systems™

Step 5: Copy the Redirect URL from phone.systems™ and paste it in your Salesforce app
-------------------------------------------------------------------------------------

On the phone.systems™ Salesforce connection page, copy the **Redirect URL**.

.. figure:: https://doc.didww.com/_images/5_1_copy_redirect_url.png
   :figclass: align-center
   :alt: Copy the Redirect URL
   :width: 100%

   **Fig. 5.** Copy the Redirect URL

Open the Salesforce app creation page and perform these actions:

    1. Expand the **API (Enable OAuth Settings)** menu and **Enable** OAuth Settings to reveal additional options
    2. Paste into the **Callback URL** field.

.. figure:: https://doc.didww.com/_images/5_2_paste_the_redirect_url.png
   :figclass: align-center
   :alt: Paste the Redirect URL into Callback URL
   :width: 100%

   **Fig. 6.** Paste the Redirect URL into Callback URL

Step 6: Add the OAuth scopes to define app permissions and the app
-------------------------------------------------------------------

Continue in the Salesforce API (Enable OAuth Settings) section, select the **Available OAuth Scopes** that determine the permissions your app has to access data or perform actions in Salesforce CRM.

1. Locate the **Available OAuth Scopes** permission list and add the following scopes:

     - **Access Connect REST API resources (chatter_api)**
     - **Access the identity URL service (id, profile, email, address, phone)**
     - **Full access (full)**
     - **Perform requests at any time (refresh_token, offline_access)**

.. note::
   Selecting the scopes is required to ensure your app has the necessary permissions to function correctly with all supported features.

2. Uncheck the **Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows**.

.. note::
   PKCE must be disabled because phone.systems™ uses a server-to-server OAuth flow that does not support dynamic PKCE code challenges.

3. Click **Create** at the bottom of the page to create the application.

.. figure:: https://doc.didww.com/_images/6_add_availalble_oauth_scopes_to_selected_oauth.png
  :figclass: align-center
  :alt: Add the available OAuth Scopes
  :width: 100%

  **Fig. 7.** Add the available OAuth Scopes

Step 7: Obtain the Consumer Key and Consumer Secret
---------------------------------------------------

To complete the connection between phone.systems™ and Salesforce, obtain the **Consumer Key** and **Consumer Secret**.

In the **Manage External Client Apps** page, perform the following actions:

    1. Open the **Settings** tab.
    2. Expand the **OAuth Settings** and click on **Consumer Key and Secret**.

.. figure:: https://doc.didww.com/_images/8_2_manage_consumer_details.png
  :figclass: align-center
  :alt: Click Manage Consumer Details
  :width: 100%

  **Fig. 8.** Click Manage Consumer Details

Salesforce will then send a verification code and ask you to verify your identity. Enter the code and select **Verify**.

.. figure:: https://doc.didww.com/_images/8_3_entered_verification_code_2.png
  :figclass: align-center
  :alt: Verify Salesforce Identity
  :width: 30%

  **Fig. 9.** Verify Salesforce Identity

Step 8: Copy the Consumer Key and Consumer Secret from Salesforce and paste it in phone.systems™
------------------------------------------------------------------------------------------------

After verifying your identity, you will be redirected to the **Consumer Details** page. Copy the **Consumer Key** and **Consumer Secret**.

.. figure:: https://doc.didww.com/_images/9_1_copy_app_credentials.png
  :figclass: align-center
  :alt: Paste phone.systems™ Client ID and Client secret
  :width: 100%

  **Fig. 10.** Copy the Consumer Key and Consumer Secret

Open the phone.systems™ Salesforce connection page, and paste the **Consumer Key** and **Consumer Secret** into the corresponding fields.

.. figure:: https://doc.didww.com/_images/9_2_paste_app_credentials.png
  :figclass: align-center
  :alt: Paste the Consumer Key and Consumer Secret
  :width: 100%

  **Fig. 11.** Paste the Consumer Key and Consumer Secret

Step 9: Connect the phone.systems™ Salesforce app
--------------------------------------------------

To complete the connection between phone.systems™ and Salesforce, open the phone.systems™ page and click **Connect**.

.. tip::
   The “invalid_client_id” message may appear shortly after creating the app.
   Wait several minutes before attempting to connect again. This allows Salesforce to register the new app credentials.

When the access permissions page appears, click **Allow**.

.. figure:: https://doc.didww.com/_images/11_allow_access.png
  :figclass: align-center
  :alt: Allow Access
  :width: 30%

  **Fig. 12.** Allow Access

After you click **Allow**, you will be redirected back to the phone.systems™ CRM Integrations page. Salesforce will appear under **Active Integrations** with the status **Connected**.

.. note::
   phone.systems™ will automatically synchronize data and establish a connection with your main Salesforce account. The app will also be installed in Salesforce CRM.

.. figure:: https://doc.didww.com/_images/12_active_salesforce_connection.png
      :figclass: align-center
      :alt: Active Salesforce connection in phone.systems™
      :width: 100%

      **Fig. 13.** Active Salesforce connection in phone.systems™

----

.. raw:: html

   <br>

Synchronizing Contacts, Companies, and Leads
============================================

After connecting, you can perform a one-time synchronization to import your existing data from Salesforce into your phone.systems™ address book.

    1.  Navigate to **Settings > CRM Integrations**.
    2.  Locate the active Salesforce integration and click the actions menu icon.
    3.  Select **Change synchronization options** from the dropdown menu.

        .. figure:: https://doc.didww.com/_images/16_sync_options.png
           :figclass: align-center
           :alt: The synchronization options menu.
           :width: 100%

           **Fig. 14.** Synchronization options.

    4.  In the **Synchronize contacts from** window, use the toggles to select whether you want to import **Contacts**, **Companies**, **Leads**, or a combination.
    5.  Click **Submit** to begin the synchronization.

        .. note::
           This is a one-time import. For ongoing, automatic creation of new contacts from calls, see the **Auto Contact Creation** settings below.

        .. figure:: https://doc.didww.com/_images/17_sync_modal.png
           :figclass: align-center
           :alt: The synchronization window for contacts, companies, and leads.
           :width: 100%

           **Fig. 15.** Synchronization window.

----

.. raw:: html

   <br>

Configuring Salesforce Settings
===============================

Once the integration is active, you can customize how data is synced between phone.systems™ and Salesforce. To access these options, navigate to **Settings > CRM Integrations** and click the **Settings** icon next to your Salesforce connection.

    .. figure:: https://doc.didww.com/_images/18_settings_button.png
       :figclass: align-center
       :alt: Salesforce integration settings button.
       :width: 100%

       **Fig. 16.** Salesforce integration settings button.

    .. important::
       The following settings apply **only** to numbers with **Call journaling** enabled. Call journaling must be configured separately for each number on the :ref:`Edit phone numbers page <ps3_edit_phone_numbers>`.

    .. figure:: https://doc.didww.com/_images/19_salesforce_settings.png
       :figclass: align-center
       :alt: Salesforce integration settings in phone.systems™
       :width: 100%

       **Fig. 17.** Salesforce integration settings.

Auto Contact Creation
---------------------

This feature automatically creates a new contact or lead in Salesforce when a call is handled from a number that does not match an existing record in your CRM.

    .. list-table::
       :header-rows: 1
       :widths: 30 70

       * - **Setting**
         - **Description**
       * - **Inbound calls**
         - When enabled, a new record will be created in Salesforce for all inbound calls from unknown numbers.
       * - **Outbound calls**
         - When enabled, a new record will be created in Salesforce for all outbound calls to unknown numbers.
       * - **Contact type**
         - Select the default record type (**Contact** or **Lead**) to be created automatically.

Other Settings
--------------

This section controls what additional call-related data is automatically uploaded to your Salesforce records.

    .. list-table::
       :header-rows: 1
       :widths: 30 70

       * - **Setting**
         - **Description**
       * - **Upload AI call insights results**
         - When enabled, detailed analytics from our AI engine will be added to the call log. This can include:

           - **Key topics:** A summary of the main topics discussed.
           - **Call summary:** A concise, AI-generated summary of the conversation.
           - **Talk to listen ratio:** A breakdown of how much each party spoke.
           - **Sentiment analysis:** An analysis of the emotional tone of the call.
           - **Transcription:** A full, written transcript of the call.

           .. note:: To utilize the AI features, :ref:`AI Call Insights <ps3_ai_settings_enable>` must be enabled.

After configuring these options, click **Save** to apply your changes.

.. |settings_gear_icon| image:: /img/phone_systems/crm_integrations/salesforce/settings_gear_icon.png
   :class: inline-img no-shadow

.. _ps3_zoho_integration:

Zoho and phone.systems™ Integration
####################################

Connecting **phone.systems™** with **Zoho CRM** allows you to manage customer calls and track important information. When the two systems are linked, contact details can be automatically synchronized, and call history can be logged in Zoho. The integration includes the following features:

- **Sync contacts automatically**: Keep contacts, leads and company details updated in phone.systems™ and Zoho CRM.
- **Call journaling**: All incoming and outgoing calls are logged in Zoho CRM for tracking and reference.
- **Create new contacts automatically**: When an unknown number calls, a new contact, lead or company is created in Zoho CRM automatically.
- **User association for call journaling**: Associating users enables call journaling between phone.systems™ and Zoho. Unassociated users will not receive call details in Zoho CRM.

----

.. raw:: html

   <br>

Connecting phone.systems™ with Zoho
===================================

This guide provides detailed steps on integrating phone.systems™ with Zoho using **Zoho API Console**. Follow the instructions below to complete the setup process.

.. note::
   To connect phone.systems™ with Zoho, you will need the **Client ID** and **Client Secret**, which can be obtained from the **Zoho developer account**.

Step 1: Sign in to your Zoho account or create a new account
------------------------------------------------------------

To begin, go to the `Zoho CRM page <https://www.zoho.com/crm/>`_ and **Sign In** to access an existing account or create a new one.

Step 2: Open Zoho API console
-----------------------------

After signing in to your Zoho account, go to `Zoho API Console page <https://api-console.zoho.eu/>`_ and click **Get Started**.

.. figure:: https://doc.didww.com/_images/1_open_api_console.png
  :figclass: align-center
  :alt: Open Zoho API Console Page
  :width: 100%

  **Fig. 1.** Open Zoho API Console Page

Step 3: Create server-based application
---------------------------------------

In the **Choose Client Type** section, find the **Server-based Applications** block and select **Create Now**.

.. figure:: https://doc.didww.com/_images/2_create_server_based_application.png
  :figclass: align-center
  :alt: Create Server-based Application
  :width: 100%

  **Fig. 2.** Create Server-based Application

Step 4: Enter client name and homepage URL
------------------------------------------

On the **Create New Client** page, enter your **Client Name** and **Homepage URL**.

.. figure:: https://doc.didww.com/_images/3_zoho_create_new_client.png
  :figclass: align-center
  :alt: Enter client name and homepage url
  :width: 100%

  **Fig. 3.** Enter client name and homepage url

Step 5: Launch phone.systems™ and create Zoho connection
--------------------------------------------------------

 1. Open a new browser tab, log in to your DIDWW account, and launch `phone.systems™ <https://my.didww.com/#/phone_systems>`_.
 2.	In phone.systems™, go to Settings > CRM Integrations.
 3.	Click **Connect** to link Zoho app with phone.systems™.

.. figure:: https://doc.didww.com/_images/4_create_zoho_connection_in_phone_systems.png
   :figclass: align-center
   :alt: Create Zoho connection in phone.systems™
   :width: 100%

   **Fig. 4.** Create Zoho connection in phone.systems™

Step 6: Copy and paste the Redirect URL
---------------------------------------

On the phone.systems™ Zoho connection page, copy the **Redirect URL**.

.. figure:: https://doc.didww.com/_images/5_copy_the_redirect_url_from_phone_systems.png
   :figclass: align-center
   :alt: Copy the Redirect URL
   :width: 100%

   **Fig. 5.** Copy the Redirect URL

Open the Zoho create new client page, and paste the **Redirect URL** in the **Authorized Redirect URLs**.

.. figure:: https://doc.didww.com/_images/6_paste_redirect_url.png
   :figclass: align-center
   :alt: Paste the redirect URL
   :width: 100%

   **Fig. 6.** Paste the redirect URL

Step 7: Create the app
----------------------

After entering the required fields (**Client Name**, **Homepage URL**, and **Authorized Redirect URLs**), click **Create**.

Once the app is created, the app credentials (**Client ID** and **Client Secret**) will be generated.

   .. figure:: https://doc.didww.com/_images/7_create_the_app_generates_the_client_and_client_secret_id.png
      :figclass: align-center
      :alt: App credentials
      :width: 100%

      **Fig. 7.** App credentials

Step 8: Copy and Paste the Client ID and Client secret
------------------------------------------------------

Copy the **Client ID** and **Client secret** from the Zoho API Console application page, then **Paste** them into the respective fields on the phone.systems™ Zoho connection page.

   .. figure:: https://doc.didww.com/_images/8_copy_and_paste_the_client_id_and_client_secret.png
      :figclass: align-center
      :alt: Paste Client ID and Client secret into phone.systems™
      :width: 100%

      **Fig. 8.** Paste Client ID and Client secret into phone.systems™

Step 9: Connect the application to Zoho
----------------------------------------

To complete the connection, click **Connect** on the phone.systems™ page. Review the access permissions for Zoho CRM, and if you agree, click **Accept**.

.. note::
   To ensure a successful connection, grant permission for phone.systems™ to access Zoho CRM data. Without permission, the connection cannot be completed.

.. figure:: https://doc.didww.com/_images/10_connect_to_zoho.png
      :figclass: align-center
      :alt: Confirm Access To Connect with Zoho Account
      :width: 100%

      **Fig. 9.** Confirm Access To Connect with Zoho Account

When access is granted, you will be redirected to the **phone.systems™ CRM Integrations** page. Zoho will then appear under **Active Integrations**, and after synchronization, its status will update to **Connected**.

.. note::
   phone.systems™ will automatically synchronize data and establish a connection with your main Zoho account. The app will also be installed in Zoho CRM.

.. figure:: https://doc.didww.com/_images/11_active_zoho_connection_in_phone_systems.png
      :figclass: align-center
      :alt: Active Zoho connection in phone.systems™
      :width: 100%

      **Fig. 10.** Active Zoho connection in phone.systems™

----

.. raw:: html

   <br>

Synchronizing Contacts, Companies, and Leads
============================================

After connecting, you can perform a one-time synchronization to import your existing data from Zoho into your phone.systems™ address book.

1.  Navigate to **Settings > CRM Integrations**.
2.  Locate the active Zoho integration and click the actions menu icon.
3.  Select **Change synchronization options** from the dropdown menu.

    .. figure:: https://doc.didww.com/_images/12_sync_options.png
       :figclass: align-center
       :alt: The synchronization options menu.
       :width: 100%

       **Fig. 11.** Synchronization options.

4.  In the **Synchronize contacts from**, use the toggles to select whether you want to import **Contacts**, **Companies**, **Leads**, or a combination.
5.  Click **Submit** to begin the synchronization.

    .. note::
       This is a one-time import. For ongoing, automatic creation of new contacts from calls, see the **Auto Contact Creation** settings below.

    .. figure:: https://doc.didww.com/_images/13_sync_modal.png
       :figclass: align-center
       :alt: The synchronization window for contacts, companies, and leads.
       :width: 100%

       **Fig. 12.** Synchronization window.

----

.. raw:: html

   <br>

Configuring Zoho Settings
=========================

Once the integration is active, you can customize its behavior. To access these options, navigate to **Settings > CRM Integrations** and click the **Settings** icon next to your Zoho connection.

.. figure:: https://doc.didww.com/_images/14_settings_button.png
   :figclass: align-center
   :alt: Zoho integration settings button.
   :width: 100%

   **Fig. 13.** Zoho integration settings button.

.. important::
   The following settings apply **only** to numbers with **Call journaling** enabled. Call journaling must be configured separately for each number on the :ref:`Edit phone numbers page <ps3_edit_phone_numbers>`.

.. figure:: https://doc.didww.com/_images/15_zoho_settings.png
   :figclass: align-center
   :alt: Zoho integration settings in phone.systems™
   :width: 100%

   **Fig. 14.** Zoho integration settings.

Auto Contact Creation
---------------------

This feature automatically creates a new contact or lead in Zoho when a call is handled from a number that does not match an existing record in your CRM.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - When enabled, a new record will be created in Zoho for all inbound calls from unknown numbers.
   * - **Outbound calls**
     - When enabled, a new record will be created in Zoho for all outbound calls to unknown numbers.
   * - **Contact type**
     - Select the default record type (**Contact** or **Lead**) to be created automatically.

After configuring these options, click **Save** to apply your changes.


.. _ps3_mondaycrm_integration:

monday and phone.systems™ Integration
#####################################

Connecting **phone.systems™** with **monday** CRM allows you to manage customer calls and track important information. The integration includes the following features:

- **Sync contacts automatically**: Keep contacts updated between phone.systems™ and monday CRM.
- **Call journaling**: Calls are automatically logged in the monday CRM workspace (phone.systems™ board). You can also manually select a different board for journaling.
- **Auto contact creation**: New contacts can be created in the monday CRM workspace when a number doesn’t match an existing contact (for inbound, outbound, or both call directions). You can choose which directions trigger contact creation.
- **Call recording uploads**: Call recordings can be automatically added to the call entry in monday CRM.
- **Flexible synchronization options**: Select a contact board and assign its columns in monday CRM to control how data is synchronized.

----

.. raw:: html

   <br>

Connecting phone.systems™ with monday CRM
=========================================

This guide provides detailed steps on integrating phone.systems™ with monday CRM. Follow the instructions below to complete the setup process.

.. note::
   To connect phone.systems™ with monday, generate the **Client ID**, **Client Secret**, and **Signing Secret** in your monday developer account.

Step 1: Sign in to your monday account
------------------------------------------

To get started, go to the `monday page <https://monday.com>`_ and **Log in** to access an existing account or create a new one.

Step 2: Open monday Developers page and create an app
-----------------------------------------------------

1. Click on your user icon in the top right corner.
2. In the **Account** section, click **Developers**.
3. On the **My Apps** page of the monday Developer Center, click the **Build app** button to create a new app.

.. figure:: https://doc.didww.com/_images/1_build_app.png
   :figclass: align-center
   :alt: Developers Account Section
   :width: 100%

   **Fig. 1.** Developers Account Section

Step 3: Launch phone.systems™ and connect to monday CRM
--------------------------------------------------------

1. In the phone.systems™ interface, click **Settings**.
2. Open the **CRM Integrations** tab at the top of the screen. Alternatively, use this direct link: `phone.systems™ monday CRM Integration <https://phone.systems/ui/index.html#/settings/integrations/monday/new>`_
3. Click **Connect** to link your monday CRM app with phone.systems™.

.. note:: Clicking **Connect** will open the **Connect monday** form to continue the integration setup.

.. figure:: https://doc.didww.com/_images/2_connect_monday_in_phone_systems.png
   :figclass: align-center
   :alt: Connect monday in phone.systems™
   :width: 100%

   **Fig. 3.** Connect monday in phone.systems™

Step 4: Copy app credentials from monday Developer Center and paste them into the phone.systems™
--------------------------------------------------------------------------------------------------

Continue configuring the new app in the monday Developer Center. Navigate to the **General settings** section, click **Show**, and then copy the **Client ID**, **Client Secret**, and **Signing Secret**.

.. figure:: https://doc.didww.com/_images/7_copy_client_credentials.png
   :figclass: align-center
   :alt: Copy Client ID, Client Secret, and Signing Secret

   **Fig. 8.** Copy Client ID, Client Secret, and Signing Secret

Open the `phone.systems™ monday connection form <https://phone.systems/ui/index.html#/settings/integrations/monday/new>`_, and paste the **Client ID**, **Client Secret**, and **Signing Secret** from the monday Developer Center into the corresponding fields.

.. figure:: https://doc.didww.com/_images/7_paste_client_credentials.png
   :figclass: align-center
   :alt: Paste Client ID, Client Secret, and Signing Secret

   **Fig. 9.** Paste Client ID, Client Secret, and Signing Secret

Step 5: Copy the Redirect URL from phone.systems™ and paste it into monday Developer Center
--------------------------------------------------------------------------------------------

Continue in the `phone.systems™ monday CRM connection page <https://phone.systems/ui/index.html#/settings/integrations/monday/new>`_, copy the **Redirect URL**.

.. figure:: https://doc.didww.com/_images/3_copy_redirect_url.png
   :figclass: align-center
   :alt: Copy the Redirect URL
   :width: 100%

   **Fig. 4.** Copy the Redirect URL

Open the app creation page on the `monday Developer Center <https://developer.monday.com>`_ and access your app configuration. Then follow these steps:

1. In the left sidebar, expand the **Build** section.
2. Click on **OAuth & permissions**.
3. Navigate to the **Redirect URLs** tab.
4. Paste the **Redirect URL** in to the corresponding input field.

.. figure:: https://doc.didww.com/_images/4_paste_redirect_url.png
   :figclass: align-center
   :alt: Paste the Redirect URL
   :width: 100%

   **Fig. 5.** Paste the Redirect URL

Step 6: Define app permissions with OAuth scopes
-------------------------------------------------

Continue in the **monday Developers Center** to configure your app permissions.

1. Open the **Scopes** tab in the **OAuth & permissions** section.
2. Locate and enable the following OAuth scopes:

    .. list-table::
       :widths: 20 60
       :header-rows: 1

       * - **OAuth Scope**
         - **Description**
       * - **me:read**
         - Read a user's profile information
       * - **boards:read**
         - Read user's boards data
       * - **boards:write**
         - Modify user's boards data
       * - **users:read**
         - Read the profile information of the users on the account
       * - **account:read**
         - Read general information about the account
       * - **workspaces:read**
         - Read user's workspaces data
       * - **workspaces:write**
         - Modify user's workspaces data
       * - **webhooks:write**
         - Create and modify webhooks
       * - **webhooks:read**
         - Read existing webhooks configuration

3. Once all scopes are selected, click **Save Scopes** at the bottom of the page.

.. figure:: https://doc.didww.com/_images/5_add_oauth_scopes.png
   :figclass: align-center
   :alt: Add required OAuth scopes
   :width: 100%

   **Fig. 6.** Add required OAuth scopes

Step 7: Publish app and authorize connection
---------------------------------------------

1.  In the monday Developer Center, click the **Promote to live** button to publish your app.
2.  Return to phone.systems™ and click **Connect**.
3.  A permission authorization window will appear. Click **Authorize** to approve the integration.

    .. figure:: https://doc.didww.com/_images/8_authorize_connection2.png
       :figclass: align-center
       :alt: Authorize the connection
       :width: 100%

       **Fig. 7.** Authorize the connection

After you click **Authorize**, the CRM status will change to **Synchronizing**, and then to **Connected** once the initial synchronization is complete.

.. important:: After the connection is established, make sure to configure synchronization with your appropriate monday board. You can follow the steps described in :ref:`Synchronizing Contacts <synchronizing_contacts>`.

.. figure:: https://doc.didww.com/_images/9_connected_status.png
   :figclass: align-center
   :alt: Connected status in phone.systems™
   :width: 100%

   **Fig. 8.** Connected status in phone.systems™

----

.. raw:: html

   <br>

.. _synchronizing_contacts:

Synchronizing Contacts
======================

Once the integration is connected, you must configure the synchronization options to map your monday.com board columns to phone.systems™ contact fields.

1.  Navigate to **Settings > CRM Integrations**.
2.  Locate the active monday.com integration and click the three-dots menu icon.
3.  Select **Change synchronization options** from the dropdown menu.

    .. figure:: https://doc.didww.com/_images/10_change_sync_options_button.png
       :figclass: align-center
       :alt: Change synchronization options button.
       :width: 100%

       **Fig. 9.** Synchronization options menu.

4.  In the **Synchronization options** window, assign the columns from your monday.com board to the corresponding fields:

        - **Board:** Select the monday.com board where your contacts are stored.
        - **Name:** Assign the column that contains the contact’s full name.
        - **Phone Numbers:** Assign the column that contains phone numbers.
        - **Emails:** Assign the column that contains email addresses.
        - **Company Name:** Assign the column that contains company names.
        - **Job Title:** Assign the column that contains job titles.
5.  Click **Save** to apply the configuration.

    .. figure:: https://doc.didww.com/_images/10_change_sync_options.png
       :figclass: align-center
       :alt: Change synchronization options window.
       :width: 100%

       **Fig. 10.** Synchronization options window.

----

.. raw:: html

   <br>

Configuring monday CRM Integration Settings
===========================================

Once the integration is active and synchronized, you can customize its behavior. To access these options, navigate to **Settings > CRM Integrations** and click the **Settings** icon next to your monday.com connection.

.. figure:: https://doc.didww.com/_images/11_settings_button.png
   :figclass: align-center
   :alt: monday.com integration settings button.
   :width: 100%

   **Fig. 11.** monday.com integration settings button.

Configuring the Call Journaling Board
-------------------------------------

.. important::
   The call journaling configuration below applies **only** to phone numbers that have **Call journaling** enabled.
   Enable journaling per number in the :ref:`phone numbers <ps3_phone_numbers>` menu.

To configure the board used for call journaling:

1. Navigate to **Settings > CRM Integrations**.
2. Locate your active **monday** integration and click the **Settings** icon.
3. On the integration settings page, click the **Call journaling board should be configured** link to open the configuration screen.

.. figure:: https://doc.didww.com/_images/11_sync_settings.png
   :figclass: align-center
   :alt: monday.com integration settings page (entry point to Call Journaling Board).
   :width: 100%

   **Fig. 12.** Integration settings page.

On this screen, you must configure the **Call Journaling Board**.
At a minimum, map the **Board** and **Contacts** fields.
All other fields are optional but recommended, as they enrich call logs with additional context.

.. list-table::
   :header-rows: 1
   :widths: 25 65

   * - **Field**
     - **Description**
   * - **Board**
     - Select the monday board where calls will be logged (for example, *Calls*).
   * - **Owner**
     - Assigns ownership of the logged call item.
   * - **Contact**
     - Connects the call entry to the **Contacts** column of your main table.
       This mapping is essential to ensure call journaling links to the appropriate contact.
   * - **Status**
     - Maps the status field of the call (e.g., completed, missed).
   * - **Call Direction**
     - Identifies whether the call was inbound or outbound.
   * - **Date Connected**
     - Logs the date when the call was connected.
   * - **Source Number**
     - The originating phone number of the call.
   * - **Destination Number**
     - The called phone number.
   * - **Call Duration**
     - The length of the call in seconds or minutes.
   * - **Call Notes**
     - Free-text notes associated with the call.
   * - **Call Recording**
     - If enabled, attaches the recording link to the logged call entry.

.. figure:: https://doc.didww.com/_images/placeholder_call_journaling_board.png
   :figclass: align-center
   :alt: Call journaling board configuration in monday CRM
   :width: 100%

   **Fig. 13.** Call journaling board configuration in monday CRM.

Auto Contact Creation
---------------------

This feature automatically creates a new item in your selected monday board when a call is handled from a number that does not match an existing contact.

.. list-table::
   :header-rows: 1
   :widths: 20 72

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - Creates a new contact for all inbound calls from numbers not already in your contacts.
   * - **Outbound calls**
     - Creates a new contact for all outbound calls to numbers not already in your contacts.

Other Settings
--------------

These settings control what additional call-related data is automatically uploaded to monday CRM.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Upload call recordings to CRM**
     - When enabled, a link to the call recording will be automatically added to the call log in monday CRM.

       .. note:: To utilize this feature, call recording must be enabled for your :ref:`contact method <ps3_contact_methods>`.

   * - **Upload AI call insights results**
     - When enabled, detailed analytics from our AI engine will be added to the call log. This can include:

       - **Key topics:** A summary of the main topics discussed.
       - **Call summary:** A concise, AI-generated summary of the conversation.
       - **Talk to listen ratio:** A breakdown of how much each party spoke.
       - **Sentiment analysis:** An analysis of the emotional tone of the call.
       - **Transcription:** A full, written transcript of the call.

       .. note:: To utilize the AI features, :ref:`AI Call Insights <ps3_ai_settings_enable>` must be enabled.



.. _ps3_activecampaign_integration:

=============================================
ActiveCampaign and phone.systems™ Integration
=============================================

Connecting **phone.systems™** with **ActiveCampaign CRM** allows you to manage customer calls and synchronize contact data. The integration includes the following features:

- **Sync contacts automatically**: Keep contacts updated between phone.systems™ and ActiveCampaign CRM.
- **Call journaling**: Calls can be logged in ActiveCampaign for tracking and reference.
- **Create new contacts automatically**: When an unknown number calls, a new contact can be created in ActiveCampaign automatically.
- **Upload AI call insights results**: AI-generated call analytics can be added to call logs.

.. note::
   **Call journaling** and **AI call insights** are available only on the **ActiveCampaign Enterprise** plan.

----

.. raw:: html

   <br>

Connecting phone.systems™ with ActiveCampaign
=============================================

This guide provides detailed steps on integrating phone.systems™ with ActiveCampaign. Follow the instructions below to complete the setup process.

.. note::
   To connect phone.systems™ with ActiveCampaign, generate the **API URL** and **API Key** in the ActiveCampaign account **Settings**.

Step 1: Sign in to your ActiveCampaign account
----------------------------------------------

To get started, open the `ActiveCampaign website <https://www.activecampaign.com/>`_ and sign in to your account or create a new one.

Step 2: Open Developer settings in ActiveCampaign
-------------------------------------------------

1. In ActiveCampaign, click **Settings** in the top right corner.
2. From the Settings menu, open the **Developer** section.

.. figure:: https://doc.didww.com/_images/1_open_developer_settings.png
   :figclass: align-center
   :alt: Open Developer settings in ActiveCampaign
   :width: 100%

   **Fig. 1.** Open Developer settings in ActiveCampaign

Step 3: Launch phone.systems™ and connect to ActiveCampaign
-----------------------------------------------------------

1. In the phone.systems™ interface, click **Settings**.
2. Open the **CRM Integrations** tab at the top of the screen. Alternatively, use this direct link: `phone.systems™ CRM Integrations <https://phone.systems/ui/index.html#/settings/crm_integrations>`_
3. Click **Connect** to link your ActiveCampaign with phone.systems™.

.. note:: Clicking **Connect** will open the **Connect ActiveCampaign** form to continue the integration setup.

.. figure:: https://doc.didww.com/_images/2_open_connect_form.png
   :figclass: align-center
   :alt: Open the Connect ActiveCampaign form in phone.systems™
   :width: 100%

   **Fig. 2.** Open the Connect ActiveCampaign form in phone.systems™

Step 4: Copy the API credentials from ActiveCampaign
----------------------------------------------------

On the ActiveCampaign **Developer** page, locate the **API Access** section and copy the following values:

1. Click **Copy API URL** and keep the value for the next step.
2. Click **Copy API Key** and keep this value as well.

.. figure:: https://doc.didww.com/_images/3_copy_api_credentials.png
   :figclass: align-center
   :alt: Copy API URL and API Key in ActiveCampaign
   :width: 100%

   **Fig. 3.** Copy API URL and API Key in ActiveCampaign

Step 5: Paste the API credentials into phone.systems™
-----------------------------------------------------

Return to the **Connect ActiveCampaign** form in phone.systems™ and fill in the following fields:

1. Paste the **API URL** into the **API URL** field.
2. Paste the **API Key** into the **API Key** field.

.. figure:: https://doc.didww.com/_images/4_paste_api_credentials.png
   :figclass: align-center
   :alt: Paste API URL and API Key into phone.systems™
   :width: 100%

   **Fig. 4.** Paste API URL and API Key into phone.systems™

Step 6: Connect the phone.systems™ ActiveCampaign integration
-------------------------------------------------------------

Click **Connect** to complete the integration setup.

.. figure:: https://doc.didww.com/_images/5_connect.png
   :figclass: align-center
   :alt: Connect your ActiveCampaign CRM to phone.systems™
   :width: 100%

   **Fig. 5.** Connect your ActiveCampaign to phone.systems™

After the connection is established, the integration status changes to **Synchronizing**, and then to **Connected** once the initial synchronization is complete.

.. note:: Existing contacts from ActiveCampaign are synchronized automatically during this step.

.. figure:: https://doc.didww.com/_images/6_connected.png
   :figclass: align-center
   :alt: Active ActiveCampaign connection in phone.systems™
   :width: 100%

   **Fig. 6.** Active ActiveCampaign connection in phone.systems™

Step 7: Enable phone-only contacts in ActiveCampaign
----------------------------------------------------

ActiveCampaign requires an email address by default when creating new contacts.
To allow phone.systems™ to create and synchronize contacts using **only a phone
number**, phone-only contacts must be enabled in the ActiveCampaign
advanced settings.

This allows the integration to automatically create or update contacts based on
calls and other phone activity.

.. important:: Enabling phone-only contacts is a **permanent change** and cannot be undone. `Learn more about phone-only contacts <https://help.activecampaign.com/hc/en-us/articles/20773942638364-Phone-only-contacts-overview>`_.

1. Go to the **ActiveCampaign** user interface and open **Settings**.
2. Navigate to **Advanced Settings** and find the **Phone-only contacts** section.
3. Enable the **Phone-only contacts** toggle.
4. Click **Save Settings**.

.. figure:: https://doc.didww.com/_images/9_phoneonly.png
   :figclass: align-center
   :alt: Active ActiveCampaign connection in phone.systems™
   :width: 100%

   **Fig. 7.** Active ActiveCampaign connection in phone.systems™

----

.. raw:: html

   <br>

Associate users for ActiveCampaign
==================================

After the ActiveCampaign integration is successfully connected, you can associate
ActiveCampaign users with their corresponding **phone.systems™** users.

User association enables call journaling by ensuring that inbound and outbound
calls are logged on the correct contacts in ActiveCampaign. Only calls handled by
associated users are recorded. Calls handled by users who are not associated are
not journaled.

.. note::
   Call journaling for ActiveCampaign is available **only** on the **ActiveCampaign Enterprise** plan.

1. Go to phone.systems™ **Settings**, then open **CRM Integrations**.
2. Under **Active Integrations** at the top of the page, you will see **ActiveCampaign** marked as **Connected**.
3. Click **Associate users**.

.. figure:: https://doc.didww.com/_images/7_associate1.png
   :figclass: align-center
   :alt: Associate users button for ActiveCampaign integration
   :width: 100%

   **Fig. 8.** Associate users button for ActiveCampaign integration

After clicking **Associate users**, a dialog opens where you can link
**ActiveCampaign users** with corresponding **phone.systems™ users**.

4. Match each ActiveCampaign user with the appropriate phone.systems™ user.
5. Click **Save** to apply the changes.

.. figure:: https://doc.didww.com/_images/8_associate2.png
   :figclass: align-center
   :alt: Associate ActiveCampaign users with phone.systems™ users
   :width: 100%

   **Fig. 9.** Associate ActiveCampaign users with phone.systems™ users

----

.. raw:: html

   <br>

Configuring ActiveCampaign Integration Settings
===============================================

After the ActiveCampaign integration is connected, you can configure how calls
and contacts are synchronized between **phone.systems™** and ActiveCampaign.

These settings control call journaling behavior, automatic contact creation,
and the upload of additional call-related data. Configuration applies only to
phone numbers with call journaling enabled.

1. In phone.systems™ go to **Settings**, then open **CRM Integrations**.
2. Under **Active Integrations** at the top of the page, you will see **ActiveCampaign** marked as **Connected**.
3. Click **Settings**.

.. figure:: https://doc.didww.com/_images/10_settings_button.png
   :figclass: align-center
   :alt: ActiveCampaign integration settings button
   :width: 100%

   **Fig. 10.** ActiveCampaign integration settings button

After clicking **Settings**, a dialog opens where you can link
**ActiveCampaign users** with corresponding **phone.systems™ users**.

.. figure:: https://doc.didww.com/_images/11_settings_menu.png
   :figclass: align-center
   :alt: ActiveCampaign integration settings menu
   :width: 100%

   **Fig. 11.** ActiveCampaign integration settings menu

Call journaling
---------------

.. important::
   - Call journaling is available only on the **ActiveCampaign Enterprise** plan.
   - Each phone number must be configured individually for call journaling.
   - :ref:`Auto Contact Creation <ps3_activecampaign_integration_auto_contact_creation>` and :ref:`Other Settings <ps3_activecampaign_integration_other_settings>` apply only for numbers with **enabled** call journaling.

Call journaling automatically logs inbound and outbound calls as activities on related contacts in ActiveCampaign.

Enable call journaling for each required number in the :ref:`phone numbers <ps3_phone_numbers>` menu.

.. _ps3_activecampaign_integration_auto_contact_creation:

Auto contact creation
---------------------

This feature automatically creates a new contact when a call is handled from a number that does not match an existing contact.

.. list-table::
   :header-rows: 1
   :widths: 20 72

   * - **Setting**
     - **Description**
   * - **Inbound calls**
     - Create a contact for inbound calls from unknown numbers.
   * - **Outbound calls**
     - Create a contact for outbound calls to unknown numbers.

.. important::
   - ActiveCampaign does not notify phone.systems™ when a contact is deleted.
   - Contacts that still exist in ActiveCampaign cannot be deleted from phone.systems™. To remove a contact from phone.systems™, delete it in ActiveCampaign first.

.. _ps3_activecampaign_integration_other_settings:

Other settings
--------------

These settings control what additional call-related data is automatically uploaded to ActiveCampaign.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - **Setting**
     - **Description**
   * - **Upload AI call insights results**
     - When enabled, detailed analytics from our AI engine will be added to the call log. This can include:

       - **Key topics:** A summary of the main topics discussed.
       - **Call summary:** A concise, AI-generated summary of the conversation.
       - **Talk to listen ratio:** A breakdown of how much each party spoke.
       - **Sentiment analysis:** An analysis of the emotional tone of the call.
       - **Transcription:** A full, written transcript of the call.

.. important::
   - **AI Call Insights** are available only on the **ActiveCampaign Enterprise** plan.
   - To utilize the AI features, :ref:`AI Call Insights <ps3_ai_settings_enable>` must be enabled.


.. _ps3_domains:

Domains
=====================

The **Domains** settings in phone.systems™ allow users to validate entire email domains. This feature eliminates the need to send separate confirmation emails for each contact method email, streamlining the management of multiple emails under the same domain.

Once an email domain is validated, any email address from that domain is automatically marked as verified when created.

**Benefits:**

* **Single Domain Validation:** Validate an entire domain to avoid sending individual confirmation emails.

* **Multiple Domain Validation:** Validate multiple domains for added flexibility.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Domains

To add your **Domain**, input the domain into the **Add new domain** field and click **Verify**.

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 2.** Add new domain

Once you add the domain, a TXT record will be generated for your domain verification. To verify the domain follow these instructions below:

* Copy the generated code

* Create a TXT record with copied code in DNS settings of your domain provider

* Click on **Verify** button to confirm.

.. note:: DNS updates may take some time.

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center
  :figwidth: 45%

  **Fig. 3.** Pending Domain

Once you verify your domain, it will be seen in the **Verified Domains** list.

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 4.** Verified Domain

When you verify a domain in the **Contact Methods** section, all email addresses associated with that domain are automatically marked as verified upon creation.

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 5.** Verified Contact Methods



.. _ps3_settings_feature_codes:

=============
Feature Codes
=============

Feature codes in phone.systems™ allows users to perform actions such as call transfers, call pickup, and call recording quickly using the phone’s keypad.

Feature codes are accessed by navigating to the **Settings** menu on the **Feature codes** tab.

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Feature Codes

----

Attended DTMF Transfer
^^^^^^^^^^^^^^^^^^^^^^

**Attended DTMF Transfer** - Attended (or warm) transfers occur when an
active call is put on hold, and another call is initiated via an
Internal Number to a third-party end destination. That third-party will
then confirm whether or not they will accept the call. Accordingly, the
call may then be transferred, or the transfer action may be cancelled.

This feature code is supported by the **App Configuration**, **SIP Account**,
and **SIP Forwarding** contact methods.

These transfers are achieved by pressing the configured **\*Attended
DTMF Transfer** code on the phone keypad, or by using the transfer
(xfer) button if available on an IP or soft phone. Detailed steps for
attended DTMF transfers are as follows:

-  Answer the incoming call, enter the **\*Attended DTMF Transfer**
   feature code on the dial pad, and the call will automatically be put
   on hold. Enter the required Internal Number (extension) when
   prompted, followed by the hash (#) key. Once this call has been
   answered and you have spoken with the person to whom the call is to
   be transferred, simply hang up and the call will automatically be
   connected between the original caller and the new participant.

-  To cancel an already initiated attended transfer, once again enter
   the same **\*Attended DTMF Transfer** feature code. You will be
   reconnected to the original caller.

-  Alternatively if a transfer (xfer) button is available on the phone
   device or softphone, answer the incoming call, put that call on hold,
   call the required Internal Number (extension) on a second line, speak
   with the person to whom the call is to be transferred, press the
   transfer button, and the call will be immediately transferred. Note
   that the call may have to be manually disconnected from the first
   line if your device does not do this automatically.

----

Unattended DTMF Transfer
^^^^^^^^^^^^^^^^^^^^^^^^

**Unattended DTMF Transfer** - Unattended (or blind) transfers are used
if the call should be transferred without first speaking with the person
to whom the call will be forwarded. These transfers are achieved by
pressing the configured **\*Unattended DTMF Transfer** on the phone
keypad, or by using the transfer (xfer) button if available on an IP or
soft phone. Detailed steps for unattended DTMF transfers are as follows:

This feature code is supported by the **App Configuration**, **SIP Account**,
and **SIP Forwarding** contact methods.

-  If a transfer button is not available on the device, answer the
   incoming call, enter the **\*Unattended DTMF Transfer** feature code
   on the dial pad, and the call will automatically be put on hold.
   Enter the Internal Number (extension) when prompted followed by the
   hash (#) key, and the call will then be transferred to the new
   participant. Note that initiated unattended transfers can not be
   cancelled.

-  If a transfer (xfer) button is available on the device, answer the
   incoming call, press the transfer button, enter the required Internal
   Number (extension), and the call will be immediately transferred.

----

.. _ps3_feature_code_call_pickup:

Call Pickup
^^^^^^^^^^^

**Call Pickup** - Call pickup is used when an incoming call rings on one
of the SIP Accounts configured for phone.systems™, but another person
would like to answer this call on their device.

This feature code is supported by the **App Configuration**, **SIP Account**,
and **SIP Forwarding** contact methods.

There are several ways to use this feature:

-  To pick up an incoming call at any extension number, enter the **\*Call
   Pickup** feature code.

-  To pick up an incoming call at a specific Internal Number
   (extension), enter the **\*Call Pickup** feature code followed by an
   Internal Number.

-  To pick up a call received on a specific phone number or partial
   number, enter the **\*Call Pickup** feature code followed by that
   phone number (full or partial). Note that because this feature code
   supports the entry of partial phone numbers, call pickup may be
   enabled for multiple devices that match the provided input.

----

Record on demand
^^^^^^^^^^^^^^^^

**Record on demand** allows users to initiate the recording of calls in real
time. To use this feature code, the contact method must have the **Record on
demand** option enabled in the **Call Recording** settings, together with a
configured delivery method for receiving the contents of the recorded call.

This feature code is supported by the **App Configuration**, **SIP Account**,
and **SIP Forwarding** contact methods.

.. note:: When using this feature code to enable call recording, a sound effect is played to the initiator to indicate that the code has been accepted and call is being recorded.


.. _ps3_technical_information:

=====================
Technical Information
=====================

Supported Codecs
^^^^^^^^^^^^^^^^

-  OPUS/48000/2

-  G722/8000

-  PCMU/8000

-  PCMA/8000

-  G729/8000

-  GSM/8000

-  telephone-event (for DTMF transport)

----

IP addresses and RTP ports
^^^^^^^^^^^^^^^^^^^^^^^^^^

-  46.19.208.0/21 (46.19.208.0 - 46.19.215.254) - for incoming and outgoing traffic.
-  46.19.210.69 - for sending :ref:`deliveries <ps3_delivery_methods>`.

-  RTP port range - 16384-32767

----

DTMF Transport Methods
^^^^^^^^^^^^^^^^^^^^^^

DTMF signaling is supported as follows:

* Telephone-event: `RFC2833 <https://tools.ietf.org/html/rfc2833>`_
* SIP INFO: `draft-kaplan-dispatch-info-dtmf-package-00 <https://tools.ietf.org/html/draft-kaplan-dispatch-info-dtmf-package-00>`_

   * application/dtmf-relay
   * application/dtmf

.. note:: By default, RFC 2833 is enabled.

----

Protocols
^^^^^^^^^

-  SIP over UDP (User Datagram Protocol)

-  SIP over TCP (Transmission Control Protocol)

-  t.38 for fax transmission (to email)

-  SIP over TLS (Transport Layer Security)

-  SIP over WSS (WebSocket Secure)

----

Audio file formats
^^^^^^^^^^^^^^^^^^

Supported audio files for uploading to Audio Files (file size is
limited to 14 MB)

-  .mp3

-  .m4a

-  .wav

-  .flac

-  .ogg

----

Call Recording File Specifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  File format .mp3

-  Bit rate 16 kbps

-  Sample rate 8 kHZ

----

Time Zone
^^^^^^^^^

phone.systems™ is using UTC offsets and daylight-saving rules issued by
IANA

-  IANA Time Zone database - https://www.iana.org/time-zones
   (https://en.wikipedia.org/wiki/Tz_database)

-  Default timezone is GMT (+0)



.. _ps3_subscription_details:

.. |br| raw:: html

   <br />

Subscription Details
=============================

Subscription details page displays your phone.systems™ total seats and your usage summary.

Each phone.systems™ seat entitles you to the following:

|inline_user| 1 :ref:`User <ps3_users>` |br|
A unique user seat with access to phone.systems mobile app on unlimited number of devices.

|inline_check| 1 :ref:`SIP Account Contact Method <ps3_sip_accounts>` |br|
A dedicated SIP account for connecting your devices to the phone system.

|inline_check| 1 :ref:`SIP Forwarding Contact Method <ps3_sip_forwarding>` |br|
Forwarding of incoming calls to a specific SIP URI address.

|inline_check| 1 :ref:`PSTN Routes Contact Method <ps3_pstn_routes>` |br|
Forwarding of incoming calls to any standard phone network number (PSTN).

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Subscription Details

To manage your existing phone.systems™ seats plan, click on `manage your subscription <https://my.didww.com/#/phone_systems>`_.

.. |inline_user| image:: ../assets/img/guide-v2/subscription_details/inline_user.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |inline_check| image:: ../assets/img/guide-v2/subscription_details/inline_check.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_app_index:

phone.systems™ App
========================

The **phone.systems™** app is a SIP-based softphone for **MacOS, iOS, Android, Windows, and Linux** operating systems. It provides a secure and efficient way to communicate with team members and external contacts.

Designed for seamless VoIP connectivity, the app supports crystal-clear HD audio, real-time call management, and an intuitive interface that adapts to all major platforms. Whether working from the office, remotely, or on the go, users can rely on **phone.systems™** for reliable voice communications.

Key features include:

    - **Cross-platform compatibility** with a unified user experience across all supported devices.
    - **Native integration with the phone.systems™ cloud PBX**, allowing users to quickly make configuration adjustments on the go.
    - **Advanced call functionality**, such as call transfer, hold, mute.
    - **Attachments**, such as call recording, voicemails, fax, and AI call insights.
    - **CRM integrations**, streamlining workflows by connecting calls and contact data with customer relationship management platforms.
    - **Encrypted SIP signaling and media (SRTP/TLS)** to ensure secure communications.
    - **Contact and call history synchronization**, making it easy to manage communications from any device.
    - **Lost calls tracking**, enabling users to monitor missed communications and follow up efficiently.
    - **Push notification support** on mobile platforms for low power consumption and instant call alerts.

.. raw:: html

   <h2 id="download_ps_app">
       Download and install the phone.systems™ app for your platform
       <a class="headerlink" href="#download_phone_systems_app" title="Link to this heading">#</a>
   </h2>

.. container:: download-container3

    .. figure:: https://doc.didww.com/_images/Download_on_the_App_Store_Badge.png
       :alt: Phone Systems iOS App
       :target: https://apps.apple.com/lt/app/phone-systems/id6474605024
       :class: download-button no-shadow fixed-size-img no-lightbox2

    .. figure:: https://doc.didww.com/_images/Google_Play_Store_badge.png
       :alt: Phone Systems Android App
       :target: https://play.google.com/store/apps/details?id=systems.phone.mobile
       :class: download-button no-shadow fixed-size-img-google no-lightbox2

    .. figure:: https://doc.didww.com/_images/microsoft-new-badge-light.png
       :alt: Phone Systems Microsoft App
       :target: https://apps.microsoft.com/detail/9nsqkhxv12bg
       :class: download-button no-shadow fixed-size-img-microsoft microsoft-button no-lightbox2

    .. figure:: https://doc.didww.com/_images/BadgeLinux.png
       :alt: Phone Systems Linux App
       :target: https://doc.didww.com/phone-systems/app/additional-resources/repositories.html
       :class: download-button no-shadow fixed-size-img-linux no-lightbox2

----

.. grid:: 1 1 3 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **App Configuration**
      :link: configuration
      :link-type: doc
      :text-align: left

      Set up the phone.systems™ application to make and receive calls.

   .. grid-item-card:: **Dial Pad**
      :link: dialpad
      :link-type: doc
      :text-align: left

      Access and use the built-in dial pad for making calls directly from the app.

   .. grid-item-card:: **Contacts**
      :link: contacts
      :link-type: doc
      :text-align: left

      Manage your contacts and easily initiate calls or messages.

   .. grid-item-card:: **Call History**
      :link: call-history
      :link-type: doc
      :text-align: left

      View and track your call history, including missed, received, and dialed calls.

   .. grid-item-card:: **Settings**
      :link: settings
      :link-type: doc
      :text-align: left

      Adjust app settings such as notifications, audio preferences, and more.

   .. grid-item-card:: **Additional Resources**
      :link: additional-resources/index
      :link-type: doc
      :text-align: left

      Access documentation, FAQs, and additional guides to help you maximize app usage.

.. toctree::
  :maxdepth: 1
  :hidden:

  App Configuration <configuration.rst>
  Dial Pad <dialpad.rst>
  Contacts <contacts.rst>
  Call History <call-history.rst>
  Settings <settings.rst>
  Additional Resources <additional-resources/index.rst>

.. |call-analytics| image:: /img/phone_systems/icons/icons-sidebar-call-analytics.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |contact-methods| image:: /img/phone_systems/icons/icons-sidebar-contact-methods.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |default| image:: /img/phone_systems/icons/icons-sidebar-default.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |delivery-methods| image:: /img/phone_systems/icons/icons-sidebar-delivery-methods.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |phone-numbers| image:: /img/phone_systems/icons/icons-sidebar-phone-numbers.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |settings| image:: /img/phone_systems/icons/icons-sidebar-settings.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |time-schedules| image:: /img/phone_systems/icons/icons-sidebar-time-schedules.svg
   :class: no-border inline-img no-shadow
   :width: 19px
   :height: 19px

.. |trunks| image:: /img/phone_systems/icons/icons-sidebar-trunks_v2.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |users| image:: /img/phone_systems/icons/icons-sidebar-users.svg
   :class: inline-img no-shadow no-border
   :width: 19px
   :height: 19px

.. |contacts| image:: /img/phone_systems/icons/icons-sidebar-contacts.svg
   :class: no-border inline-img no-shadow
   :width: 19px
   :height: 19px

.. raw:: html

    <style>
        .docutils.container.download-container3 {
            display: inline-grid;
            grid-template-columns: repeat(2, max-content);
            column-gap: 15px;
            row-gap: 10px;
            justify-content: start;
            justify-items: start;
            align-items: center;
            width: auto !important;
            max-width: 100% !important;
            margin: 0 !important;
            padding: 0 !important;
        }

        .docutils.container.download-container3 > figure,
        .docutils.container.download-container3 > * {
            margin: 0 !important;
            max-width: none !important;
        }

        .download-container3 .download-button {
            width: 220px !important;
            display: block;
            text-align: left;
        }

        .download-container3 .download-button img {
            width: 100% !important;
            height: auto;
            display: block;
            box-shadow: none !important;
        }

        .download-container3 .microsoft-button img {
            height: 54px !important;
            object-fit: contain;
        }

        @media (max-width: 600px) {
            .docutils.container.download-container3 {
                display: grid;
                grid-template-columns: 1fr;
                width: 100% !important;
            }

            .download-container3 .download-button {
                width: min(220px, 100%) !important;
            }
        }
    </style>

.. raw:: html

    <script>
        document.addEventListener("DOMContentLoaded", function() {

            // Redirects users when clicking a figure with .align-default instead of opening Lightbox

            document.querySelectorAll("figure.align-default").forEach(function(figure) {
                let anchor = figure.querySelector("a.reference.external.image-reference"); // Find the anchor inside each figure

                if (anchor) {
                    let targetUrl = anchor.getAttribute("href"); // Get the href value

                    // Prevent default behavior and redirect user to the link on click
                    figure.addEventListener("click", function(event) {
                        event.preventDefault(); // Stop Lightbox, prevent default image opening
                        window.location.href = targetUrl; // Redirect user
                    });

                    // Ensure cursor changes to pointer when hovering over the figure
                    figure.style.cursor = "pointer";

                    // Show the href in the status bar on hover
                    figure.addEventListener("mouseenter", function() {
                        figure.setAttribute("title", targetUrl); // Display href when hovering
                    });
                }
            });

            // Disables Lightbox functionality for images with .no-lightbox2 class
            document.querySelectorAll(".no-lightbox2").forEach(function(img) {
                let parentAnchor = img.closest("a");
                if (parentAnchor) {
                    let targetUrl = parentAnchor.getAttribute("href"); // Get the :target: URL

                    // Disable Lightbox2 opening
                    parentAnchor.setAttribute("data-lightbox-disabled", "true");

                    parentAnchor.onclick = function(event) {
                        event.preventDefault(); // Prevent default Lightbox behavior
                        window.location.href = targetUrl; // Redirect immediately
                    };
                }
            });

            // Removes Lightbox overlay and container from the DOM if .no-lightbox2 elements exist
            setTimeout(function() {
                if (document.querySelector(".no-lightbox2")) {
                    let lightboxOverlay = document.getElementById("lightboxOverlay");
                    let lightbox = document.getElementById("lightbox");

                    if (lightboxOverlay) lightboxOverlay.remove();
                    if (lightbox) lightbox.remove();
                }
            }, 500); // Removes Lightbox quickly after the page loads

        });
    </script>

    <style>
        /* Prevent Lightbox from displaying for .no-lightbox2 */
        .no-lightbox2 {
            cursor: pointer !important; /* Show hand cursor on hover */
        }

        /* Ensure Lightbox overlay and container are hidden */
        #lightboxOverlay, #lightbox {
            display: none !important;
            visibility: hidden !important;
            opacity: 0 !important;
        }

        /* Ensure figures behave like clickable links */
        figure.align-default {
            cursor: pointer !important; /* Ensures hand cursor on hover */
        }

        /* Ensure anchor tags display properly */
        figure.align-default a {
            text-decoration: none !important;
        }
    </style>

    <script>
        document.addEventListener("DOMContentLoaded", function() {
            document.querySelectorAll("figure.align-default").forEach(function(figure) {
                let mainAnchor = figure.querySelector("a.reference.external.image-reference"); // Outer anchor with correct href
                let imageAnchor = figure.querySelector("a[data-lightbox]"); // Inner anchor with incorrect href

                if (mainAnchor && imageAnchor) {
                    let targetUrl = mainAnchor.getAttribute("href"); // Get the correct URL

                    // Replace the inner anchor's href with the correct one
                    imageAnchor.setAttribute("href", targetUrl);

                    // Prevent Lightbox from opening
                    imageAnchor.removeAttribute("data-lightbox");

                    // Redirect on click
                    figure.addEventListener("click", function(event) {
                        event.preventDefault();
                        window.location.href = targetUrl;
                    });

                    // Ensure pointer cursor on hover
                    figure.style.cursor = "pointer";
                }
            });
        });
    </script>

.. Hide the SVG external link icon after the extension was added this icon is added by default and it is not needed for this page

.. raw:: html

   <style>
     svg[aria-hidden="true"] {
       display: none !important;
     }
   </style>


.. _ps3_appplication_configurations:

.. |br| raw:: html

   <br />

================================
phone.systems™ App Configuration
================================

The phone.systems™ mobile application connects a user account to an application
line within the platform.

This configuration provides the user with a dedicated calling setup and
controls how inbound and outbound calls are routed, how caller ID is presented,
and whether calls are recorded.

----

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Configure User & Application Line**
      :link: ps3_configure_app_device_user
      :link-type: ref
      :text-align: center

      Create or configure a user and assign an application line.

   .. grid-item-card:: **Install & Activate the App**
      :link: ps3_setup_phone_systems_app
      :link-type: ref
      :text-align: center

      Activate the mobile application and complete the user setup process.

----

.. _ps3_configure_app_device_user:

Configure User and Application Line in phone.systems™
=====================================================

Before a user can make or receive calls through the phone.systems™
application, their account must be connected to a user with enabled application line.
This setup links the user to a dedicated application line and ensures that
calls are routed and handled according to the assigned configuration.

Select one of the options below depending on whether you are setting up a new
user or configuring an existing one.

|br|

Before You Begin
----------------

Before configuring phone.systems™ app, ensure the required calling components are available. These elements enable inbound connectivity and voice routing for the user.

    - **A DID number** – Required to enable inbound calling functionality. If not available, .
    - **An assigned phone.systems™ trunk** – Needed to establish voice connectivity for the user. For setup steps, see :ref:`Configure DID Numbers with phone.systems™ in the DIDWW User Panel <ps3_prerequisites>`.

|br|

.. tab-set::
   :class: my-tabs
   :sync-group: app-device-user

   .. tab-item:: *Configure App for New Users*
      :sync: new-users

      Each user must have a distinct profile and a dedicated application line (App Configuration Contact Method) to facilitate call routing, identity assignment, and access to calling features within the phone.systems™ application. This ensures accurate association of internal numbers, caller ID, and recording policies for both inbound and outbound communications.

      .. raw:: html

         <h3 id="create-new-user-app">
             Step 1: Create a New User
             <a class="headerlink" href="?appconfig=new-users#create-new-user-app" title="Link to this heading">¶</a>
         </h3>

      1. Go to the **Users** menu.
      2. Click the **+** button.

         .. figure:: https://doc.didww.com/_images/fig40.png
            :figclass: align-center
            :width: 80%
            :alt: Add User

            **Fig. 1.** Add new user

      3. Fill in the **User Details** in the Create User form:

         - **First name:**  The user’s name.
         - **Last name:** The user’s surname.
         - **Department (optional):** The department the user belongs to.
         - **Job title (optional):** The user’s job position.
         - **Time Schedule (optional):** The user's working hours. Read more in :ref:`Time Schedules Documentation <ps3_time_schedules>`.
         - **Email:** The user's email address for communication.

         .. figure:: https://doc.didww.com/_images/create_new_user.png
            :figclass: align-center
            :width: 30%
            :alt: User Details

            **Fig. 2.** User details form

      4. Enable **Configure application line in the next step** and click **Next**.

         .. figure:: https://doc.didww.com/_images/fig42.png
            :figclass: align-center
            :width: 30%
            :alt: Configure Application Line

            **Fig. 3.** Enable application configuration

   .. tab-item:: *Configure App for Existing Users*
      :sync: existing-users

      Existing users may have App Configuration Contact Methods already created but not configured. Finalizing this setup allows the user to place and receive calls through the phone.systems™ application.

      .. raw:: html

         <h3 id="configure-existing-user-app">
             Step 1: Invite and Configure an Existing User
             <a class="headerlink" href="?appconfig=existing-users#configure-existing-user-app" title="Link to this heading">¶</a>
         </h3>

      1. Go to the **Users** menu in the phone.systems™ dashboard.
      2. In the Users tab, locate the user from the list.
      3. Click the **Actions** button next to the user’s name.
      4. Select **Send Invite to App** or **Resend Invite to App**, depending on the user’s current status.
      5. Go to the **Contact Methods** menu and open the **App Configurations** tab.
      6. Click the **Actions** button next to the contact method and select **Edit** to configure the application line.

      .. note::
            If the **Send Invite to App** button is inactive, ensure the user has a valid **email address** under their contact information to enable this option.

      .. figure:: https://doc.didww.com/_images/fig0.png
         :figclass: align-center
         :width: 80%
         :alt: Edit App Configuration

         **Fig. 4.** Edit application configuration

.. raw:: html

   <h3 id="configure-app-contact-method">
       Step 2: Configure the App Configuration Contact Method
       <a class="headerlink" href="#configure-app-contact-method" title="Link to this heading">¶</a>
   </h3>

Set up how calls are handled for the user, then click **Save**.

.. note::

   An invitation is sent automatically if the user has a valid email address.

The user can then activate the phone.systems™ application.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Inbound Calls*

      .. list-table::
         :widths: 20 90
         :header-rows: 0

         * - **DID Numbers**
           - Select one or more DID numbers to receive inbound calls.

             .. note::
                If no DID numbers are available, refer to :ref:`Configure DID Number with phone.systems™ <ps3_prerequisites>` or :ref:`Add Third Party Phone Numbers <ps3_add_3rd_party_phone_numbers>`.
         * - **Internal Number**
           - Select one or more internal numbers to receive inbound calls.

             .. note::
                If no internal numbers are available, refer to :ref:`Create Internal Numbers Documentation <ps3_create_internal_numbers>`.
         * - **When Unavailable**
           - Specify the forwarding behavior when the destination is unavailable.

         * - **Voicemail Audio**
           - Select the voicemail email when the **Route to Voicemail** option is selected for unavailable calls.

             .. note::
                To configure voicemail audio files, refer to :ref:`Audio Files Documentation <ps3_audio_files>`.

   .. tab-item:: *Outbound Calls*

      .. list-table::
         :widths: 30 70
         :header-rows: 0

         * - **Enable External Outbound Calls**
           - Specifies whether the user can make external outbound calls.
         * - **Caller IDs**
           - Specifies one or multiple caller IDs used for outbound calls.

             .. note::
                Caller ID options appear only if external outbound calls are enabled.
         * - **Internal Caller ID**
           - Specifies the caller ID used for internal outbound calls.

             .. note::
                If no internal numbers are available, refer to :ref:`Create Internal Numbers Documentation <ps3_create_internal_numbers>`.
         * - **Internal Announcement**
           - Select the audio announcement message for internal calls.

             .. note::
                To upload announcement audio files, refer to :ref:`Audio Files Documentation <ps3_audio_files>`.
         * - **External Announcement**
           - Select the audio announcement message for external calls.

   .. tab-item:: *Call Recording*

      .. list-table::
         :widths: 35 65
         :header-rows: 0

         * - **Delivery Methods**
           - Specifies the delivery methods for call recordings.

             .. note::
                For setup instructions, refer to :ref:`Delivery Methods Documentation <ps3_delivery_methods>`.
         * - **Inbound Internal**
           - Toggle to enable inbound internal call recording.
         * - **Inbound External**
           - Toggle to enable inbound external call recording.
         * - **Outbound Internal**
           - Toggle to enable outbound internal call recording.
         * - **Outbound External**
           - Toggle to enable outbound external call recording.
         * - **Record On Demand**
           - If enabled, users can initiate recording with a feature code.

             .. note::
                To configure on-demand recording, define a :ref:`feature code <ps3_settings_feature_codes>`.

----

.. _ps3_setup_phone_systems_app:

Install and Activate the phone.systems™ App
===========================================

After a user account and their application line have been configured in
phone.systems™, the system automatically sends an invitation email to the
user’s registered email address.
This email allows the user to install the phone.systems™ mobile application
and securely connect it to their assigned application line.

The invitation email includes:

- A download link for the application
- Activation details (QR code and authentication code)

The user should follow the instructions in the email to complete the setup on
their device.

.. note::
   If the invitation email does not arrive, check the email spam or junk folder or
   contact your administrator to resend it.

.. figure:: https://doc.didww.com/_images/activation_email.png
   :figclass: align-center
   :width: 30%
   :alt: phone.systems invitation email

   **Fig. 8.** Invitation email

Step 1: Open the Application
----------------------------

To begin activation, open the phone.systems™ application on the user’s device.
Install it first if it is not already installed.

Tap **Sign in** to begin activation.

.. figure:: https://doc.didww.com/_images/sign_in.png
   :figclass: align-center
   :width: 30%
   :alt: Sign In Screen

   **Fig. 9.** Sign-in screen

Step 2: Activate the Application
--------------------------------

Activate the application using one of the following methods provided in the invitation email.

When activating using a QR code, the application may request camera access to scan the code.

.. note:: When activating using a QR code, the application may request camera access to scan the code.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Scan QR Code*

      1. Allow camera access when prompted.
      2. Scan the QR code from the invitation email.

      .. figure:: https://doc.didww.com/_images/qr_scan.png
         :figclass: align-center
         :width: 30%
         :alt: QR code activation

         **Fig. 10.** QR code activation

   .. tab-item:: *Enter Code Manually*

      If camera access is denied or unavailable, activate the application using the authentication code from the invitation email.

      1. Tap **Enter code manually** on the QR scanning screen.
      2. Copy the authentication code from the invitation email.
      3. Paste the code into the **Enter authentication code** field.
      4. Tap **Continue** to proceed.

      .. grid:: 1 1 1 2
         :gutter: 3

         .. grid-item::

            .. figure:: https://doc.didww.com/_images/manual_code.png
               :width: 100%
               :figclass: align-center
               :alt: Camera permission denied screen

               **Fig. 11.** Camera permission denied screen

         .. grid-item::

            .. figure:: https://doc.didww.com/_images/enter_code.png
               :width: 100%
               :figclass: align-center
               :alt: Enter authentication code screen

               **Fig. 12.** Enter authentication code screen

Step 3: Grant Required Permissions
----------------------------------

After activation, the **Welcome to phone.systems™** screen is displayed. Tap
**Continue** to proceed.

On the next screen, tap **Setup permissions** to allow the required device
permissions for calling.

Allow the following permissions:

- **Microphone access** – Required to make and receive calls.
- **Push notifications** – Required to receive incoming call alerts and notifications.

.. note::
   - If microphone or push notification permissions are denied, the application may not be able to place or receive calls properly. Permissions can be modified later in the device system settings.
   - On **iPhone**, **Focus** mode may silence calls and notifications. If you are
     not receiving incoming call alerts, make sure Focus mode is disabled or
     that phone.systems™ is allowed in your Focus settings.

     See Apple’s documentation:
     `Set up a Focus on iPhone <https://support.apple.com/guide/iphone/set-up-a-focus-iphd6288a67f/ios>`_
     and
     `Allow or silence notifications for a Focus <https://support.apple.com/guide/iphone/allow-or-silence-notifications-for-a-focus-iph21d43af5b/ios>`_.

.. grid:: 1 1 1 2
   :gutter: 3

   .. grid-item::

      .. figure:: https://doc.didww.com/_images/continue.png
         :width: 100%
         :figclass: align-center
         :alt: Welcome screen with Continue button

         **Fig. 13.** Welcome screen

   .. grid-item::

      .. figure:: https://doc.didww.com/_images/setup_permissions.png
         :width: 100%
         :figclass: align-center
         :alt: Setup permissions screen

         **Fig. 14.** Permissions setup screen

Step 4: Confirm Personal Information and Complete the Setup
-----------------------------------------------------------

After granting the required permissions, you will be prompted to review and confirm your profile information.

1. Enter or verify your profile details, such as your name, job title, and department.
2. Tap **Save and continue** to complete the setup.

The phone.systems™ application is now activated and ready to make and receive calls according to the assigned App Configuration settings.

.. figure:: https://doc.didww.com/_images/personal_information.png
   :figclass: align-center
   :width: 30%
   :alt: Personal Information

   **Fig. 15.** Personal information

.. _ps3_application_dialpad:

.. |br| raw:: html

   <br />

===========================
phone.systems™ App Dial Pad
===========================

The **Dial Pad** interface in the **phone.systems™** app lets users manually enter phone numbers to make outbound calls. It features a numeric keypad, a status indicator, an outbound caller ID associated with your account, and a call button for easy navigation and communication.

.. figure:: https://doc.didww.com/_images/fig8.png
   :figclass: align-center
   :width: 30%
   :alt: Dial Pad Interface

   **Fig. 1.** Dial Pad Interface

----

.. raw:: html

    <br>

Placing a Call
--------------

To place a call to an unknown number:

    1. Enter the recipient's phone number or internal number.
    2. Click the |call| icon to initiate the call.

.. figure:: https://doc.didww.com/_images/fig28.png
   :figclass: align-center
   :width: 30%
   :alt: Calling An Unknown Number

   **Fig. 2.** Calling An Unknown Number

To call a contact:

    1. Enter at least one digit to search for the number in your contacts list.
    2. Click the |call-button| next to the desired contact.

Alternatively, go to the :ref:`contacts menu <ps3_application_contacts>` and select a contact.

.. figure:: https://doc.didww.com/_images/fig29.png
   :figclass: align-center
   :width: 30%
   :alt: Calling A Contact

   **Fig. 3.** Calling A Contact

When the call starts, you'll see the **In-Call** screen.

.. figure:: https://doc.didww.com/_images/fig30.png
   :figclass: align-center
   :width: 30%
   :alt: In Call Screen

   **Fig. 4.** In Call Screen

Call Ended Screen
^^^^^^^^^^^^^^^^^

After a call ends, the app displays a **Call Ended** screen with quick actions and the call status. This screen appears after an outbound call ends.

The screen closes automatically after **5 seconds**, or immediately after you select an action. You can also close it manually using the **X** button.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Unknown Contact*

      The following actions are available when the call participant is not saved in your contacts:

      - **Create contact** – Add the number as a new contact.
      - **Call again** – Redial the same number.

      .. figure:: https://doc.didww.com/_images/call_ended_unknown.png
         :figclass: align-center
         :width: 30%
         :alt: Call ended screen for unknown contact

         **Fig. 5.** Call Ended Screen (Unknown Contact)

   .. tab-item:: *Saved Contact*

      The following actions are available when the call participant is a saved contact:

      - **See history** – Open the contact :ref:`call history <ps3_appplication_call_history>`.
      - **Call again** – Redial the same contact.

      .. figure:: https://doc.didww.com/_images/call_ended_saved.png
         :figclass: align-center
         :width: 30%
         :alt: Call ended screen for saved contact

         **Fig. 6.** Call Ended Screen (Saved Contact)

----

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate:

Call State Management
------------------------------

phone.systems™ app allows you to perform multiple actions during an active call. Click on the following shortcuts to learn more:

.. grid:: 1 1 2 3
   :gutter: 5

   .. grid-item-card:: **Mute/Unmute Your Microphone**
      :link: ps3_application_dialpad_callstate_mute
      :link-type: ref
      :text-align: center

      Toggle your microphone on or off during a call to control whether the other party can hear you.

   .. grid-item-card:: **Sound Settings**
      :link: ps3_application_dialpad_callstate_sound_settings
      :link-type: ref
      :text-align: center

      Switch the sound input and output methods.

   .. grid-item-card:: **Holding/Unholding a Call**
      :link: ps3_application_dialpad_callstate_hold
      :link-type: ref
      :text-align: center

      Place the current call on hold or resume it, allowing you to manage multiple tasks or conversations.

   .. grid-item-card:: **Using the Keypad**
      :link: ps3_application_dialpad_callstate_keypad
      :link-type: ref
      :text-align: center

      Open the dialpad to enter digits during a call — useful for extensions, IVRs, or access codes.

   .. grid-item-card:: **Blind Transfer**
      :link: ps3_application_dialpad_callstate_btransfer
      :link-type: ref
      :text-align: center

      Transfer the active call directly to another number without speaking to the recipient beforehand.

   .. grid-item-card:: **View in CRM**
      :link: ps3_application_dialpad_callstate_viewcrm
      :link-type: ref
      :text-align: center

      Open the synced contact’s record directly in your connected CRM.

   .. grid-item-card:: **Call Quality**
      :link: ps3_application_dialpad_callstate_quality
      :link-type: ref
      :text-align: center

      View the current quality of the active call directly on the in-call screen.

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_mute:

Mute/Unmute Your Microphone
^^^^^^^^^^^^^^^^^^^^^^^^^^^

    - To mute your microphone during an active call, click the |mute| icon. When muted, the icon will turn blue.
    - To unmute, click the |mute| icon again.

.. figure:: https://doc.didww.com/_images/fig32.png
   :figclass: align-center
   :width: 30%
   :alt: Muting Your Microphone

   **Fig. 7.** Muting Your Microphone

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_sound_settings:

Sound Settings
^^^^^^^^^^^^^^

Sound settings control which **microphone (input)** and **speaker or headset (output)** are used during a call.
The options differ depending on whether you are using the **mobile** or **desktop** app.

.. tab-set::

   .. tab-item:: *Mobile App*

      On mobile, the |sound| button toggles the **loudspeaker**.

         - To enable the loudspeaker, tap the |sound| icon. The call audio switches to the device speaker.
         - To disable it and return audio to the earpiece or connected headset, tap |sound| again.

      .. note::
         The loudspeaker toggle is only available on mobile.

      .. figure:: https://doc.didww.com/_images/loudspeaker.png
         :figclass: align-center
         :width: 30%
         :alt: Loudspeaker enabled on mobile

         **Fig. 8.** Loudspeaker button

      When a **Bluetooth** device is connected, the |sound| icon changes to |soundbt|.
      Tap it to open the **Output device** sheet, where you can choose between Bluetooth accessories, the speaker, or the device earpiece.

      .. grid:: 1 1 1 2

         .. grid-item::
            :class: text-center

            .. figure:: https://doc.didww.com/_images/appmobile1.png
               :figclass: align-center
               :alt: In-call sound button indicating Bluetooth device available (mobile)
               :width: 65%

               **Fig. 9.** Output device button

         .. grid-item::
            :class: text-center

            .. figure:: https://doc.didww.com/_images/appmobile2.png
               :figclass: align-center
               :alt: Output device sheet with Bluetooth accessories, speaker, and device earpiece options (mobile)
               :width: 65%

               **Fig. 10.** Output device selection

   .. tab-item:: *Desktop App*

      On desktop, clicking the |sound| button opens the **Sound Settings** window.
      Here, you can independently select which devices are used for **input** and **output** during an active call.

         1. Click the |sound| icon during a call.
         2. Under **Input devices**, choose your preferred microphone.
         3. Under **Output devices**, select your preferred speakers or headset.
         4. Close the window — the changes take effect immediately.

      .. tip::
         If a device does not appear, ensure it is connected at the OS level and recognized by your system before initiating or answering a call.

      .. grid:: 1 1 1 2

         .. grid-item::
            :class: text-center

            .. figure:: https://doc.didww.com/_images/appdesktop1.png
               :figclass: align-center
               :alt: Sound settings button on desktop

               **Fig. 11.** Sound settings button

         .. grid-item::
            :class: text-center

            .. figure:: https://doc.didww.com/_images/appdesktop2.png
               :figclass: align-center
               :alt: Sound settings window showing input and output device selection

               **Fig. 12.** Sound settings window

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_hold:

Hold/Unhold a Call
^^^^^^^^^^^^^^^^^^

    - To put a call on hold, click the |hold| icon. The text "(On Hold)" will appear next to the call duration.
    - To resume the call, click the |hold| icon again.

.. figure:: https://doc.didww.com/_images/fig31.png
   :figclass: align-center
   :width: 30%
   :alt: On Hold Button

   **Fig. 13.** On Hold Button

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_keypad:

Using the Keypad
^^^^^^^^^^^^^^^^

The **Keypad** feature sends **Dual-Tone Multi-Frequency (DTMF)** signals during a call, typically used for navigating automated phone menus or entering passcodes.

    1. To activate the keypad, click the |keypad| icon during an active call. The keypad will appear, allowing you to enter the necessary digits.
    2. To close the keypad, click the |keypad| icon again.

.. figure:: https://doc.didww.com/_images/fig65.png
   :figclass: align-center
   :width: 30%
   :alt: Keypad Interface

   **Fig. 14.** Keypad Interface

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_btransfer:

Blind Transfer
^^^^^^^^^^^^^^

The **Blind Transfer** feature allows you to transfer a call to another user without speaking to the person first.

To perform a blind transfer, follow the steps below:

    1. During an active call, tap the |blind_transfer| icon.
    2. Select the user you want to transfer the call to.

   .. figure:: https://doc.didww.com/_images/fig66.png
      :figclass: align-center
      :width: 30%
      :alt: Selecting a Contact

      **Fig. 15.** Selecting a Contact

3. Choose the number where the call should be transferred.

   - A :ref:`Phone Number <ps3_phone_numbers>`
   - An :ref:`Internal Number <ps3_internal_numbers>`

   .. figure:: https://doc.didww.com/_images/fig67.png
      :figclass: align-center
      :width: 30%
      :alt: Entering or Selecting a Number

      **Fig. 16.** Entering or Selecting a Number

Once the number is selected, the call will be transferred, and your connection will end.

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_viewcrm:

View in CRM
^^^^^^^^^^^^

When a contact is synced from a connected :ref:`CRM integration <ps3_crm_integrations>`, a **View in CRM** button appears on the in-call screen.
This feature lets you instantly open the contact’s record in the integrated CRM platform without leaving the phone.systems™ app.

    - To open the contact record in your CRM, click **View in CRM**.
    - The contact’s profile will open in a new browser tab or window, depending on your browser settings.

.. note::
   The **View in CRM** button only appears if the contact is imported or synced from your connected CRM.

.. figure:: https://doc.didww.com/_images/view_in_crm.png
   :figclass: align-center
   :width: 30%
   :alt: View in CRM button visible during an active call

   **Fig. 17.** View in CRM button during an active call

.. raw:: html

    <br>

.. _ps3_application_dialpad_callstate_quality:

Call Quality
^^^^^^^^^^^^

The **Call Quality** indicator shows the current quality of the active call directly on the in-call screen.
Use it to quickly understand whether the connection quality is stable while you are speaking.

The quality label appears below the contact name and number during the call.
For example, the app may show **Excellent Quality** with a green status indicator when the connection is strong.

If the call quality score is low, check your network connection, switch to a more stable network if possible, and make sure no other applications are using excessive bandwidth. If the issue continues, :ref:`report an issue <reporting_an_issue>`.

.. note:: Call quality is only shown on the desktop versions of the app.

.. figure:: https://doc.didww.com/_images/call_quality.png
   :figclass: align-center
   :width: 30%
   :alt: Call quality indicator shown during an active call

   **Fig. 18.** Call quality indicator

----

.. raw:: html

    <br>

Add a New Contact
-----------------

To add a new contact straight from the dialpad screen, follow these steps:

    1. Input a phone number of the new contact using the dialpad.
    2. Click on the |+-sym| button.

    .. figure:: https://doc.didww.com/_images/dialpad_create1.png
       :figclass: align-center
       :width: 30%
       :alt: Create Contact Button

       **Fig. 19.** Create Contact Button

    3. A contact creation screen will appear. Enter the following details:

        - **First Name:** The first name of the contact. |br|
        - **Last Name:** The last name of the contact. |br|
        - **Number(s):** One or more phone numbers of the contact. |br|
        - **Email:** The email address of the contact. |br|
        - **Job Title:** The contact's job title. |br|
        - **Company Name:** The contact's company name.

    4. Once you have entered all the details, click **Save** to create the contact.

    .. figure:: https://doc.didww.com/_images/dialpad_create2.png
       :figclass: align-center
       :width: 30%
       :alt: Create Contact

       **Fig. 20.** Create Contact

.. |call| image:: /phone-systems/assets/img/guide-v2/app/call.png
   :class: inline-img no-shadow
   :width: 90px
   :height: 30px

.. |call-button| image:: /phone-systems/assets/img/guide-v2/app/call-button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |hold| image:: /phone-systems/assets/img/guide-v2/app/hold.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |mute| image:: /phone-systems/assets/img/guide-v2/app/mute.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |sound| image:: /phone-systems/assets/img/guide-v2/app/sound.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |soundbt| image:: /phone-systems/assets/img/guide-v2/app/soundbt.png
   :class: inline-img no-shadow
   :width: 40px
   :height: 30px

.. |keypad| image:: /phone-systems/assets/img/guide-v2/app/keypad.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |blind_transfer| image:: /phone-systems/assets/img/guide-v2/app/blind_transfer.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |+-sym| image:: /phone-systems/assets/img/guide-v2/app/+-sym.png
   :class: inline-img no-shadow
   :width: 28px
   :height: 28px

.. raw:: html

   <style>

    .text-center {
         text-align: center;
    }

   </style>

.. raw:: html

    <style>
        .rst-content .section ul, .rst-content .toctree-wrapper ul, .rst-content section ul, .wy-plain-list-disc, article ul {
            margin-bottom: 0px;
            vertical-align: middle;
        }

    .sd-tab-content {
        box-shadow: none;
    }
    .sd-tab-set>label {
        border-color: var(--sd-color-tabs-underline);
        color: inherit;
    }

    /* Green check-circle */
    .sd-octicon-x-circle {
        color: #d73a49;
        fill: currentColor;
    }

    /* Red x-circle */
    .sd-octicon-check-circle {
        color: #28a745;
        fill: currentColor;
    }

    .hide-table {
        display: none;
    }

    </style>

.. raw:: html

   <style>
     em {
       font-size: 115%;
       font-weight: 700 !important;
       font-style: normal !important; /* Removes italic if desired */
       font-family: Roobert-semibold !important;
     }
   </style>

.. _ps3_application_contacts:

.. |br| raw:: html

   <br />

.. raw:: html

   <br>

phone.systems™ App Contacts
=============================

The **Contacts** section of the phone.systems™ application allows you to view and manage your saved contacts, including both external contacts and internal team members.

This guide explains how to navigate your contact list, create and manage contacts, understand user statuses, and use features like phonebooks and favorites.

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **Viewing Contacts & Phonebooks**
      :link: app_contacts_viewing
      :link-type: ref
      :text-align: center

      Learn to navigate your External and Team contacts and use phonebook filters.

   .. grid-item-card:: **Creating & Editing Contacts**
      :link: app_contacts_creating_editing
      :link-type: ref
      :text-align: center

      Add new external contacts and edit their details directly within the app.

   .. grid-item-card:: **Deleting Contacts**
      :link: app_contacts_deleting
      :link-type: ref
      :text-align: center

      Understand the process for removing both External and Team contacts.

   .. grid-item-card:: **Status, Favorites & Search**
      :link: app_contacts_features
      :link-type: ref
      :text-align: center

      Learn about real-time user status, favorites, and search functionality.

.. raw:: html

    <br>

----

.. _app_contacts_viewing:

Viewing Contacts & Phonebooks
-----------------------------

The Contacts section is divided into two main tabs, allowing you to easily distinguish between your external contacts and your internal team.

    - **External Contacts:** This tab displays all contacts from your company phonebook and your personal user's phonebook.
    - **Team Contacts:** This tab lists all internal :ref:`Users <ps3_users>` within your phone.systems™ account.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig9.png
           :figclass: align-center
           :alt: External Contacts

           **Fig. 1** External Contacts

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig99.png
           :figclass: align-center
           :alt: Team Contacts.

           **Fig. 2** Team Contacts.

Phonebooks
^^^^^^^^^^

Phonebooks control which contacts are visible to each user. You can choose from the following three options:

    - **All phonebooks:** Shows both company and user-specific contacts.
    - **Company:** Shows company contacts only.
    - **User:** Shows your user-specific contacts only.

.. grid:: 1 1 1 3

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/phonebook1.png
           :figclass: align-center
           :alt: All Phonebooks.

           **Fig. 3** All Phonebooks.

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/phonebook2.png
           :figclass: align-center
           :alt: Company Phonebook.

           **Fig. 4** Company Phonebook.

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/phonebook3.png
           :figclass: align-center
           :alt: User-specific Phonebook.

           **Fig. 5** User's Phonebook.

----

.. raw:: html

    <br>

.. _app_contacts_creating_editing:

Creating & Editing Contacts
---------------------------

.. note::
   **Team Contacts** cannot be created or edited using the phone.systems™ app. They must be created as new :ref:`Users <ps3_users_create_new>` in the phone.systems™ UI.

Creating External Contacts
^^^^^^^^^^^^^^^^^^^^^^^^^^

In the phone.systems™ app, you can create new contacts directly in the **Contacts** section.

To create a new contact:

    1. Open the **Contacts** tab on the phone.systems™ app.
    2. Click the |+-icon| icon in the top right corner of the application interface.
    3. A contact creation screen will appear. Enter the following details:

        .. list-table::
           :header-rows: 1
           :widths: 30 70

           * - **Field**
             - **Description**
           * - **Phonebook**
             - Assign the contact to the shared **Company Phonebook** or your private **User's Phonebook**.
           * - **First Name**
             - The first name of the contact.
           * - **Last Name**
             - The last name of the contact.
           * - **Number(s)**
             - One or more phone numbers for the contact.
           * - **Email**
             - The email address of the contact.
           * - **Job Title**
             - The contact's job title.
           * - **Company Name**
             - The contact's company name.

    4. Click **Save** to add the contact. The contacts will appear in the :ref:`contacts menu <ps3_contacts>` of the phone.systems™ app.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig17.png
           :figclass: align-center
           :alt: Create Contacts Button

           **Fig. 6.** Create Contacts Button

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig18.png
           :figclass: align-center
           :alt: Creating a Contact

           **Fig. 7.** Creating a Contact

Editing External Contacts
^^^^^^^^^^^^^^^^^^^^^^^^^

To edit a contact in the phone.systems™ app:

    1. Navigate to the **Contacts** section.
    2. Locate the contact you want to modify from the relevant phonebook view (e.g., **Company** or **User** phonebook).
    3. Click on the contact to open the details.
    4. Click the |edit-contact| icon to open the edit form.
    5. Make the desired changes in the **Edit contact** menu.
    6. Click **Save** to apply the changes.

Edits will be immediately reflected in the :ref:`contact list <ps3_contacts>` within the phone.systems™ interface.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig19.png
           :figclass: align-center
           :alt: Edit Contact Button.

           **Fig. 8.** Edit Contact Button.

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig20.png
           :figclass: align-center
           :alt: Editing Contacts.

           **Fig. 9.** Editing Contacts.

----

.. raw:: html

   <br>

.. _app_contacts_deleting:

Deleting Contacts
-----------------

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Delete External Contacts*

      To delete **External Contacts**, open the :ref:`Contacts menu <ps3_deleting_contacts>` in your phone.systems™ UI.

      1. Locate the contact you want to delete.
      2. Click the **Actions** button next to the contact.
      3. Select **Delete** to remove the contact.

      .. figure:: https://doc.didww.com/_images/fig21.png
         :figclass: align-center
         :alt: Deleting External Contacts

         **Fig. 10.** Deleting an External Contact

   .. tab-item:: *Delete Team Contacts*

      To delete **Team Contacts**, go to the :ref:`Users menu <ps3_users_deleting>` in your phone.systems™ UI.

      1. Locate the user you want to delete.
      2. Click the **Actions** button and select **Delete**.

      .. figure:: https://doc.didww.com/_images/fig0.png
         :figclass: align-center
         :alt: Actions Button

         **Fig. 11.** Actions Button in the Users Menu

      If the user has any active dependencies, they will be listed in the **Delete User** screen.

      To confirm deletion, check the box labeled **I am aware that by deleting this User(s) I will also remove the dependencies**, and click **Delete**.

      .. figure:: https://doc.didww.com/_images/fig50.png
         :figclass: align-center
         :figwidth: 40%
         :alt: Deleting Team Contact

         **Fig. 12.** Deleting a Team Contact

.. raw:: html

    <br>

----

.. _app_contacts_features:

Status, Favorites & Search
--------------------------

Contact Status
^^^^^^^^^^^^^^

The **phone.systems™** app provides real-time contact status visibility for **Team Contacts**, allowing users to see whether their colleagues are available for calls.

This feature helps streamline communication by ensuring users only attempt to call contacts who are available.

.. tab-set::
   :class: my-tabs

   .. tab-item:: |available| *Available Status*

    The **Available** status means the contact is actively connected to the phone.systems app and can receive incoming calls.

        - The user is online and logged into the app.
        - Their device (mobile or desktop) is registered and ready to receive calls.

   .. tab-item:: |unavailable| *Unavailable Status*

    The **Unavailable** status means the contact is online but has manually set their status to unavailable, preventing them from receiving calls.

        - The user is still logged into the app but has set their status to **Unavailable**.
        - Their device remains registered, but incoming calls will not ring through.
        - If another team member attempts to call them, the call may go to voicemail or follow call forwarding rules (if configured).

   .. tab-item:: |in-call| *In-call Status*

    The **In-call** status is displayed when a contact is currently on an active call using phone.systems.

        - The user is engaged in a call and cannot accept new incoming calls.
        - If another team member attempts to call them, the call may go to voicemail or follow call forwarding rules (if configured).
        - Once the call ends, their status will update based on their availability (Available or Unavailable).

   .. tab-item:: |offline| *Offline Status*

    The **Offline** status means the contact is not connected to the phone.systems app, making them unreachable.

        - The user is logged out of the app, or their device is not registered.
        - If another team member attempts to call them, the call may go to voicemail or follow call forwarding rules (if configured).
        - They will not receive incoming calls until they reconnect to the system.

.. note::
   Contact statuses are only displayed for **Team Contacts**. External contacts and non-team members do not have a visible status.

.. figure:: https://doc.didww.com/_images/fig_status.png
   :figclass: align-center
   :figwidth: 40%

   **Fig. 13.** Contact Status

Favorite Contacts
^^^^^^^^^^^^^^^^^^^

You can mark both **External** and **Team** contacts as favorites to have them appear at the top of your contact lists and in the dedicated **Favorites** tab.

1.  Open the contact you wish to favorite.
2.  Click the **star icon** (|star|) to mark it as a favorite.

.. grid:: 1 1 2 3

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig24.png
           :figclass: align-center

           **Fig. 14.** Favorite Button

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig25.png
           :figclass: align-center

           **Fig. 15.** Favorite Contacts

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig25.1.png
           :figclass: align-center

           **Fig. 16.** Favorite Contacts Tab

Using the Search Bar
^^^^^^^^^^^^^^^^^^^^

In **phone.systems™**, use the search bar to quickly find contacts by name or phone number.

    - For **name** searches, type any part of the first or last name.
    - For **phone number** searches, type any part of the phone or internal number.

Results appear instantly as you type.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig26.png
           :figclass: align-center

           **Fig. 17.** Searching Contacts By Name

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig27.png
           :figclass: align-center

           **Fig. 18.** Searching Contacts By Number

.. |+-icon| image:: /phone-systems/assets/img/guide-v2/app/+-icon.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |edit-contact| image:: /phone-systems/assets/img/guide-v2/app/edit-contact.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |star| image:: /phone-systems/assets/img/guide-v2/app/star.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |available| image:: /phone-systems/assets/img/guide-v2/app/available-inline.svg
   :class: custom-padding no-shadow inline-img

.. |unavailable| image:: /phone-systems/assets/img/guide-v2/app/unavailable-inline.svg
   :class: custom-padding no-shadow inline-img

.. |in-call| image:: /phone-systems/assets/img/guide-v2/app/in-call-inline.svg
   :class: custom-padding no-shadow inline-img

.. |offline| image:: /phone-systems/assets/img/guide-v2/app/offline-inline.svg
   :class: custom-padding no-shadow inline-img

.. raw:: html

    <style>
       .custom-padding {
           padding-bottom: 3px;
           width: 20px;
           height: 20px;
       }
    </style>


.. _ps3_appplication_call_history:

.. |br| raw:: html

   <br />

phone.systems™ App Call History
===============================

The **Call History** section provides access to logs of recent inbound and outbound calls, including visual status indicators. You can review recent call activities, identify missed or lost calls, and access detailed information such as call type, timestamps, and duration.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item-card:: **View Call Details**
      :link: ps3_appplication_call_history_details
      :link-type: ref
      :text-align: center

      Explore full metadata and technical information recorded for each call.

   .. grid-item-card:: **Access Call Attachments**
      :link: ps3_appplication_call_history_attachments
      :link-type: ref
      :text-align: center

      Access voicemails, recordings, faxes, AI insights, tags, and notes associated with calls.

   .. grid-item-card:: **Access Related Calls**
      :link: ps3_appplication_call_history_related
      :link-type: ref
      :text-align: center

      View and manage calls grouped by flow or user session.

   .. grid-item-card:: **Synchronize Call Records**
      :link: ps3_application_call_sync
      :link-type: ref
      :text-align: center

      Manually sync call logs to retrieve the latest data.

   .. grid-item-card:: **Filter Call History**
      :link: ps3_appplication_call_history_filter
      :link-type: ref
      :text-align: center

      Narrow down your call history using advanced filter criteria.

   .. grid-item-card:: **Resolve Lost Calls**
      :link: ps3_appplication_call_history_lost_calls
      :link-type: ref
      :text-align: center

      Review and manage missed or unanswered calls.

----

.. raw:: html

    <br>

.. _ps3_appplication_call_history_details:

Call Log Details
----------------

To view detailed call information, click the |inline_details| button on the corresponding call log entry. This opens a page displaying call participants, status, start time, durations, end reason, and resolution details.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/call_log_record.png
           :figclass: align-center
           :alt: Call log record
           :width: 90%

           **Fig. 1.** Call Log Record

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig46.png
           :figclass: align-center
           :alt: Call log details and attachments
           :width: 77%

           **Fig. 2.** Call Log Details

.. raw:: html

   <style>

    .text-center {
         text-align: center;
    }

   </style>

.. list-table::
   :widths: 20 70
   :header-rows: 0

   * - **Call Log Detail**
     - **Description**
   * - **Call Participants**
     -
       - **Source numbers** – The number of the caller who initiated the call.
       - **Destination numbers** – The number of the callee who answered the call.

   * - **General Call Details**
     -
       - **Status** – The current status of the call.
       - **Call log** – The synchronization status of the call.
       - **Call Start** – The time when the call began.
       - **Waiting Time** – The duration it took for the call to connect or disconnect.
       - **In Call Duration** – The total time the call was active.

   * - **End Reason**
     -
       - **Resolved At** – The date and time when the call was resolved.
       - **Resolved By** – The user who resolved the call.
       - **End Reason** – The reason for the call ending.

.. tip::

    You can callback the contact or number straight from the call log details screen by clicking the |call-button| button.

Unknown Contact Actions
^^^^^^^^^^^^^^^^^^^^^^^

The **Actions** menu is available when a call participant is shown as an **unknown contact** in the **Call Log Details** screen.
Tap the **three-dots** icon next to the phone number to open the menu.

The available actions include:

- **Call** – Initiate a new call to the selected number.
- **Copy number** – Copy the phone number to your clipboard.
- **Create contact** – Add the number as a new contact.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/actions-menu1.png
           :figclass: align-center
           :alt: Actions button for unknown contact
           :width: 100%

           **Fig. 3.** Actions Button

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/actions-menu2.png
           :figclass: align-center
           :alt: Actions menu for unknown contact
           :width: 100%

           **Fig. 4.** Actions Menu

----

.. raw:: html

    <br>

.. _ps3_appplication_call_history_attachments:

Call Attachments
-----------------------

The **Attachments** tab in your phone.systems™ call history lets you review and interact with files related to a specific call.

.. important::
    - To view attachments in the phone.systems™ app, make sure that users are :ref:`added to the call flow <ps3_control_panel_manage_users>`.
    - Attachments are only available if :ref:`cloud storage <ps3_cloud_storage_integrations>` is enabled.

Select an attachment type below to learn more:

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **Voicemail**
      :link: ps3_appplication_call_history_attachments_voicemail
      :link-type: ref
      :text-align: center

      Review and play back voicemail attachments.

   .. grid-item-card:: **Recording**
      :link: ps3_appplication_call_history_attachments_recording
      :link-type: ref
      :text-align: center

      Access and play call recordings.

   .. grid-item-card:: **Fax**
      :link: ps3_appplication_call_history_attachments_fax
      :link-type: ref
      :text-align: center

      Open and view fax PDFs.

   .. grid-item-card:: **AI Call Insights**
      :link: ps3_appplication_call_history_attachments_ai
      :link-type: ref
      :text-align: center

      Explore AI-powered summaries, analyses, and transcripts.

   .. grid-item-card:: **Tags**
      :link: ps3_app_call_history_attachments_tags
      :link-type: ref
      :text-align: center

      Assign or remove tags to organize calls.

   .. grid-item-card:: **Notes**
      :link: ps3_app_call_history_attachments_notes
      :link-type: ref
      :text-align: center

      Add, edit, or delete notes for a call.

.. raw:: html

    <br>

.. _ps3_appplication_call_history_attachments_voicemail:

Voicemail Attachments
^^^^^^^^^^^^^^^^^^^^^^^^

Use the voicemail attachment to play back voice messages left after missed calls.

Tap the |inline_play| icon to play the voicemail, or use the |inline_playback| control to adjust playback speed.

.. note::

   You can download voicemails from the web UI under :ref:`call flow CDRs <ps3_call_flow_cdrs_voicemail>`.

.. figure:: https://doc.didww.com/_images/fig68.png
   :figclass: align-center
   :alt: Voicemail Attachments
   :width: 30%

   **Fig. 5.** Voicemail Attachments

.. _ps3_appplication_call_history_attachments_recording:

Recording Attachments
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The **Recording** attachment provides access to the full audio of a call.

Tap the |inline_play| icon to play the recording, or use the |inline_playback| control to adjust playback speed.

.. note::

    You can download call recordings from the web UI under :ref:`call flow CDRs <ps3_call_flow_cdrs_recording>`.

.. figure:: https://doc.didww.com/_images/fig70.png
   :figclass: align-center
   :alt: Recording Attachments
   :width: 30%

   **Fig. 6.** Recording Attachments

.. _ps3_appplication_call_history_attachments_fax:

Fax Attachments
^^^^^^^^^^^^^^^^^^^^^

The **Fax** attachment allows you to open faxed documents directly in PDF format.

Tap the **Open PDF** button to open the PDF file.

.. figure:: https://doc.didww.com/_images/fig69.png
   :figclass: align-center
   :alt: Fax Attachments
   :width: 30%

   **Fig. 7.** Fax Attachments

.. _ps3_appplication_call_history_attachments_ai:

AI Call Insights
^^^^^^^^^^^^^^^^

Use **AI Call Insights** to review recorded calls with enhanced context.

This feature provides a :ref:`summary <ps3_appplication_call_history_attachments_ai_summary>`, :ref:`analysis <ps3_appplication_call_history_attachments_ai_analysis>`, and :ref:`transcript <ps3_appplication_call_history_attachments_ai_transcript>` for each call. These insights help you quickly identify key points, understand participant interactions, and review the conversation without needing to play the recording.

.. note::

    1. Make sure **AI Call Insights** feature is enabled before the call is logged. Learn how to do this in :ref:`AI Call Insights <ps3_ai_settings_enable>`.
    2. AI Processing Conditions:

       - AI generation and charging begin once the call has been connected for at least **15 seconds**.
       - The audio file must not exceed **25 MB**.

.. figure:: https://doc.didww.com/_images/fig60.png
   :figclass: align-center
   :alt: AI Call Insights: Summary, Analysis and Transcript
   :width: 30%

   **Fig. 8.** AI Call Insights: Summary, Analysis and Transcript

.. _ps3_appplication_call_history_attachments_ai_summary:

AI Call Insight: Summary
"""""""""""""""""""""""""

The **Summary** section highlights the key points from a call. This helps users quickly understand the purpose and decisions made, without needing to replay the conversation.

.. figure:: https://doc.didww.com/_images/fig61.png
   :figclass: align-center
   :alt: AI Call Insight: Summary
   :width: 30%

   **Fig. 9.** AI Call Insight: Summary

.. _ps3_appplication_call_history_attachments_ai_analysis:

AI Call Insight: Analysis
""""""""""""""""""""""""""""

The **Analysis** section provides insight into speaker behavior and mood. It includes:

    - **Talk-to-Listen Ratio**: Compares speaking vs. listening time per participant.
    - **Sentiment Analysis**: Identifies the emotional tone as positive, neutral, or negative.

.. figure:: https://doc.didww.com/_images/fig62.png
   :figclass: align-center
   :alt: AI Call Insight: Analysis
   :width: 30%

   **Fig. 10.** AI Call Insight: Analysis

.. _ps3_appplication_call_history_attachments_ai_transcript:

AI Call Insight: Transcript
"""""""""""""""""""""""""""""""

The **Transcript** displays a full text version of the call. This feature is ideal for reviewing dialogue, validating information, or tracking action items.

.. figure:: https://doc.didww.com/_images/fig63.png
   :figclass: align-center
   :alt: AI Call Insight: Transcript
   :width: 30%

   **Fig. 11.** AI Call Insight: Transcript

.. _ps3_app_call_history_attachments_tags:

Tags
^^^^

The **Tags** attachment lets you assign predefined labels to a call to help categorize and organize call records.

Use tags when you want to group calls by purpose, track specific types of interactions (for example, potential customer or callback), or make calls easier to filter and review later.

Tap the **Tags** icon to open the tag selection window. Select one or more tags, then tap **Apply** to assign them to the call.

.. note::

    Tags are created and managed in the :ref:`Call Tags <ps3_settings_call_tags>` section of the phone.systems™ Admin Panel.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/call_tags_attachment_view.png
           :figclass: align-center
           :alt: Tags section in attachments
           :width: 90%

           **Fig. 12.** Tags in the Attachments tab

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/call_tags_modal.png
           :figclass: align-center
           :alt: Tag selection window
           :width: 90%

           **Fig. 13.** Select and apply tags

.. _ps3_app_call_history_attachments_notes:

Notes
^^^^^^^^^

The **Notes** attachment lets you add and manage text notes for a call to capture important details or follow-up actions.

Use notes to document conversation summaries, key decisions, or additional context that is not included in call metadata or recordings.

Tap the **Edit** icon to open the note editor, update the content, then tap **Save** to apply changes.
Tap the **Delete** icon to remove the note from the call.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/notes_attachment_view.png
           :figclass: align-center
           :alt: Notes section in attachments
           :width: 90%

           **Fig. 14.** Notes in the Attachments tab

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/notes_edit_modal.png
           :figclass: align-center
           :alt: Edit note window
           :width: 90%

           **Fig. 15.** Edit note window

----

.. raw:: html

    <br>

.. _ps3_appplication_call_history_related:

Access Related Calls
----------------------

The **Related Calls** tab, available within the opened call log history, displays all calls associated with the current entry. It helps support teams and supervisors trace user call behavior, especially in cases of failed attempts or escalations. This feature supports tracking the sequence and context of call interactions.

Each related call entry includes:

    - **Contact name and call outcome** – Displays the participant's name (e.g., John S.) and the result (e.g., Failed).
    - **Call type** – Indicates whether the call was a **Direct Call** or handled via a call flow.
    - **Timestamp** – Shows the time of the related call (e.g., 12:21).

.. note::
   The **Related Calls** tab appears only if there is more than one call associated with the same user or number.

.. figure:: https://doc.didww.com/_images/fig71.png
   :figclass: align-center
   :alt: Related Calls
   :width: 30%

   **Fig. 16.** Related Calls Tab

----

.. raw:: html

    <br>

.. _ps3_application_call_sync:

Synchronize Call Records
------------------------------

The **phone.systems™ app** synchronizes call history periodically, but you can also perform an instant manual synchronization if you need to update the call history immediately.

To synchronize your call history in real time:

    1. Open the Call history tab on the phone.systems™ app.
    2. Click the |inline_synch| button.

.. figure:: https://doc.didww.com/_images/synchronize.png
   :figclass: align-center
   :alt: Synchronize button
   :figwidth: 40%

   **Fig. 17.** Synchronize button

----

.. raw:: html

    <br>

.. _ps3_appplication_call_history_filter:

Filter Call History
-------------------

The **Filter Call History** panel lets you refine visible call logs based on specific criteria.

Use filters to quickly locate calls by date, direction, status, type, attachments, or assigned tags.

To use filters, follow these steps:

    1. Open the **Call history** section in the phone.systems™ app.
    2. Tap the |filter| icon to open the **Filter Call History** screen.
    3. Select the filters you want to apply.
    4. Tap **Apply**.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig77.png
           :figclass: align-center
           :alt: Filter Call History Button

           **Fig. 18** Filter Call History Button

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/fig72.png
           :figclass: align-center
           :alt: Filter Call History Panel

           **Fig. 19** Filter Call History Panel

These are all of the available filters and their attributes:

    .. list-table::
       :widths: 15 70
       :header-rows: 1

       * - **Filter**
         - **Attributes**
       * - **Date**
         - Filters calls by time range:

           - **All** – Displays calls from all available dates.
           - **Today** – Shows only calls made or received on the current date.
           - **Yesterday** – Displays calls from the previous calendar day.
           - **Last week** – Filters calls placed or received within the last 7 days.
           - **Last month** – Includes calls from the last 30 calendar days.

       * - **Direction**
         - Filters based on the direction of the call:

           - **All** – Shows both inbound and outbound calls.
           - **Inbound** – Displays only incoming calls received by the user.
           - **Outbound** – Displays only outgoing calls initiated by the user.

       * - **Status**
         - Filters calls by completion or handling state:

           - **All** – Includes calls of any status.
           - **Lost** – Calls that were missed or not successfully connected.
           - **Answered** – Calls that were successfully picked up by the recipient.
           - **Resolved** – Calls that were manually or automatically marked as completed or followed-up.

       * - **Type**
         - Filters by the call’s routing path:

           - **All** – Includes all types of call routing.
           - **Call flow** – Calls that passed through a defined call flow (configured using :ref:`call flows <ps3_call_flows_index>`).
           - **Direct call** – Peer-to-peer calls made directly between two endpoints (configured using :ref:`contact methods <ps3_app_configurations>`).

       * - **Attachments**
         - Filters calls based on the presence of specific attachments. At least one of the selected options must exist on the call log (OR logic):

           - **Voicemail** – Includes calls with a voicemail recording.
           - **Recording** – Includes calls with a full call audio recording.
           - **Fax** – Includes call logs with a fax PDF document attached.
           - **AI call insights** – Includes calls with AI-generated summaries, analysis, or transcripts.
           - **Note** – Includes calls that contain a saved note.

       * - **Tags**
         - Filters calls by assigned tags. Select one or more tags to display calls that match the selected labels.

----

.. raw:: html

    <br>

.. _ps3_appplication_call_history_lost_calls:

Lost Calls
------------

The **Lost Calls** section helps you avoid missed opportunities by tracking failed calls that may need follow-up.

You can find the **Lost Calls** tab in the **Call History** section. Missed or failed calls are marked with a red icon and labeled as "Failed."

.. figure:: https://doc.didww.com/_images/fig12.png
   :figclass: align-center
   :alt: Lost Calls History
   :figwidth: 40%

   **Fig. 20.** Lost Calls History

There are two ways to resolve a lost call:

1. **Return the Call**

   Select the missed call and tap the phone icon to redial.

2. **Mark as Resolved**

   You can manually mark the call as resolved by clicking the |inline_resolve| button:

   .. figure:: https://doc.didww.com/_images/resolve.png
        :figclass: align-center
        :alt: Manually Resolving Lost Calls
        :figwidth: 40%

        **Fig. 21.** Manually Resolving Lost Calls in Call History

   Or open the call details by clicking the |inline_details| button, then select the |inline_checkmark| icon in the upper-right corner to mark the call as resolved. In the confirmation window, click **Confirm** to complete the action.

   .. figure:: https://doc.didww.com/_images/fig16.png
        :figclass: align-center
        :alt: Manually Resolving Lost Calls from Details View
        :figwidth: 80%

        **Fig. 22.** Resolving a Lost Call from the Call Details View

.. |inline_details| image:: ../assets/img/guide-v2/app/inline_details.png
   :class: inline-img no-shadow
   :width: 67.5px
   :height: 30px

.. |inline_playback| image:: ../assets/img/guide-v2/app/inline_playback.png
   :class: inline-img no-shadow
   :width: 60px
   :height: 30px

.. |inline_resolve| image:: ../assets/img/guide-v2/app/inline_resolve.png
   :class: inline-img no-shadow
   :width: 67.5px
   :height: 30px

.. |inline_synch| image:: ../assets/img/guide-v2/app/inline_synch.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |inline_checkmark| image:: ../assets/img/guide-v2/app/inline_checkmark.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |inline_play| image:: ../assets/img/guide-v2/app/inline_play.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |filter| image:: ../assets/img/guide-v2/app/filter.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. |call-button| image:: ../assets/img/guide-v2/app/call-button.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px


.. _ps3_application_settings:

.. |br| raw:: html

   <br />

phone.systems™ App Settings
===========================

The phone.systems™ app provides a range of settings to help you customize and control your experience. Use the settings section to adjust preferences related to behavior, profile management, and notifications.

Use the following options to manage your app behavior, call handling, and profile settings:

.. grid:: 1 1 1 4
   :gutter: 5

   .. grid-item-card:: **Change Application Status**
      :link: ps3_change_your_application_status
      :link-type: ref
      :text-align: center

      Set your availability for calls by choosing Online, Pause, or Offline status.

   .. grid-item-card:: **Switch Outbound Caller ID**
      :link: ps3_switch_your_outbound_caller_id
      :link-type: ref
      :text-align: center

      Select which number is shown as your caller ID when making outbound calls.

   .. grid-item-card:: **Manage Personal Settings**
      :link: ps3_application_settings_personal
      :link-type: ref
      :text-align: center

      Manage your user profile and CRM integration.

   .. grid-item-card:: **Manage General Settings**
      :link: ps3_application_settings_general
      :link-type: ref
      :text-align: center

      Configure app behavior, startup options, sound notifications, and sign-out settings.

----

Open App Settings
--------------------

    1. Tap the **top bar** to open the drop-down menu.
    2. Tap the |settings| icon to open the **Settings** panel.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/reporting1.png
           :figclass: align-center
           :alt: Step 1: Open the drop-down menu

           **Fig. 1.** Open the Drop-Down Menu

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/reporting2.png
           :figclass: align-center
           :alt: Step 2: Open the settings menu

           **Fig. 2.** Open the Settings Menu

----

.. raw:: html

    <br>

.. _ps3_change_your_application_status:

Change Application Status
-----------------------------------

In the phone.systems™ app, you can manually adjust your application status to control your availability for calls. This feature is useful for managing your presence during working hours, breaks, or when you're unavailable.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Version 1.0.30 and above*

      To change your application status:

      1. Tap the **top bar** to open the drop-down menu.
      2. Choose one of the following options:

         - **Available** – You are available for inbound and outbound calls.
         - **Unavailable** – You are not available to receive calls.

      .. grid:: 1 1 1 2

         .. grid-item::
            :class: text-center

              .. figure:: https://doc.didww.com/_images/available.png
                 :figclass: align-center
                 :alt: Application Status Available

                 **Fig. 3.** Available

         .. grid-item::
            :class: text-center

              .. figure:: https://doc.didww.com/_images/unavailable.png
                 :figclass: align-center
                 :alt: Application Status Unavailable

                 **Fig. 4.** Unavailable

   .. tab-item:: *Version 1.0.28 and below*

      To change your application status:

      1. Tap the **top bar** to open the drop-down menu.
      2. Select one of the following status options:

         - **Online** – You are available for inbound and outbound calls.
         - **Pause** – You can make outbound calls, but inbound calls are disabled.
         - **Offline** – You are not available for any calls.

      .. grid:: 1 1 1 3

         .. grid-item::
            :class: text-center

              .. figure:: https://doc.didww.com/_images/fig13.1.png
                 :figclass: align-center
                 :alt: Application Status Online

                 **Fig. 5.** Online

         .. grid-item::
            :class: text-center

              .. figure:: https://doc.didww.com/_images/fig13.2.png
                 :figclass: align-center
                 :alt: Application Status Pause

                 **Fig. 6.** Pause

         .. grid-item::
            :class: text-center

              .. figure:: https://doc.didww.com/_images/fig13.3.png
                 :figclass: align-center
                 :alt: Application Status Offline

                 **Fig. 7.** Offline

----

.. raw:: html

    <br>

.. _ps3_switch_your_outbound_caller_id:

Switch Outbound Caller ID
--------------------------------

In the phone.systems™ app, you can configure and switch your **outbound caller ID**—the number shown to recipients when you place a call.

If your user account has access to multiple caller IDs (numbers assigned by your administrator), the app lets you choose which one to use for outgoing calls.

To switch your outbound caller ID:

    1. Tap the **top bar** of the app to open the drop-down menu.
    2. From the list of available caller IDs, select the one you want to use.

The active caller ID will appear in the top-right corner of the interface.

.. figure:: https://doc.didww.com/_images/cli.png
   :figclass: align-center
   :alt: Outbound Caller ID List
   :width: 30%

   **Fig. 8.** Outbound Caller ID List

----

.. raw:: html

    <br>

.. _ps3_application_settings_personal:

Manage Personal Settings
--------------------------

The **Personal** section contains settings related to your user profile and CRM integration. These options help personalize how the application behaves during communication events.

Use the shortcuts below to access specific personal settings:

.. grid:: 1 1 1 2
   :gutter: 5

   .. grid-item-card:: **Edit profile**
      :link: ps3_application_settings_personal_edit
      :link-type: ref
      :text-align: center

      Update your personal information, including your name, job title, and department.

   .. grid-item-card:: **Open CRM Contact pages automatically**
      :link: ps3_application_settings_personal_opencrm
      :link-type: ref
      :text-align: center

      Automatically open CRM contact pages during external calls to access caller information instantly.

.. _ps3_application_settings_personal_edit:

Edit Profile
^^^^^^^^^^^^^^^^^^^^^^

The **Edit Profile** screen lets you update your basic user information and avatar.

You can modify the following fields:

    - **First name**
    - **Last name**
    - **Job title**
    - **Department**

Avatar
''''''

Additionally, you can upload a **custom avatar**:

    1. Tap the |edit| icon to upload a new avatar image.
    2. Select the desired image file from your device.
    3. Use the adjustment slider to resize or reposition the avatar if needed.
    4. Click **Save** to apply your changes.

    .. note::

        - Supported image formats are **.jpeg** and **.png**.
        - To edit the existing avatar or remove the current avatar, tap the |edit| icon.
        - Avatar changes sync with the :ref:`phone.systems users menu <ps3_users>`. If no custom avatar is set, the app displays the user’s initials.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/edit.png
           :figclass: align-center
           :alt: Edit Profile

           **Fig. 9.** Edit Avatar Button

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/edit2.png
           :figclass: align-center
           :alt: Edit Profile

           **Fig. 10.** Edit Avatar Window

.. _ps3_application_settings_personal_opencrm:

Open CRM Contact Pages Automatically
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When this setting is turned on, phone.systems™ automatically opens the contact details page in your connected CRM during calls with external contacts.

This feature works as follows:

    - Incoming calls from recognized external sources trigger a CRM lookup.
    - The CRM interface opens directly to the contact’s details page, giving you instant access to caller information.
    - This reduces the need for manual searches and helps you handle calls more efficiently.

.. note::

   To use this feature, your CRM system must already be integrated with phone.systems™. For setup instructions, see :ref:`CRM integrations <ps3_crm_integrations>`.

.. figure:: https://doc.didww.com/_images/crm.png
   :figclass: align-center
   :alt: Open CRM Contact Pages Automatically
   :width: 30%

   **Fig. 11.** Open CRM Contact Pages Automatically

----

.. raw:: html

    <br>

.. _ps3_application_settings_general:

Manage General Settings
--------------------------

The **General** section contains settings for controlling application behavior, managing audio feedback, and accessing support.

Click the shortcuts to any of the general settings below:

.. grid:: 1 1 2 3
   :gutter: 5

   .. grid-item-card:: **Start app automatically**
      :link: ps3_application_settings_general_starting
      :link-type: ref
      :text-align: center

      Set the app to automatically start when your device turns on, ensuring it's always ready for use.

   .. grid-item-card:: **Sound settings**
      :link: ps3_application_settings_general_sound
      :link-type: ref
      :text-align: center

      Choose a ringtone and control ringtone or dialpad sound behavior in the desktop app.

   .. grid-item-card:: **Language**
      :link: ps3_application_settings_general_language
      :link-type: ref
      :text-align: center

      Change the interface language to your preferred option.

   .. grid-item-card:: **Report an issue**
      :link: reporting_an_issue
      :link-type: ref
      :text-align: center

      Quickly report any issues by providing details to the support team for resolution.

   .. grid-item-card:: **Sign out**
      :link: ps3_application_settings_general_signout
      :link-type: ref
      :text-align: center

      Sign out of your account to end your session and ensure your data is secure.

.. _ps3_application_settings_general_starting:

Start App Automatically
^^^^^^^^^^^^^^^^^^^^^^^

You can configure the **phone.systems™** app to launch automatically when your device turns on.

To enable automatic startup:

    1. Open the **General** settings section.
    2. Toggle on the **Start app automatically** option.

    .. figure:: https://doc.didww.com/_images/start_app.png
       :figclass: align-center
       :alt: Start app automatically toggle
       :width: 30%

       **Fig. 12.** Start App Automatically Toggle

.. _ps3_application_settings_general_sound:

Sound Settings
^^^^^^^^^^^^^^

Use **Sound settings** to manage ringtone playback, select an incoming call ringtone, and control dialpad tones.

.. note::

   These settings control ringtone and dialpad sound behavior in the app. They do not change call audio devices or system-level sound settings.

Enable or Disable Ringtone
''''''''''''''''''''''''''

The ringtone is the sound played when you receive an incoming call.

To enable or disable ringtone playback:

    1. Open the **General** settings section.
    2. Open **Sound settings**.
    3. Under **Ringtone**, turn **Play ringtone** on or off.

       - **On** - The selected ringtone plays for incoming calls.
       - **Off** - Incoming calls arrive without ringtone playback in the app.

.. figure:: https://doc.didww.com/_images/sound_settings_ringtone.png
   :figclass: align-center
   :alt: Ringtone sound settings
   :width: 30%

   **Fig. 13.** Ringtone Sound Settings

Change Ringtone
'''''''''''''''

To change the ringtone:

    1. Open the **General** settings section.
    2. Open **Sound settings**.
    3. Under **Ringtone**, select the current ringtone name.
    4. Preview a ringtone if needed.
    5. Select the ringtone you want to use.

.. figure:: https://doc.didww.com/_images/sound_settings_select_ringtone.png
   :figclass: align-center
   :alt: Available ringtones
   :width: 30%

   **Fig. 14.** Available Ringtones

Enable or Disable Dialpad Sounds
''''''''''''''''''''''''''''''''

Dialpad sounds are tones played when you press keys on the keypad.

To enable or disable dialpad sounds:

    1. Open the **General** settings section.
    2. Open **Sound settings**.
    3. Under **Dialpad**, turn **Sound** on or off.

       - **On** - Dialpad tones play when you use the keypad.
       - **Off** - Dialpad tones are muted.

.. figure:: https://doc.didww.com/_images/sound_settings_dialpad.png
   :figclass: align-center
   :alt: Dialpad sound settings
   :width: 30%

   **Fig. 15.** Dialpad Sound Settings

.. _ps3_application_settings_language:

.. _ps3_application_settings_general_language:

Language
^^^^^^^^

The **Language** setting allows you to customize the interface of the **phone.systems™** app.
Changing the language updates all in-app menus, buttons, and labels.

To change your language preference:

    1. Tap the **top bar** to open the drop-down menu.
    2. Tap the |settings| icon to open the **Settings** menu.
    3. Tap **Language**.
    4. Select your preferred language from the list:

        - **English (default)**
        - **Ukrainian**
        - **Lithuanian**
        - **Latvian**
        - **German**
        - **Spanish**
        - **Portuguese**

.. figure:: https://doc.didww.com/_images/language.png
   :figclass: align-center
   :alt: Language Selection Screen
   :width: 30%

   **Fig. 16.** Language Selection Screen

.. _reporting_an_issue:

Report an Issue
^^^^^^^^^^^^^^^

Use the **Report an Issue** action to submit problems directly from the **phone.systems™** app to the support team.

To report an issue:

    1. Tap the **top bar** to open the drop-down menu.
    2. Tap the |settings| icon to open the **Settings** menu.
    3. Select **Report an Issue**.
    4. Fill in your **email address** and **describe the issue**, including:

       - What steps you took before the issue occurred.
       - Any error messages shown.
       - What you expected to happen and what actually happened.

    5. Click **Send** to submit the report.

.. note::
   Providing detailed information helps the support team resolve your issue faster.

.. grid:: 1 1 1 4

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/reporting1.png
           :figclass: align-center
           :alt: Step 1: Open the drop-down menu

           **Fig. 17.** Open the Drop-Down Menu

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/reporting2.png
           :figclass: align-center
           :alt: Step 2: Open the settings menu

           **Fig. 18.** Open the Settings Menu

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/reporting3.png
           :figclass: align-center
           :alt: Step 3: Select Report an issue

           **Fig. 19.** Select Report an Issue

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/reporting4.png
           :figclass: align-center
           :alt: Step 4: Input report data

           **Fig. 20.** Enter Email and Issue Description

.. _ps3_application_settings_general_signout:

Sign Out
^^^^^^^^

    1. Tap the **Sign Out** button from the settings menu.
    2. On the confirmation screen, click **Sign Out**.

.. caution::

   Before signing out, ensure you have access to your activation key or QR code in case you need to reconnect.

.. grid:: 1 1 1 2

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/signout1.png
           :figclass: align-center
           :alt: Sign Out Button

           **Fig. 21.** Sign Out Button

   .. grid-item::
      :class: text-center

        .. figure:: https://doc.didww.com/_images/signout2.png
           :figclass: align-center
           :alt: Sign Out Confirmation

           **Fig. 22.** Sign Out Confirmation

.. |settings| image:: /phone-systems/assets/img/guide-v2/app/settings.png
   :class: inline-img no-shadow
   :width: 24px
   :height: 24px

.. |edit| image:: /phone-systems/assets/img/guide-v2/app/edit_avatar.png
   :class: inline-img no-shadow
   :width: 30px
   :height: 30px

.. raw:: html

   <style>

    .text-center {
         text-align: center;
    }

   </style>


.. _ps3_additional_resources:

Additional Resources
========================

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`device-desktop` **Install phone.systems™ App on Linux**
      :link: repositories
      :link-type: doc
      :text-align: left

      Install the phone.systems™ app on Debian or Ubuntu using the official repository.

   .. grid-item-card:: :octicon:`plug` **phone.systems™ App Integration Protocols**
      :link: integration-protocols
      :link-type: doc
      :text-align: left

      Learn to use standard and custom URL protocols to integrate phone.systems™, automate tasks, and perform actions like calling or opening the dial pad from links.

.. toctree::
  :maxdepth: 1
  :hidden:

  Install phone.systems™ app on Linux <repositories.rst>
  phone.systems™ app integration protocols <integration-protocols.rst>


.. _ps3_application_repositories:

===================================
Install phone.systems™ app on Linux
===================================

To install the **phone.systems™** app on a **Linux** system, you first need to configure the package repository. This ensures secure and seamless installation, as well as future updates.

The following steps will guide you through setting up the repository and installing the app on **Debian** or **Ubuntu** distributions.

----

.. raw:: html

   <br>

Supported distributions and versions
======================================

The phone.systems™ app is available for the following **Linux** distributions and versions:

    .. list-table::
       :widths: 25 25 25
       :header-rows: 1

       * - **Distribution**
         - **Version**
         - **Platform**
       * - :ref:`Debian <install_ps3_app_on_debian>`
         - 12.x (Bookworm), 13.x (Trixie)
         - x86_64 / amd64
       * - :ref:`Ubuntu <install_ps3_app_on_ubuntu>`
         - 24.04 (Noble)
         - x86_64 / amd64

----

.. raw:: html

   <br>

Set up the repository and install phone.systems™ app
====================================================

To install **phone.systems™** on a **Debian** or **Ubuntu** Linux systems, follow these steps:

.. raw:: html

   <br>

.. _install_ps3_app_on_debian:

Install on Debian
------------------

Follow these steps to install phone.systems™ on **Debian 12 (Bookworm) or Debian 13 (Trixie)**.

.. raw:: html

   <br>

Step 1: Install required dependencies
''''''''''''''''''''''''''''''''''''''''''

Run the following command to install the required system dependencies:

    .. code-block:: console

        sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring

Step 2: Import the official signing key
''''''''''''''''''''''''''''''''''''''''''''

To verify package authenticity and allow `apt` to trust the repository, import the phone.systems™ signing key:

    .. code-block:: console

        sudo curl -fsSL https://pkg.phone.systems/debian/key.asc -o /etc/apt/keyrings/phone_systems.asc

Step 3: Add the phone.systems™ repository
''''''''''''''''''''''''''''''''''''''''''''

Run the following command to add the phone.systems™ repository:

    .. code-block:: console

        echo "deb [signed-by=/etc/apt/keyrings/phone_systems.asc] \
        https://pkg.phone.systems/debian `lsb_release -cs` main" \
            | sudo tee /etc/apt/sources.list.d/phone_systems.list

Step 4: Install the phone.systems™ app
''''''''''''''''''''''''''''''''''''''''''''

Update the package list and install the phone.systems™ app:

    .. code-block:: console

        sudo apt update
        sudo apt install phone-systems-mobile

----

.. raw:: html

   <br>

.. _install_ps3_app_on_ubuntu:

Install on Ubuntu
------------------

Follow these steps to install phone.systems™ app on **Ubuntu 24.04 (Noble)**.

.. raw:: html

   <br>

Step 1: Install required dependencies
'''''''''''''''''''''''''''''''''''''

Run the following command to install the required dependencies:

    .. code-block:: console

        sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring

Step 2: Import the official signing key
'''''''''''''''''''''''''''''''''''''''

To allow `apt` to verify package authenticity, import the official phone.systems™ signing key:

    .. code-block:: console

        sudo curl -fsSL https://pkg.phone.systems/debian/key.asc -o /etc/apt/keyrings/phone_systems.asc

Step 3: Add the phone.systems™ repository
'''''''''''''''''''''''''''''''''''''''''

Run the following command to add the phone.systems™ `apt` repository packages to your sources list:

    .. code-block:: console

        echo "deb [signed-by=/etc/apt/keyrings/phone_systems.asc] \
        https://pkg.phone.systems/debian `lsb_release -cs` main" \
            | sudo tee /etc/apt/sources.list.d/phone_systems.list

Step 4: Install the phone.systems™ app
''''''''''''''''''''''''''''''''''''''

Update the package list and install the phone.systems™ app:

    .. code-block:: console

        sudo apt update
        sudo apt install phone-systems-mobile


.. _ps3_appplication_integration_protocols:

.. |br| raw:: html

   <br />

========================================
phone.systems™ App Integration Protocols
========================================

Integration protocols are predefined rules that enable seamless communication between applications. In phone.systems™, these URL-based commands let systems, scripts, or users perform specific actions such as initiating calls, entering numbers in the dial pad, or authenticating the app.

Benefits of integration protocols:
    * Automate repetitive tasks to save time and reduce errors.
    * Enable one-click actions to boost productivity.
    * Link the phone.systems™ app with other tools to create custom workflows.
    * Simplify user experience by reducing manual steps.

For example, a **CRM system** can use these protocols to initiate calls directly from a customer’s profile. They can also be embedded in links, emails, or scripts to streamline communication workflows.

----

.. raw:: html

   <br>

phone.systems™ App Supported URL Protocols
==========================================

The phone.systems™ app supports both **industry-standard** and **custom URL protocols** for initiating calls and performing app-specific functions.

.. raw:: html

   <br>

Industry-Standard Protocols
-------------------------------

The following protocols are commonly used for initiating calls through web links:

    .. list-table:: Supported Industry Protocols
       :header-rows: 1
       :widths: 15 14 5

       * - **Protocol URL**
         - **Description**
         - **Example**
       * - .. code-block:: none

              callto:some_number

         - Used to initiate a call using a hyperlink.
         - .. raw:: html

                <a href="callto:12124613663">callto:12124613663</a>
       * - .. code-block:: none

                tel:some_number

         - Used to initiate a call using a hyperlink.
         - .. raw:: html

                <a href="tel:12124613663">tel:12124613663</a>

.. raw:: html

   <br>

phone.systems™ Custom URL Protocols
-------------------------------------

In addition to standard protocols, phone.systems™ provides unique URL-based protocols for extended functionality:

    .. list-table:: phone.systems™ Unique Protocols
       :header-rows: 1
       :widths: 11 10 4

       * - **Protocol URL**
         - **Description**
         - **Example**
       * - .. code-block:: none

                phone.systems://dialpad?number=some_number
         - Opens the dial pad with a pre-filled number.
         - .. raw:: html

                <a href="phone.systems://dialpad?number=12124613663">Open Dialpad</a>
       * - .. code-block:: none

                phone.systems://call?number=some_number
         - Initiates a call using the phone.systems™ app.
         - .. raw:: html

                <a href="phone.systems://call?number=12124613663">Initiate Call</a>
       * - .. code-block:: none

                phone.systems://authenticate?code=some_code
         - Authenticates the phone.systems™ app with a provided code.
         - .. raw:: html

                <a href="phone.systems://authenticate?code=3:eyJhbGciOiJIUzg1NiJ9.eyJzdWIiOiI5ZWYyNTBmNy0wYzBjLTQ2OTYtYmRkZSf2MTNjYjlhN2VlZTQiLCJleH8iOjE3MzUyMDIzMTN9.UZdvuLdB1nSAKI45MXgQOFG3WF8jpGA-QNb6OcVhjwc">Authenticate</a>

.. note:: phone.systems™ URL protocols are considered deep links and must be clickable to function properly. When pasted into a browser’s search bar, the URL can be automatically modified, typically by adding a ``https://`` prefix, which may result in an incorrect URL. To avoid this issue, ensure the URLs are clicked to open the app, rather than being pasted directly into a browser's address bar.

----

.. raw:: html

   <br>

Setting phone.systems™ as the Default App
=========================================

To use URL protocols, set phone.systems™ as the default app for handling `tel` and `callto` protocols. Follow the steps for your operating system:

macOS
-----

To set phone.systems™ for ``tel`` or ``callto`` protocols:

    1. Open **FaceTime**.
    2. Go to **Preferences**.
    3. In **Default for calls**, select **phone.systems™**.

    .. tip:: If **phone.systems™** does not appear in the dropdown, ensure the app is installed and up to date. Alternatively, use a third-party tool like **RCDefaultApp** to assign the ``callto`` protocol to **phone.systems™**.

.. raw:: html

   <br>

Windows
----------

To set phone.systems™ for ``tel`` or ``callto`` protocols:

    1. Open **Settings**.
    2. Go to **Apps > Default Apps**.
    3. Select **Choose default apps by protocol**.
    4. Assign **phone.systems™** to the ``tel`` and ``callto`` protocols.

.. raw:: html

   <br>

Android
----------

To enable all supported protocols:

    1. Open the phone.systems™ app **Settings**.
    2. Select **Open by default**.
    3. Under **Supported links**, choose **phone.systems™**.

.. raw:: html

   <br>

iOS
-----

To set phone.systems™ for the ``tel`` protocol:

    1. Use the Safari browser.
    2. Long press a link with the ``tel`` protocol.
    3. Select **phone.systems™** as the app.

    .. important::

        - The `tel` protocol does not work in Chrome on iOS. Use **Safari** instead.
        - For other protocols use **Chrome** Browser.


:html_theme.sidebar_secondary.remove: true

================
Introduction
================

Connect your DIDWW voice and messaging services to the platforms, PBX systems, and automation tools your team already uses. This section contains setup guides for each supported integration, covering SIP trunk configuration, DID assignment, and where applicable, API-based provisioning and messaging.

All Integrations
-----------------

.. grid:: 1 1 2 4
   :gutter: 4
   :padding: 0

   .. grid-item-card::
      :link: elevenlabs/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/elevenlabs.svg" alt="ElevenLabs">
           </span>
           <span class="integration-name">ElevenLabs</span>
         </div>

   .. grid-item-card::
      :link: retell-ai/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

          <div class="integration-row">
            <span class="integration-icon">
              <img src="../_static/icons/retellai.svg" alt="Retell AI">
            </span>
            <span class="integration-name">Retell AI</span>
          </div>

   .. grid-item-card::
      :link: vapi/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

          <div class="integration-row">
            <span class="integration-icon">
              <img src="../_static/icons/vapi.svg" alt="Vapi">
            </span>
            <span class="integration-name">Vapi</span>
          </div>

   .. grid-item-card::
      :link: ms-teams/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/microsoft-teams.png" alt="Microsoft Teams">
           </span>
           <span class="integration-name">Microsoft Teams</span>
         </div>

   .. grid-item-card::
      :link: 3cx/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/3CX.svg" alt="3cx">
           </span>
           <span class="integration-name">3CX</span>
         </div>

   .. grid-item-card::
      :link: amazon/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/aws.svg" alt="Amazon Chime">
           </span>
           <span class="integration-name">Amazon Chime SDK</span>
         </div>

   .. grid-item-card::
      :link: yeastar/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/yeastar.svg" alt="Yeastar">
           </span>
           <span class="integration-name">Yeastar P-Series PBX</span>
         </div>

   .. grid-item-card::
      :link: asterisk/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/asterisk.png" alt="Asterisk">
           </span>
           <span class="integration-name">Asterisk</span>
         </div>

   .. grid-item-card::
      :link: freeswitch/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/freeswitch.webp" alt="FreeSWITCH">
           </span>
           <span class="integration-name">FreeSWITCH</span>
         </div>

   .. grid-item-card::
      :link: twilio/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/twilio.png" alt="Twilio">
           </span>
           <span class="integration-name">Twilio</span>
         </div>

   .. grid-item-card::
      :link: avaya/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/avaya.svg" alt="Avaya">
           </span>
           <span class="integration-name">Avaya</span>
         </div>

   .. grid-item-card::
      :link: ribbon/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/ribbon.svg" alt="Ribbon">
           </span>
           <span class="integration-name">Ribbon</span>
         </div>

   .. grid-item-card::
      :link: telinta/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/telinta.png" alt="Telinta">
           </span>
           <span class="integration-name">Telinta</span>
         </div>

   .. grid-item-card::
      :link: zapier/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/zapier.png" alt="Zapier">
           </span>
           <span class="integration-name">Zapier</span>
         </div>

   .. grid-item-card::
      :link: pabbly/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/pabbly.svg" alt="Pabbly">
           </span>
           <span class="integration-name">Pabbly</span>
         </div>

   .. grid-item-card::
      :link: genesys/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/genesys.svg" alt="Genesys">
           </span>
           <span class="integration-name">Genesys Cloud CX</span>
         </div>

   .. grid-item-card::
      :link: freepbx/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/freepbx.png" alt="FreePBX">
           </span>
           <span class="integration-name">FreePBX</span>
         </div>

   .. grid-item-card::
      :link: odoo/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/odoo.jpeg" alt="Odoo">
           </span>
           <span class="integration-name">Odoo</span>
         </div>

   .. grid-item-card::
      :link: didww-prometheus-exporter/index
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-integration

      .. raw:: html

         <div class="integration-row">
           <span class="integration-icon">
             <img src="../_static/icons/prometheus-exporter.svg" alt="prometheus-exporter">
           </span>
           <span class="integration-name">Prometheus</span>
         </div>

.. toctree::
  :maxdepth: 1
  :hidden:

  elevenlabs/index
  retell-ai/index
  vapi/index
  ms-teams/index
  3cx/index
  amazon/index
  yeastar/index
  asterisk/index
  freeswitch/index
  Twilio <twilio/index.rst>
  avaya/index
  ribbon/index
  telinta/index
  zapier/index
  pabbly/index
  genesys/index
  freepbx/index
  odoo/index
  didww-prometheus-exporter/index.rst


.. |br| raw:: html

  <br>

.. _elevenlabs_integration:

==========
ElevenLabs
==========

Use **ElevenAgents** by `ElevenLabs <https://elevenlabs.io/>`_ with **DIDWW SIP Trunking** to create, deploy, and scale **AI-powered conversational agents**.
Connect DIDWW SIP trunks to ElevenAgents to route incoming calls, place outbound calls, and deliver natural conversations over standard phone lines.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Route incoming calls from DIDWW numbers to ElevenAgents.
      - Connect callers to AI voice agents for real-time conversations.
      - Import existing DIDWW numbers into ElevenLabs.

   .. grid-item::
      :class: left-align-block

      - Place outbound calls through DIDWW Outbound Trunks.
      - Transfer active calls from AI agents to live people.
      - Assign ElevenAgents Voice Agents to individual DIDWW numbers.

----

.. _elevenlabs_inbound:

1. Route Incoming Calls to ElevenAgents
=======================================

Configure an Inbound SIP Trunk in the DIDWW User Panel to send incoming calls from your DIDWW numbers to ElevenAgents.
This trunk defines the SIP path that delivers calls to your ElevenAgents Voice Agent.

Before You Begin
-----------------

    - An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
    - At least one active **DID number** with capacity to receive incoming calls is required. `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_.

Step 1: Create New SIP Trunk
----------------------------

    1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
    2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/inbound1.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Fig. 1. Creating a new inbound SIP trunk

Step 2: Configure General SIP Trunk Settings
--------------------------------------------

In the Create Inbound SIP Trunk form, enter the main requirements to route the calls to ElevenAgents.

    1. In the **General** tab, enter a descriptive **Name** for the trunk (e.g., ``ElevenLabs``).
    2. Select **Static Endpoint**.
    3. Enter the ElevenLabs SIP endpoint hostname in **Host**. For most accounts, this is ``sip.rtc.elevenlabs.io``. If your account uses a different region or environment, check your ElevenLabs dashboard or documentation to confirm the correct host.
    4. In **Transport**, select **TCP**, **UDP**, or **TLS**.
    5. In **Port**, enter the port that corresponds to the selected transport:

       - ``5060`` for **TCP** or **UDP**
       - ``5061`` for **TLS**

.. important::

   - ElevenLabs enterprise accounts can use static SIP host domains. For details, see the `ElevenLabs SIP Trunking documentation <https://elevenlabs.io/docs/agents-platform/phone-numbers/sip-trunking>`_.

.. figure:: https://doc.didww.com/_images/generalsettings.png
   :figclass: align-center
   :alt: SIP trunk configured with TCP transport

   Fig. 2. SIP trunk configured with TCP transport and Port 5060

.. _elevenlabs_create_inbound_trunk_authentication:

Step 3: Configure Authentication (Optional)
---------------------------------------------

Inbound SIP trunk authentication is **optional**. Enable it only if your setup requires username and password verification for inbound SIP calls.

    1. Open the **Authorization** tab.
    2. Turn on **Enable Authorization**.
    3. Enter the authentication details:

       - **Auth User** – The username provided by your system.
       - **Auth Password** – The corresponding password.

    .. figure:: https://doc.didww.com/_images/inbound4.png
      :figclass: align-center
      :alt: Authentication settings for inbound SIP trunk

      Fig. 3. Authentication settings for inbound SIP trunk

.. _elevenlabs_create_inbound_trunk_media_encryption:

Step 4: Configure SRTP (Optional)
---------------------------------

Media encryption (**SRTP**) is **optional**. This feature improves security by encrypting RTP traffic.

    1. Open the **Media & DTMF** tab.
    2. In **SRTP Mode**, choose the preferred SRTP method from the list:

        - **SRTP SDES** – Uses Session Description Protocol Security Descriptions.
        - **SRTP DTLS** – Uses Datagram Transport Layer Security for key negotiation.
        - **SRTP ZRTP** – Uses the ZRTP key agreement protocol.

    .. figure:: https://doc.didww.com/_images/inbound5.png
      :figclass: align-center
      :alt: SRTP Mode settings for inbound SIP trunk

      Fig. 4. SRTP Mode settings for inbound SIP trunk

.. _elevenlabs_create_inbound_trunk:

Step 5: Click Create and Save Inbound SIP Trunk Configuration
-------------------------------------------------------------

When all required fields in the Create Inbound SIP Trunk are filled, click **Create** to save your inbound SIP trunk.

.. note:: For advanced SIP trunk configuration, see :ref:`Advanced Inbound SIP Trunk documentation <user_panel_sipin_trunk_advanced_configuration>`.

.. figure:: https://doc.didww.com/_images/inbound6.png
   :figclass: align-center
   :alt: Inbound SIP trunk created

   Fig. 5. Create the Inbound SIP Trunk

Step 6: Assign Inbound SIP Trunk to Your DID Numbers
----------------------------------------------------

After creating the Inbound SIP Trunk for ElevenAgents, assign it to the DID number(s) that will deliver incoming calls to your ElevenAgents Voice Agent.

    1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
    2. Select the DID number(s) you want to assign to the inbound SIP trunk.
    3. At the bottom of the page, click **Batch Actions > Update Trunks**.

    .. figure:: https://doc.didww.com/_images/inbound7.png
       :figclass: align-center
       :alt: Assigning a SIP trunk to DID numbers

       Fig. 6. Selecting **Update Trunks** from the Batch Actions menu

    4. From the dropdown menu, choose the **ElevenLabs SIP trunk** you created earlier.
    5. Click **Confirm** to apply the changes.

    .. figure:: https://doc.didww.com/_images/inbound8.png
       :figclass: align-center
       :alt: Assigning a SIP trunk to DID numbers

       Fig. 7. Assigning the newly created SIP trunk to the selected DID(s)

----

.. raw:: html

    <br>

.. _elevenlabs_outbound:

2. Enable Outbound Calling from ElevenAgents Through DIDWW
==========================================================

Configure an Outbound SIP Trunk in the DIDWW User Panel to allow ElevenAgents to place outbound calls through DIDWW.
This trunk provides the SIP credentials and routing settings required for outbound calls to external phone numbers.

.. important::
   When configuring outbound calling with AI agents, ensure compliance with the **Telephone Consumer Protection Act (TCPA)** and related regulations. |br|
   For details on consent types and legal requirements, refer to the official
   `ElevenLabs TCPA Compliance Guide <https://elevenlabs.io/docs/agents-platform/legal/tcpa#types-of-consent-required>`_.

Before You Begin
-----------------

Access to **DIDWW Outbound Trunks** is required for making outbound calls. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

Step 1: Create New Outbound Voice Trunk
---------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/outbound1.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Fig. 8. Creating a new outbound SIP trunk

Step 2: Configure Authentication
----------------------------------------

1. Update the **Friendly Name** (e.g., ``ElevenLabs``).
2. Keep the default **Credentials & IP-based** authentication method selected. The SIP digest credentials (username and password) will be provided after the trunk is created.
3. In **Allowed SIP IP addresses**, enter the public IP address or subnet from which ElevenLabs will send outbound SIP traffic.

.. note::
   ElevenLabs SIP traffic originates from IP ranges that may vary depending on your plan or region. |br|
   Refer to the official ElevenLabs documentation for the most up-to-date information:
   `ElevenLabs SIP Trunking IP Information <https://elevenlabs.io/docs/agents-platform/phone-numbers/sip-trunking>`_

.. warning::
   You can allow all traffic by adding ``0.0.0.0/0``, which removes all IP restrictions. |br|
   Although SIP Digest Authentication will still verify requests using valid credentials, this setup is not recommended. |br|
   Restrict access to known ElevenLabs IPs whenever possible.

.. figure:: https://doc.didww.com/_images/outbound2.1.png
   :figclass: align-center
   :alt: Configuring allowed SIP IP addresses for outbound trunk authentication

   Fig. 9. Entering allowed SIP IP addresses for outbound authentication

.. _elevenlabs_create_outbound_trunk_media_encryption:

Step 3: Configure Media Encryption (Optional)
---------------------------------------------

Media encryption (**SRTP**) is **optional**. This feature improves security by encrypting RTP traffic.

    1. Expand the **Media** configuration section in the configuration form.
    2. In the **Media encryption mode** field, choose the preferred SRTP method from the list:

        - **SRTP SDES** – Uses Session Description Protocol Security Descriptions.
        - **SRTP DTLS** – Uses Datagram Transport Layer Security for key negotiation.
        - **ZRTP** – Uses ZRTP key agreement protocol.

    .. figure:: https://doc.didww.com/_images/outbound3.png
       :figclass: align-center
       :alt: Media encryption settings for outbound SIP trunk

       Fig. 10. Media encryption settings for outbound SIP trunk

.. _elevenlabs_create_outbound_trunk:

Step 4: Click Create and Save Outbound SIP Trunk Configuration
------------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk are filled, click **Create** to save your outbound SIP trunk.

.. note:: For advanced outbound SIP trunk configuration, see :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/outbound4.png
   :figclass: align-center
   :alt: Outbound SIP trunk created

   Fig. 11. Outbound SIP trunk created and ready for use

.. _elevenlabs_create_outbound_trunk_copy_credentials:

Step 5: View Outbound Trunk Credentials
---------------------------------------

When outbound trunk is created you can view its credentials by selecting the key icon in the Credentials column on the Outbound Trunks page.

    1. Go to **Voice > Outbound Trunks**.
    2. Locate your outbound trunk and click the **key icon** in the **Credentials** column.
    3. The trunk credentials will appear, showing the **Username** and **Password** (click the **eye icon** to reveal the password).
    4. Enter these credentials in the **Outbound Configuration** section of your ElevenAgents phone number. See :ref:`Configure Outbound Settings <elevenlabs_configure_outbound_settings>` for details.

.. figure:: https://doc.didww.com/_images/outbound5.png
   :figclass: align-center
   :alt: Accessing outbound trunk credentials

   Fig. 12. Opening the outbound trunk credentials view

----

.. raw:: html

    <br>

.. _elevenlabs_configure_number:

3. Connect DIDWW Numbers to ElevenAgents
========================================

Connect your DIDWW phone numbers to ElevenAgents by configuring the DIDWW SIP trunking details inside ElevenLabs.
This setup imports your existing DIDWW numbers and assigns an ElevenAgents Voice Agent to handle incoming and outgoing calls.

.. note::
   For more information, see the official ElevenLabs `SIP Trunking Guide <https://elevenlabs.io/docs/agents-platform/phone-numbers/sip-trunking>`_.

Before You Begin
-----------------

    - An **ElevenLabs account** with available credits is required to process voice calls through AI agents. `Sign in to ElevenLabs <https://elevenlabs.io/app/sign-in>`_ or `Create ElevenLabs account <https://elevenlabs.io/sign-up>`_ to get started.
    - An active **AI Voice Agent** is required in ElevenAgents. See the `Assistant Setup Guide <https://elevenlabs.io/docs/agents-platform/quickstart#assistant-setup>`_ for instructions.
    - The AI Voice Agent must be **published and live** before it can receive calls or perform actions such as call transfers.

Step 1: Import Number From SIP Trunk
------------------------------------

    1. In the `ElevenLabs User Panel <https://elevenlabs.io/app/agents>`_, open the **Phone Numbers** menu.
    2. Click **Import number** and select **From SIP Trunk**.

.. figure:: https://doc.didww.com/_images/elevenlabs1.png
   :figclass: align-center
   :alt: Importing a phone number from a SIP trunk

   Fig. 13. Starting number import from a SIP trunk

Step 2: Enter Your Phone Number
-------------------------------------

    1. Update the **Label** (e.g., ``DIDWW Phone Number``).
    2. Paste your **Phone Number** in E.164 format without the ``+`` symbol (e.g., ``12132214943``).

.. note::
   ElevenLabs requires phone numbers to be globally unique across all workspaces. |br|
   If a phone number (DID) was previously registered in ElevenLabs by another user, it cannot be registered again, even if it has been reassigned to a new customer. |br|
   This limitation is enforced by ElevenLabs and cannot be controlled or verified by DIDWW.

.. figure:: https://doc.didww.com/_images/elevenlabs2.png
   :figclass: align-center
   :alt: Adding label and phone number

   Fig. 14. Defining the DIDWW phone number details

Step 3: Configure Inbound Settings
----------------------------------

These settings control how ElevenAgents handles incoming calls from your DIDWW numbers. Configure them to match your DIDWW Inbound SIP Trunk setup.

    1. Set **Media Encryption** to **Allow**, **Disable**, or **Require**, based on your settings in :ref:`Create Inbound SIP Trunk – Step 4: Media Encryption <elevenlabs_create_inbound_trunk_media_encryption>`.
    2. Enter the **SIP Username** and **Password** from your DIDWW trunk credentials, if SIP digest authentication was enabled during :ref:`Create Inbound SIP Trunk - Step 3: Configure Authentication <elevenlabs_create_inbound_trunk_authentication>`.

.. figure:: https://doc.didww.com/_images/elevenlabs3.png
   :figclass: align-center
   :alt: Inbound SIP trunk configuration

   Fig. 15. Configuring inbound SIP settings

.. _elevenlabs_configure_outbound_settings:

Step 4: Configure Outbound Settings
-----------------------------------

These settings define how ElevenAgents sends outbound SIP traffic to DIDWW. Configure them to match your DIDWW Outbound SIP Trunk setup.

    1. Enter the **Address** (:ref:`DIDWW Outbound Trunk Signaling Endpoints <voice-out-signaling-endpoints>`).
    2. Select **Transport Type** – **TCP** or **TLS**, depending on your setup.
    3. Set **Media Encryption** to **Allow**, **Disable**, or **Require**, based on your configuration in :ref:`Create Outbound SIP Trunk – Step 3: Media Encryption <elevenlabs_create_outbound_trunk_media_encryption>`.
    4. Enter the **Username** and **Password** copied from :ref:`Create Outbound SIP Trunk – Step 5: View Outbound Trunk Credentials <elevenlabs_create_outbound_trunk_copy_credentials>`.

.. figure:: https://doc.didww.com/_images/elevenlabs4.png
   :figclass: align-center
   :alt: Outbound SIP trunk configuration

   Fig. 16. Configuring outbound SIP settings

Step 5: Import Your Phone Number
-----------------------------------------------

When the main phone number configuration is complete, click **Import** to add your DIDWW number to ElevenAgents.

.. note:: To receive inbound calls, you only need to enter your **DIDWW phone number**.

.. figure:: https://doc.didww.com/_images/elevenlabs5.png
   :figclass: align-center
   :alt: Completed SIP trunk configuration

   Fig. 17. Successfully imported phone number and activated SIP trunk

Step 6: Assign Voice Agent
----------------------------

To complete the setup, assign an existing **ElevenAgents Voice Agent** to your imported DIDWW phone number.
When someone calls your DID number, this agent will answer and manage the conversation.

    1. Open the **Edit** page for your imported phone number in the **Phone Numbers** section (click the number to open it).
    2. In the **Agent** field, select the **Voice Agent** you want to handle inbound calls from the dropdown list.

.. note::

   For more information on creating or managing agents, see the `ElevenLabs Quickstart Guide <https://elevenlabs.io/docs/agents-platform/quickstart>`_.

.. figure:: https://doc.didww.com/_images/elevenlabs6.png
   :figclass: align-center
   :alt: Assigning a Voice Agent to the imported phone number

   Fig. 18. Assigning a Voice Agent to handle calls from the DIDWW number

Step 7: Make a Test Call to Your DIDWW Number
---------------------------------------------

Place a test call to your **DIDWW phone number** to confirm that inbound calls are correctly forwarded to the **ElevenAgents SIP URI**.
The assigned **Voice Agent** should answer and handle the call.

Verify that SIP signaling, authentication, and media encryption (if enabled) are functioning as expected.

.. note::
   You can review call activity and verify call status or error codes in the DIDWW **Inbound Call Logs**.
   See :ref:`Inbound Call Logs <inbound_cdr_logs>` for more details.

.. raw:: html

    <br>

Additional Resources
==========================================

.. card:: **Configure AI-to-Live Agent Call Transfers**
   :link: elevenlabs_use_cases_transfer
   :link-type: ref

   Step-by-step guide on setting up your ElevenAgents AI agent to transfer active calls to a live person using SIP REFER via DIDWW trunks.

.. toctree::
  :maxdepth: 1
  :hidden:

  Configure AI-to-Live Agent Call Transfers <ai-to-liveagent-call-transfers.rst>

.. raw:: html

    <br>


.. |br| raw:: html

  <br>

.. _elevenlabs_use_cases_transfer:

Configure AI-to-Live Agent Call Transfers
=========================================

ElevenAgents provides a built-in feature that allows its AI Agent to transfer an active, answered call to a live human agent. This is achieved using in-dialog :ref:`SIP REFER <call_redirection_refer>` signaling, where the AI Agent issues a REFER request during the call to redirect the caller to another destination.

When the transfer is triggered, ElevenAgents sends a SIP REFER request to DIDWW. After validating the request, DIDWW initiates a new outbound call to the live agent using your configured outbound trunk. To ensure this process works reliably, both the inbound and outbound SIP trunks must be correctly configured, and ElevenAgents must be set up to authenticate with DIDWW and send SIP REFER requests.

.. note::
   Ensure that both your inbound and outbound SIP trunks are fully operational before beginning this configuration. See :ref:`elevenlabs_inbound` and :ref:`elevenlabs_outbound` for setup instructions.

----

.. raw:: html

    <br>

.. _elevenlabs_call_transfer_outbound_trunk_configuration:

1. Configure Outbound SIP Trunk
-------------------------------

To enable the **SIP REFER** transfer, the outbound trunk must be configured to accept signaling from **DIDWW Inbound SIP IPs**.
This ensures that when a call is transferred, DIDWW can initiate a new outbound call (to the live agent) using the same trunk, authenticated with the credentials from your inbound trunk.

.. raw:: html

    <br>

Before You Begin
^^^^^^^^^^^^^^^^

At least one :ref:`Outbound Trunk <elevenlabs_outbound>` is required, with **Authentication method** set to **Credentials & IP-Based**. |br|

.. raw:: html

    <br>

Step 1: Edit Outbound SIP Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, open the **Voice** section from the left navigation menu.
2. Select **Outbound Trunks**.
3. Locate your **ElevenLabs** trunk in the list.
4. Click the trunk name or the Actions (⋯) icon, then select **Edit**.

.. figure:: https://doc.didww.com/_images/edit_outbound_trunk_elevenlabs.png
   :figclass: align-center
   :alt: Editing the Outbound Trunk for ElevenLabs AI-to-Agent Transfers

   Fig. 1. Editing the Outbound Trunk for ElevenLabs AI-to-Agent Transfers

.. _elevenlabs_call_transfer_outbound_trunk_configuration_step2:

Step 2: Configure Allowed SIP IP Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the **Edit Outbound Trunk** window, locate the **Allowed SIP IP addresses** field.
2. Add :ref:`DIDWW inbound SIP IPs <service_did_sip>`, such as IPv4 ``46.19.210.14`` and IPv6 ``2a01:ad00:2:14::14``, and ensure the correct **ElevenLabs SIP IPs** are also included.
3. Click **Submit** to save the changes.

.. note::
   ElevenLabs SIP traffic originates from IP ranges that may vary depending on your plan or region. |br|
   Refer to the official ElevenLabs documentation for the most up-to-date information:
   `ElevenLabs SIP Trunking IP Information <https://elevenlabs.io/docs/agents-platform/phone-numbers/sip-trunking>`_

.. warning::
   You can allow all traffic by adding ``0.0.0.0/0``, which removes all IP restrictions. |br|
   Although SIP Digest Authentication will still verify requests using valid credentials, this configuration is **not recommended**. |br|
   Always restrict access to known ElevenLabs IPs whenever possible.

.. figure:: https://doc.didww.com/_images/uc1.png
   :figclass: align-center
   :alt: Allowing inbound DIDWW SIP IPs on the outbound trunk

   Fig. 2. Allowing inbound DIDWW SIP IPs on the outbound trunk

.. _elevenlabs_call_transfer_outbound_trunk_copy_credentials:

Step 3: Copy Credentials From Outbound Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Copy the outbound trunk authentication credentials before configuring the inbound trunk. Keep these credentials available for the inbound trunk authorization and ElevenAgents configuration steps.

1. On the `Outbound Trunks <https://my.didww.com/#/outbound_trunks>`_ page, locate your **ElevenLabs** outbound trunk.
2. Click the **key icon** under the **Credentials** column to open the **Credentials** window.

.. figure:: https://doc.didww.com/_images/outbound5.png
   :figclass: align-center
   :alt: Opening the Outbound Trunk Credentials in the DIDWW User Panel

   Fig. 3. Opening the Outbound Trunk Credentials in the DIDWW User Panel

3. In the **Credentials** window, copy the **Username** and **Password**. Click the **eye icon** to reveal the password if it is hidden.

.. figure:: https://doc.didww.com/_images/3copy_out_credentials2.png
   :figclass: align-center
   :alt: Copying the Outbound Trunk Username and Password

   Fig. 4. Copying the Outbound Trunk Username and Password

----

.. raw:: html

    <br>

.. _elevenlabs_call_transfer_inbound_trunk_configuration:

2. Configure Inbound SIP Trunk
------------------------------

To enable the **SIP REFER** transfer process, the inbound trunk must be configured to accept and authenticate in-dialog REFER requests from **ElevenAgents** through DIDWW.
This ensures that when an active call is transferred, DIDWW can validate the REFER request using your inbound trunk credentials and then initiate a new outbound call to the live agent via your **Outbound Trunk**.

.. raw:: html

    <br>

Before You Begin
^^^^^^^^^^^^^^^^

At least one :ref:`Inbound SIP Trunk <elevenlabs_inbound>` is required. This trunk will be used to receive inbound calls from **ElevenLabs** and must be properly linked to your **Outbound Trunk** for SIP REFER call transfers to function correctly. Have the :ref:`outbound trunk credentials <elevenlabs_call_transfer_outbound_trunk_copy_credentials>` available before continuing.

.. raw:: html

    <br>

Step 1: Edit Inbound SIP Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, open the **Voice** section from the left-hand navigation menu.
2. Select **Inbound Trunks**.
3. Locate your **ElevenLabs** inbound trunk in the list.
4. Click the **Actions (⋯)** icon, then select **Edit**.

.. figure:: https://doc.didww.com/_images/edit_inbound_trunk_elevenlabs.png
   :figclass: align-center
   :alt: Editing the Inbound Trunk for ElevenLabs AI-to-Agent Transfers

   Fig. 5. Editing the Inbound Trunk for ElevenLabs AI-to-Agent Transfers

Step 2: Configure the Network Protocol
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. important::

   The **Network protocol** setting in your inbound trunk must **match** the configuration used in your outbound trunk.
   This ensures proper communication between trunks during **SIP REFER** call transfers. |br|
   For example, if your outbound trunk is configured for **IPv4 only**, the inbound trunk must also use **IPv4 only**.
   A mismatch between IP versions will prevent call transfers from completing successfully.

1. In the **General** tab of the **Edit Inbound SIP Trunk** page, locate **Network Protocol**.
2. Select the same IP version as configured in your outbound trunk, as described in :ref:`Step 2 of the Outbound Trunk setup <elevenlabs_call_transfer_outbound_trunk_configuration_step2>`.

.. figure:: https://doc.didww.com/_images/network_protocol_inbound_sip_trunk.png
   :figclass: align-center
   :alt: Configuring Network Protocol for Inbound SIP Trunk

   **Fig. 6.** Configuring the Network Protocol for the Inbound SIP Trunk (AI-to-Agent Transfer)

Step 3: Add Outbound Trunk Credentials to Inbound Trunk Authorization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Apply the credentials copied from the **Outbound Trunk** to the inbound trunk authorization settings.

1. Open the **Authorization** tab.
2. Turn on **Enable Authorization**.
3. Paste the **Auth User** and **Auth Password** values that you copied from :ref:`Step 3: Copy Credentials From Outbound Trunk <elevenlabs_call_transfer_outbound_trunk_copy_credentials>`.

.. note::
   Enabling authorization ensures that DIDWW validates all SIP REFER requests using the credentials from your outbound trunk. |br|
   This step is required for successful AI-to-Live Agent call transfers between **ElevenLabs** and **DIDWW**.

.. figure:: https://doc.didww.com/_images/4_paste_authentication.png
   :figclass: align-center
   :alt: Inbound SIP Trunk Authorization settings

   Fig. 7. Configuring authorization on the Inbound SIP Trunk

Step 4: Configure Signalling Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To enable in-dialog SIP REFER transfers between inbound and outbound trunks, adjust **Max Transfers** in the **Signalling** tab.

1. In the **Edit Inbound SIP Trunk** page, open the **Signalling** tab.
2. Locate **Max Transfers**.
3. Set this value to **1** or higher to allow in-dialog SIP **REFER** transfers.
4. Click **Submit** to save the configuration.

.. important::
   Setting **Max transfers** to ``0`` disables call transfers.
   To ensure successful AI-to-Live Agent transfers, this value must be at least **1**.

.. figure:: https://doc.didww.com/_images/5_inbound_advanced_settings.png
   :figclass: align-center
   :alt: Inbound SIP Trunk Signalling tab with Max Transfers

   Fig. 8. Inbound SIP Trunk Signalling tab with Max Transfers configured for REFER transfers

----

.. raw:: html

    <br>

.. _elevenlabs_call_transfer_configure_elevenlabs:

3. Configure ElevenAgents
-------------------------

To complete the AI-to-Live Agent transfer setup, you must configure ElevenAgents to authenticate with DIDWW and enable the **Transfer to Number** function within your AI Agent.

.. raw:: html

    <br>

Before You Begin
^^^^^^^^^^^^^^^^

- At least one :ref:`Imported DIDWW Number <elevenlabs_configure_number>` must be available in your **ElevenLabs** account and linked to a valid SIP Trunk connection. |br|
- You will also need the **Outbound SIP Trunk credentials** obtained in :ref:`Step 3: Copy Credentials From Outbound Trunk <elevenlabs_call_transfer_outbound_trunk_copy_credentials>`. |br|

.. raw:: html

    <br>

Step 1: Update SIP Trunk Authentication for Your Phone Number
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To allow **ElevenAgents** to authenticate inbound calls from **DIDWW** and enable call transfers, update the SIP Trunk configuration for your imported DIDWW number.

1. In the ElevenAgents Dashboard, open the **Phone Numbers** menu, or click this direct link: `ElevenLabs Phone Numbers <https://elevenlabs.io/app/agents/phone-numbers>`_.

.. figure:: https://doc.didww.com/_images/uc9.png
   :figclass: align-center
   :alt: Accessing the Phone Numbers section

   Fig. 9. Accessing the Phone Numbers section

2. Select your imported **DID Number**, click on it to open the **Number Details** page, and then click **Edit**.

.. figure:: https://doc.didww.com/_images/uc10.png
   :figclass: align-center
   :alt: Editing the imported DIDWW phone number

   Fig. 10. Editing the imported DIDWW phone number

3. In the Edit SIP trunk form **Inbound Configuration**, under **Authentication (Optional)** section, enter the credentials copied from your DIDWW outbound trunk, as described in :ref:`Step 3: Copy Credentials From Outbound Trunk <elevenlabs_call_transfer_outbound_trunk_copy_credentials>`.

   - **SIP Trunk Username:** Enter the outbound trunk username
   - **SIP Trunk Password:** Enter the outbound trunk password

4. Click **Update** to save the SIP trunk configuration.

.. figure:: https://doc.didww.com/_images/uc11.png
   :figclass: align-center
   :alt: Entering DIDWW SIP trunk authentication credentials in ElevenLabs

   Fig. 11. Configuring inbound SIP authentication using DIDWW credentials

Step 2: Configure Voice Agent
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the ElevenAgents Dashboard, edit any of your existing **Agents** which will be used to transfer the call.

.. figure:: https://doc.didww.com/_images/uc5.png
   :figclass: align-center
   :alt: Selecting the Voice Agent in ElevenLabs

   Fig. 12. Selecting the Voice Agent in the ElevenLabs dashboard

2. Open the **Tools** menu.
3. In the right-side panel, locate the **System tools** section.
4. Find the **Transfer to number** option and enable the setting.
5. Click the **gear icon** next to **Transfer to number** to open its configuration panel.

.. figure:: https://doc.didww.com/_images/uc6.png
   :figclass: align-center
   :alt: Enabling Transfer to number tool

   Fig. 13. Enabling the Transfer to number tool in the ElevenLabs Agent configuration

6. In the **Transfer to Number** settings, locate the **Human Transfer Rules** section and fill in the following details:

   - **Transfer type:** Select ``SIP REFER`` — this defines the transfer method.
   - **Destination type:** Select ``SIP URI`` — specifies the format of the destination address.
   - **SIP URI:** Enter the SIP address where the call should be transferred to a live person, for example: ``sip:+1234567890@fra.eu.out.didww.com``.
   - **Condition:** Enter the condition text that triggers the transfer, for example: ``when a caller asks to be transferred to a live person``.

7. Click **Save** in the **Transfer to Number** settings form to confirm your Human Transfer Rules.

.. figure:: https://doc.didww.com/_images/uc7.png
   :figclass: align-center
   :alt: Saving Transfer to Number tool configuration

   Fig. 14. Saving the Transfer to Number configuration in the rule editor

8. Finally, click **Publish** on the main **Voice Agent** page to apply all changes.

.. important::

   Ensure that your Voice Agent is **published** and shows a **Live** status in ElevenLabs before testing call transfers.
   SIP REFER transfers may fail if the agent is not live.

.. figure:: https://doc.didww.com/_images/uc8.png
   :figclass: align-center
   :alt: Saving the updated Voice Agent configuration

   Fig. 15. Saving the updated Voice Agent configuration

Step 3: Make a Test Call and Verify Call Transfer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once all configurations are complete, perform a test call to ensure that the **AI-to-Live Agent SIP REFER transfer** works correctly.

1. Place a call to your **DIDWW number** that is routed to your **ElevenAgents AI agent**.
2. Interact with the AI Agent and trigger the **transfer condition** (for example, ask “Can I speak to a live agent?”).
3. Confirm that the call is successfully transferred to the live person and two-way audio is established.

.. note::
   Review the :ref:`Inbound <inbound_cdr_logs>` and :ref:`Outbound <outbound_cdr_logs>` **CDR Logs** to verify call flow details and confirm successful completion. |br|
   If you experience any issues during testing or call transfers, please contact **DIDWW Support** at support@didww.com for further assistance.


.. _retell_ai:

=========
Retell AI
=========

Use `Retell AI voice agents <https://www.retellai.com/>`_ with **DIDWW SIP Trunking** to handle inbound and outbound calling over standard phone lines.
Connect your DIDWW SIP trunks with Retell AI to route incoming calls to AI agents, place outbound calls through DIDWW trunks, and manage voice conversations using your existing DIDWW phone numbers.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Route incoming calls from DIDWW numbers to Retell AI agents.
      - Connect callers to AI agents for real-time conversations.
      - Import existing DIDWW numbers into Retell AI.

   .. grid-item::
      :class: left-align-block

      - Place outbound calls through DIDWW Outbound Trunks.
      - Assign inbound and outbound AI agents to DIDWW numbers.
      - Manage voice conversations over standard phone lines.

----

.. _retell_inbound:

1. Route Incoming Calls to Retell AI
====================================

Configure an Inbound SIP Trunk in the DIDWW User Panel to send incoming calls from your DIDWW numbers to Retell AI.
This trunk defines the SIP path that delivers calls to your Retell AI agent.

Before You Begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- At least one active **DID number** with capacity to receive incoming calls is required. `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_.

Step 1: Create New SIP Trunk
----------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/inbound1.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Fig. 1. Creating a new inbound SIP trunk

Step 2: Configure General SIP Trunk Settings
--------------------------------------------

In the Create Inbound SIP Trunk form, enter the main requirements to route the calls to Retell AI.

1. In the **General** tab, enter a descriptive **Name** for the trunk (e.g., ``Retell AI``).
2. Select **Static Endpoint**.
3. In **Host**, enter the Retell AI SIP endpoint hostname: ``sip.retellai.com``.
4. In **Port**, enter the port that corresponds to the transport protocol:

   - ``5060`` for **TCP** or **UDP**
   - ``5061`` for **TLS**

5. In **Transport**, select **TCP**, **UDP**, or **TLS**.

.. figure:: https://doc.didww.com/_images/generalsettings.png
   :figclass: align-center
   :alt: SIP trunk configured for Retell AI

   Fig. 2. SIP trunk configured for Retell AI

.. _retell_create_inbound_trunk:

Step 3: Click Create and Save Inbound SIP Trunk Configuration
-------------------------------------------------------------

When all required fields in the Create Inbound SIP Trunk are filled, click **Create** to save your inbound SIP trunk.

.. note:: For advanced SIP trunk configuration, see :ref:`Advanced Inbound SIP Trunk documentation <user_panel_sipin_trunk_advanced_configuration>`.

.. figure:: https://doc.didww.com/_images/inbound2.png
   :figclass: align-center
   :alt: Create the Inbound SIP Trunk

   Fig. 3. Create the Inbound SIP Trunk

Step 4: Assign Inbound SIP Trunk to Your DID Numbers
----------------------------------------------------

After creating the Inbound SIP Trunk for Retell AI, assign it to the DID number(s) that will deliver incoming calls to your Retell AI agent.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number(s) you want to assign to the inbound SIP trunk.
3. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/inbound3.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 4. Selecting **Update Trunks** from the Batch Actions menu

4. From the dropdown menu, choose the **Retell AI SIP trunk** you created earlier.
5. Click **Confirm** to apply the changes.

.. figure:: https://doc.didww.com/_images/inbound4.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 5. Assigning the newly created SIP trunk to the selected DID(s)

----

.. _retell_outbound:

2. Enable Outbound Calling from Retell AI Through DIDWW
=======================================================

Configure an Outbound SIP Trunk in the DIDWW User Panel to allow Retell AI agents to place outbound calls through DIDWW.
This trunk provides the SIP credentials and routing settings required for outbound calls to external phone numbers.

Before You Begin
----------------

Access to **DIDWW Outbound Trunks** is required for making outbound calls. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

Step 1: Create New Outbound Voice Trunk
---------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/outbound1.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Fig. 6. Creating a new outbound SIP trunk

Step 2: Configure Authentication
--------------------------------

1. Update the **Friendly Name** (e.g., ``Retell AI``).
2. Keep the default **Credentials & IP-based** authentication method selected. The SIP digest credentials (username and password) will be provided after the trunk is created.
3. In **Allowed SIP IP addresses**, enter the public IP address subnet from which Retell AI will send outbound SIP traffic: ``18.98.16.120/30``.

.. note::
   Retell AI SIP traffic originates from IP ranges that may vary depending on your plan or region.
   Refer to the official Retell AI documentation for the most up-to-date information:
   `Retell AI SIP Trunking IP Information <https://docs.retellai.com/deploy/custom-telephony#overview>`_

.. warning::
   You can allow all traffic by adding ``0.0.0.0/0``, which removes all IP restrictions.
   Although SIP Digest Authentication will still verify requests using valid credentials, this setup is not recommended.
   Restrict access to known Retell AI IPs whenever possible.

.. figure:: https://doc.didww.com/_images/outbound2.png
   :figclass: align-center
   :alt: Configuring allowed SIP IP addresses for outbound trunk authentication

   Fig. 7. Entering allowed SIP IP addresses for outbound authentication

.. _retell_create_outbound_trunk:

Step 3: Click Create and Save Outbound SIP Trunk Configuration
--------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk are filled, click **Create** to save your outbound SIP trunk.

.. note:: For advanced outbound SIP trunk configuration, see :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/outbound3.png
   :figclass: align-center
   :alt: Outbound SIP trunk created

   Fig. 8. Outbound SIP trunk created and ready for use

.. _retell_create_outbound_trunk_copy_credentials:

Step 4: View Outbound Trunk Credentials
---------------------------------------

After the outbound trunk is created, you can view its credentials by selecting the key icon in the Credentials column on the Outbound Trunks page.

1. Go to **Voice > Outbound Trunks**.
2. Locate your outbound trunk and click the **key icon** in the **Credentials** column.
3. The trunk credentials will appear, showing the **Username** and **Password** (click the **eye icon** to reveal the password).
4. Copy and securely store these credentials. You will need them later when configuring Retell AI in :ref:`Step 2: Enter SIP Trunking Details <retell_configure_number>`.

.. figure:: https://doc.didww.com/_images/outbound4.png
   :figclass: align-center
   :alt: Accessing outbound trunk credentials

   Fig. 9. Opening the outbound trunk credentials view

----

.. _retell_configure_number:

3. Connect DIDWW Numbers to Retell AI
=====================================

To connect your **DIDWW phone numbers** with **Retell AI**, you’ll configure the DIDWW SIP trunking details inside Retell AI.
This setup imports your existing DID numbers and assigns an **AI agent** to handle both incoming and outgoing calls.

Before You Begin
----------------

- A **Retell AI account** is required. `Sign in to Retell AI <https://www.retellai.com/>`_ or create an account if needed.
- **AI Voice Agent** is required in Retell AI. See the `Retell AI Quickstart Guide <https://docs.retellai.com/get-started/quick-start>`_ for guidance on creating an agent.

Step 1: Open Phone Numbers Page
--------------------------------

1. In the Retell AI dashboard, go to **Deploy > Phone Numbers**.
2. Click the **+** button and select **Connect to your number via SIP trunking**.

.. figure:: https://doc.didww.com/_images/retell1.png
   :figclass: align-center
   :alt: Opening SIP trunking connection in Retell AI

   Fig. 10. Starting SIP trunking configuration in Retell AI

Step 2: Enter SIP Trunking Details
----------------------------------

In the SIP trunk configuration window, enter your DIDWW number and outbound routing details.

1. Enter your **Phone Number** in E.164 format without the ``+`` symbol (e.g., ``18489005419``).
2. In **Termination URI**, enter the DIDWW :ref:`outbound signaling endpoint <voice-out-signaling-endpoints>` (e.g., ``out.didww.com``).
3. Enter the **SIP Trunk Username** and **SIP Trunk Password** from :ref:`Step 4: View Outbound Trunk Credentials <retell_create_outbound_trunk_copy_credentials>`.
4. (Optional) Enter a **Nickname** to identify the number (e.g., ``DIDWW Number``).
5. Select **Outbound Transport** (e.g., ``TCP``).
6. Click **Save** to add your DIDWW number to Retell AI.

After saving, the number will appear in the **Phone Numbers** list.

.. figure:: https://doc.didww.com/_images/retell2.png
   :figclass: align-center
   :alt: Entering SIP trunk configuration details in Retell AI

   Fig. 11. Configuring SIP trunk connection settings

Step 3: Assign Call Agents
---------------------------

Configure which AI agents will handle inbound and outbound calls for your DIDWW number.

1. In the **Inbound Call Agent** section, select the **Call Agent** to handle incoming calls.
2. In the **Outbound Call Agent** section, select the **Call Agent** to use for outbound calls.
3. (Optional) Configure additional options such as allowed countries or webhook settings.

.. figure:: https://doc.didww.com/_images/retell3.png
   :figclass: align-center
   :alt: Configuring inbound and outbound call agents in Retell AI

   Fig. 12. Assigning inbound and outbound AI agents

Step 4: Test the Configuration
------------------------------

Verify that both inbound and outbound calling are working as expected.

1. Place a test call to your **DIDWW DID number** to confirm that inbound calls are routed to Retell AI and handled by the assigned **AI agent**.
2. In the Retell AI dashboard, use the **Make an outbound call** option to place a test call through your DIDWW outbound trunk.

Ensure that calls are successfully established in both directions and that the correct agents are handling the interactions.

.. note::
   You can review call activity and verify call status or error codes in the DIDWW **Inbound** and **Outbound Call Logs**.
   See :ref:`Inbound Call Logs <inbound_cdr_logs>` and :ref:`Outbound Call Logs <outbound_cdr_logs>` for more details.


.. _vapi_integration:

====
Vapi
====

Use `Vapi assistants <https://vapi.ai/>`_ with **DIDWW SIP Trunking** to handle inbound and outbound calling over standard phone lines.
Connect your DIDWW SIP trunks with Vapi to route incoming calls to assistants, place outbound calls through DIDWW trunks, and manage voice conversations using your existing DIDWW phone numbers.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Route incoming calls from DIDWW numbers to Vapi assistants.
      - Connect callers to AI assistants for real-time conversations.
      - Import existing DIDWW numbers into Vapi.

   .. grid-item::
      :class: left-align-block

      - Place outbound calls through DIDWW Outbound Trunks.
      - Transfer active calls to external phone numbers through DIDWW.
      - Assign Vapi assistants to individual DIDWW phone numbers.

----

.. _vapi_inbound:

1. Route Incoming Calls to Vapi
=====================================

Configure an **Inbound SIP Trunk** in the DIDWW User Panel to send incoming calls from your DIDWW numbers to Vapi.
This trunk defines the SIP path that delivers calls to your Vapi assistant and can be configured to support SIP REFER call transfers.

Before You Begin
----------------

- At least one active **DID number** with capacity to receive incoming calls is required. `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_.
- A private Vapi API key is required to use the cURL examples. See `Get Your API Credentials <https://docs.vapi.ai/chat/quickstart#1-get-your-api-credentials>`_ in the Vapi documentation. Keep the key secure and do not expose it in client-side code.

Step 1: Create New SIP Trunk
----------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/inbound1.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Fig. 1. Creating a new inbound SIP trunk

Step 2: Configure General SIP Trunk Settings
--------------------------------------------

In the **General** tab, configure the endpoint and network settings used to deliver calls from DIDWW to Vapi.

1. Enter a descriptive **Name** for the trunk (e.g., ``Vapi``).
2. Select **Static Endpoint**.
3. Enter the **Host** value ``sip.vapi.ai``.
4. Select the **Transport** used by Vapi: **UDP**, **TCP**, or **TLS**.
5. Enter the corresponding **Port**: ``5060`` for **UDP** or **TCP**, or ``5061`` for **TLS**.
6. Set **Network Protocol** to match the IP version used by your DIDWW outbound trunk. If you allowed IPv4 addresses in the outbound trunk, use **Prefer IPv4 over IPv6** or **IPv4 only**.

.. figure:: https://doc.didww.com/_images/generalsettings.png
   :figclass: align-center
   :alt: SIP trunk configured for Vapi

   Fig. 2. SIP trunk configured for Vapi

.. _vapi_create_inbound_trunk:

Step 3: Enable Call Transfer Signaling
--------------------------------------

To support call transfers, configure the inbound trunk to allow in-dialog SIP REFER requests.

1. Open the **Signalling** tab.
2. Set **Max transfers** value to ``1`` or higher.

.. figure:: https://doc.didww.com/_images/inbound_advanced_signaling.png
   :figclass: align-center
   :alt: Enable Call Transfer Signaling

   Fig. 3. Enable Call Transfer Signaling

Step 4: Save the Inbound SIP Trunk
----------------------------------

When all required fields in the Create Inbound SIP Trunk are filled, click **Create** to save your inbound SIP trunk.

.. note:: For advanced SIP trunk configuration, see :ref:`Advanced Inbound SIP Trunk documentation <user_panel_sipin_trunk_advanced_configuration>`.

.. figure:: https://doc.didww.com/_images/inbound2.png
   :figclass: align-center
   :alt: Inbound SIP trunk created

   Fig. 4. Create the Inbound SIP Trunk

Step 5: Locate Your DID Numbers
-------------------------------

After creating the Inbound SIP Trunk for Vapi, locate the DID number(s) that will deliver incoming calls to your Vapi assistant.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Find the DID number(s) you want to connect to Vapi.

.. figure:: https://doc.didww.com/_images/inbound3.png
   :figclass: align-center
   :alt: Locate your DID numbers

   Fig. 5. Locate your DID numbers

Step 6: Assign Inbound SIP Trunk to Your DID Numbers
----------------------------------------------------

1. Select the DID number(s) you located in the previous step.
2. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/inbound3.5.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 6. Selecting **Update Trunks** from the Batch Actions menu

3. From the dropdown menu, choose the **Vapi SIP trunk** you created earlier.
4. Click **Confirm** to apply the changes.

.. figure:: https://doc.didww.com/_images/inbound4.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 7. Assigning the Vapi SIP trunk to the selected DID(s)

----

.. _vapi_outbound:

2. Enable Outbound Calling from Vapi Through DIDWW
==================================================

Configure an Outbound SIP Trunk in the DIDWW User Panel to allow Vapi assistants to place outbound calls through DIDWW.
This trunk also provides the SIP credentials required for authenticated SIP REFER call transfers to external phone numbers.

Before You Begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- Access to **DIDWW Outbound Trunks** is required for making outbound calls. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

Step 1: Create New Outbound Voice Trunk
---------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/outbound1.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Fig. 8. Creating a new outbound SIP trunk

Step 2: Configure Authentication
--------------------------------

1. Update the **Friendly Name** (e.g., ``Vapi``).
2. Keep the default **Credentials & IP-based** authentication method selected. The SIP digest credentials (username and password) will be provided after the trunk is created.
3. In **Allowed SIP IP addresses**, enter the public SIP signaling IP addresses for your Vapi region:

   - US: ``44.229.228.186/32`` and ``44.238.177.138/32``
   - EU: ``44.233.34.47/32`` and ``44.233.34.48/32``

   Then add the DIDWW inbound SIP addresses used for call transfers:

   - New York: ``46.19.209.14``
   - Frankfurt: ``46.19.210.14``
   - Los Angeles: ``46.19.212.14``
   - Miami: ``46.19.213.14``
   - Singapore: ``46.19.214.14``
   - Hong Kong: ``46.19.215.14``
   - Amsterdam: ``185.238.173.14``

.. note::
   Vapi SIP signaling IP addresses depend on the region where your Vapi organization is hosted and may change. Refer to the official Vapi documentation for the most up-to-date information: `Vapi SIP Networking and Firewall Configuration <https://docs.vapi.ai/advanced/sip/sip-networking>`_

.. warning::
   You can allow all traffic by adding ``0.0.0.0/0``, which removes all IP restrictions.
   Although SIP Digest Authentication will still verify requests using valid credentials, this setup is not recommended.
   Restrict access to known Vapi SIP signaling IPs whenever possible.

.. figure:: https://doc.didww.com/_images/outbound2.png
   :figclass: align-center
   :alt: Configuring allowed SIP IP addresses for outbound trunk authentication

   Fig. 9. Entering allowed SIP IP addresses for outbound authentication

.. _vapi_create_outbound_trunk:

Step 3: Save the Outbound SIP Trunk
--------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk are filled, click **Create** to save your outbound SIP trunk.

.. note:: For advanced outbound SIP trunk configuration, see :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/outbound3.png
   :figclass: align-center
   :alt: Outbound SIP trunk created

   Fig. 10. Outbound SIP trunk created and ready for use

.. _vapi_create_outbound_trunk_copy_credentials:

Step 4: Copy Outbound Trunk Credentials
---------------------------------------

When the outbound trunk is created, you can view its credentials by selecting the key icon in the Credentials column on the Outbound Trunks page.

1. Go to **Voice > Outbound Trunks**.
2. Locate your outbound trunk and click the **key icon** in the **Credentials** column.
3. The trunk credentials will appear, showing the **Username** and **Password** (click the **eye icon** to reveal the password).
4. Copy and securely store these credentials. You will need them later when configuring Vapi in :ref:`Step 1: Create Outbound Trunk <vapi_create_vapi_outbound_trunk>` and :ref:`Step 2: Create Inbound Trunk <vapi_create_vapi_inbound_trunk>`.

.. figure:: https://doc.didww.com/_images/outbound4.png
   :figclass: align-center
   :alt: Accessing outbound trunk credentials

   Fig. 11. Opening the outbound trunk credentials view

Step 5: Add Outbound Credentials to the Inbound Trunk
-----------------------------------------------------

To support call transfers, configure the DIDWW inbound trunk to authenticate SIP REFER requests with the credentials generated for the outbound trunk.

1. Go to **Voice > Inbound Trunks** and locate the Vapi inbound trunk.
2. Click the **Actions (⋯)** icon, then select **Edit**.
3. Open the **Authorization** tab.
4. Turn on **Enable Authorization**.
5. In **Auth User**, paste the outbound trunk **Username**.
6. In **Auth Password**, paste the outbound trunk **Password**.
7. Click **Submit**.

.. figure:: https://doc.didww.com/_images/inbound_auth.png
   :figclass: align-center
   :alt: Adding outbound trunk credentials to the inbound trunk Authorization tab

   Fig. 12. Adding outbound trunk credentials to the inbound trunk

----

.. _vapi_configure_number:

3. Connect DIDWW SIP Trunks in Vapi
===================================

Connect the DIDWW SIP trunks in Vapi so your assistant can receive incoming calls, place outbound calls, transfer active calls, and use your DIDWW phone numbers.
This setup adds the required SIP trunk credentials, enables call transfer tooling, and links your DIDWW phone numbers to a Vapi assistant.

Before You Begin
----------------

- An active **Vapi account** is required. `Sign in to Vapi <https://dashboard.vapi.ai/>`_ or create an account if needed.
- A configured **Vapi assistant** is required. See the `Vapi Quickstart Guide <https://docs.vapi.ai/assistants/quickstart>`_ for guidance on creating an assistant.
- A private Vapi API key is required to use the cURL examples. See `Get Your API Credentials <https://docs.vapi.ai/chat/quickstart#1-get-your-api-credentials>`_ in the Vapi documentation.  Use ``https://api.vapi.ai`` for US organizations or ``https://api.eu.vapi.ai`` for EU organizations.

.. _vapi_create_vapi_outbound_trunk:

Step 1: Create Outbound Trunk
-----------------------------

Create a Vapi outbound SIP trunk credential that uses DIDWW as the SIP provider.

.. tab-set::
   :class: my-tabs
   :sync-group: vapi-configuration

   .. tab-item:: Dashboard
      :sync: dashboard

      1. In Vapi, open the **Integrations** menu.
      2. Locate **Phone Number Providers** and open **SIP Trunk** integrations.

      .. figure:: https://doc.didww.com/_images/vapi_out1.png
         :figclass: align-center
         :alt: Opening the SIP Trunk provider in Vapi integrations

         Fig. 13. Opening the SIP Trunk provider in Vapi

      3. Click **Configure New SIP Trunk**.

      .. figure:: https://doc.didww.com/_images/vapi_out2.png
         :figclass: align-center
         :alt: Starting a new SIP trunk configuration in Vapi

         Fig. 14. Starting a new SIP trunk configuration in Vapi

      4. Enter a friendly **Name** (e.g., ``DIDWW Outbound Trunk``).
      5. In **IP Address / Domain**, enter any of the DIDWW :ref:`outbound signaling endpoints <voice-out-signaling-endpoints>` (e.g., ``fra.eu.out.didww.com``).
      6. Configure the transport protocol and port. Use ``5060`` for UDP/TCP or ``5061`` for TLS.
      7. Uncheck **Allow inbound calls**, leaving only **Allow outbound calls** selected.

      .. figure:: https://doc.didww.com/_images/vapi_out3.png
         :figclass: align-center
         :alt: Configuring DIDWW gateway settings for the Vapi outbound trunk

         Fig. 15. Configuring DIDWW gateway settings

      8. In **Authentication**, enter the **Username** and **Password** copied from :ref:`Step 4: Copy Outbound Trunk Credentials <vapi_create_outbound_trunk_copy_credentials>`.
      9. Click **Save SIP Trunk**.

      .. figure:: https://doc.didww.com/_images/vapi_out4.png
         :figclass: align-center
         :alt: Configuring authentication for the Vapi outbound trunk

         Fig. 16. Configuring outbound trunk authentication

   .. tab-item:: cURL
      :sync: curl

      .. code-block:: bash

         curl -X POST https://api.vapi.ai/credential \
           -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
           -H "Content-Type: application/json" \
           -d '{
             "provider": "byo-sip-trunk",
             "name": "DIDWW Outbound Trunk",
             "gateways": [
               {
                 "ip": "YOUR_DIDWW_OUTBOUND_ENDPOINT",
                 "port": 5060,
                 "inboundEnabled": false,
                 "outboundEnabled": true,
                 "outboundProtocol": "udp"
               }
             ],
             "outboundAuthenticationPlan": {
               "authUsername": "YOUR_DIDWW_TRUNK_USERNAME",
               "authPassword": "YOUR_DIDWW_TRUNK_PASSWORD"
             }
           }'

      Replace the endpoint with the DIDWW signaling endpoint selected for your deployment.

.. _vapi_create_vapi_inbound_trunk:

Step 2: Create Inbound Trunk
----------------------------

Create the Vapi inbound trunk that will accept calls from DIDWW.
Because Vapi allows only one allowed IP address per gateway, create one gateway for each required DIDWW SIP signaling IP.

.. tab-set::
   :class: my-tabs
   :sync-group: vapi-configuration

   .. tab-item:: Dashboard
      :sync: dashboard

      1. In Vapi, open the **SIP Trunk** integration and click **Configure New SIP Trunk**.

      .. figure:: https://doc.didww.com/_images/vapi_in1.png
         :figclass: align-center
         :alt: Starting an inbound SIP trunk configuration in Vapi

         Fig. 17. Starting an inbound SIP trunk configuration in Vapi

      2. Enter a friendly **Name** (e.g., ``DIDWW Inbound Trunk``).
      3. In the gateway settings, enter one of the :ref:`DIDWW SIP IPs <service_did_sip>` as the allowed signaling IP for the gateway (e.g., ``46.19.209.14``).
      4. Configure the transport protocol and port. Use ``5060`` for UDP/TCP or ``5061`` for TLS. This must match the transport protocol selected on the :ref:`DIDWW inbound SIP trunk <vapi_inbound>`.
      5. Uncheck **Allow outbound calls**, leaving only **Allow inbound calls** selected.
      6. Click **Add Another Gateway** and repeat steps 3-5 until you have added all :ref:`DIDWW SIP IPs <service_did_sip>` to the inbound trunk gateways. This is required because Vapi allows only one IP per gateway.

      .. figure:: https://doc.didww.com/_images/vapi_in2.png
         :figclass: align-center
         :alt: Configuring DIDWW gateway IPs for the Vapi inbound trunk

         Fig. 18. Configuring DIDWW gateway IPs for the inbound trunk

      7. In **Authentication**, enter the **Username** and **Password** copied from :ref:`Step 4: Copy Outbound Trunk Credentials <vapi_create_outbound_trunk_copy_credentials>`.
      8. Click **Save SIP Trunk**.

      .. figure:: https://doc.didww.com/_images/vapi_in3.png
         :figclass: align-center
         :alt: Configuring authentication for the Vapi inbound trunk

         Fig. 19. Configuring inbound trunk authentication

   .. tab-item:: cURL
      :sync: curl

      .. code-block:: bash

         curl -X POST https://api.vapi.ai/credential \
           -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
           -H "Content-Type: application/json" \
           -d '{
             "provider": "byo-sip-trunk",
             "name": "DIDWW Inbound Trunk",
             "gateways": [
               { "ip": "46.19.209.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false },
               { "ip": "46.19.210.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false },
               { "ip": "46.19.212.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false },
               { "ip": "46.19.213.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false },
               { "ip": "46.19.214.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false },
               { "ip": "46.19.215.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false },
               { "ip": "185.238.173.14", "port": 5060, "netmask": 32, "inboundEnabled": true, "outboundEnabled": false }
             ],
             "outboundAuthenticationPlan": {
               "authUsername": "YOUR_DIDWW_TRUNK_USERNAME",
               "authPassword": "YOUR_DIDWW_TRUNK_PASSWORD"
             }
           }'

      Save the returned credential ``id``; it is required when you `import the DIDWW number <https://docs.vapi.ai/phone-numbers/didww>`_.

Step 3: Create Call Transfer Tool
---------------------------------

Create a call transfer tool in Vapi so the assistant can transfer an active call to a live person through DIDWW.

.. tab-set::
   :class: my-tabs
   :sync-group: vapi-configuration

   .. tab-item:: Dashboard
      :sync: dashboard

      1. In Vapi, open the **Tools** page and click **Create Tool** and select **Transfer Call**.

      .. figure:: https://doc.didww.com/_images/vapi_transfer2.png
         :figclass: align-center
         :alt: Selecting the Transfer Call tool in Vapi

         Fig. 20. Selecting the Transfer Call tool

      2. Enter a **Tool Name** (for example, ``transfer_call_tool``).
      3. In **Description**, enter a short explanation of when the tool should be used, for example: ``Transfers the active call to a live person through DIDWW when the caller requests human assistance.``.
      4. Under **Destinations**, click **Add Destination** and select **SIP**.

      .. figure:: https://doc.didww.com/_images/vapi_transfer3.png
         :figclass: align-center
         :alt: Configuring the Transfer Call tool settings in Vapi

         Fig. 21. Configuring the Transfer Call tool settings

      5. In **SIP URI**, enter the SIP URI in the format ``sip:+E164_NUMBER@OUTBOUND_ENDPOINT``, where the phone number is in E.164 format with the ``+`` symbol and the outbound endpoint is one of the DIDWW :ref:`Outbound Trunk Signaling Endpoints <voice-out-signaling-endpoints>`, for example ``sip:+1234567890@fra.eu.out.didww.com``.
      6. In **Message to Customer**, enter the message that should be played before the transfer starts, for example ``Please wait while I transfer your call``.
      7. In the destination **Description** field, enter when this transfer destination should be used, for example ``Trigger this tool when a caller asks to be transferred to a live person``.
      8. In **Transfer Mode**, keep the default **Blind Transfer** mode.

      .. figure:: https://doc.didww.com/_images/vapi_transfer4.png
         :figclass: align-center
         :alt: Configuring the SIP destination for the Transfer Call tool in Vapi

         Fig. 22. Configuring the SIP destination for the Transfer Call tool

      9. Click **Save** to create the call transfer tool.

   .. tab-item:: cURL
      :sync: curl

      .. code-block:: bash

         curl -X POST https://api.vapi.ai/tool \
           -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
           -H "Content-Type: application/json" \
           -d '{
             "type": "transferCall",
             "destinations": [
               {
                 "type": "sip",
                 "sipUri": "sip:+447700900123@YOUR_DIDWW_OUTBOUND_ENDPOINT",
                 "message": "Please wait while I transfer your call.",
                 "description": "Use when the caller asks to speak with a live person.",
                 "transferPlan": {
                   "mode": "blind-transfer",
                   "sipVerb": "refer"
                 }
               }
             ]
           }'

      Save the returned tool ``id`` for the next step.

Step 4: Add Call Transfer Tool to Your Assistant
------------------------------------------------

Add the transfer tool to the assistant that will handle calls for your DIDWW number.

.. tab-set::
   :class: my-tabs
   :sync-group: vapi-configuration

   .. tab-item:: Dashboard
      :sync: dashboard

      1. In Vapi, go to **Assistants** and open the assistant that will handle your DIDWW calls.
      2. Open the **Tools** tab and click **Add tool**.
      3. Select the **Transfer Call Tool** you created in the previous step.

      .. figure:: https://doc.didww.com/_images/vapi_assistant1.png
         :figclass: align-center
         :alt: Adding the transfer tool to a Vapi assistant

         Fig. 23. Adding the transfer tool to a Vapi assistant

      4. Click **Publish** to apply the assistant changes.

      .. figure:: https://doc.didww.com/_images/vapi_assistant2.png
         :figclass: align-center
         :alt: Transfer tool attached to a Vapi assistant

         Fig. 24. Transfer tool attached to the assistant

      5. In the pop-up window, click **Publish** again to confirm the changes.

      .. figure:: https://doc.didww.com/_images/vapi_assistant3.png
         :figclass: align-center
         :alt: Publishing the Vapi assistant after adding the transfer tool

         Fig. 25. Publishing the assistant changes

   .. tab-item:: cURL
      :sync: curl

      Retrieve the assistant, add the transfer tool ID to ``model.toolIds``, and PATCH the complete model back. The example uses ``jq`` to preserve the existing model configuration and tool IDs.

      .. code-block:: bash

         VAPI_API_BASE="https://api.vapi.ai"
         ASSISTANT_ID="YOUR_ASSISTANT_ID"
         TRANSFER_TOOL_ID="YOUR_TRANSFER_TOOL_ID"

         CURRENT_MODEL=$(curl -s "$VAPI_API_BASE/assistant/$ASSISTANT_ID" \
           -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" | jq '.model')

         UPDATED_MODEL=$(printf '%s' "$CURRENT_MODEL" | jq \
           --arg toolId "$TRANSFER_TOOL_ID" \
           '.toolIds = (((.toolIds // []) + [$toolId]) | unique)')

         jq -n --argjson model "$UPDATED_MODEL" '{model: $model}' | \
           curl -X PATCH "$VAPI_API_BASE/assistant/$ASSISTANT_ID" \
             -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
             -H "Content-Type: application/json" \
             --data-binary @-

.. _vapi_add_phone_numbers:

Step 5: Import DIDWW Phone Numbers
----------------------------------

Import your DIDWW phone number to Vapi and assign it to the assistant that will handle incoming calls.

.. tab-set::
   :class: my-tabs
   :sync-group: vapi-configuration

   .. tab-item:: Dashboard
      :sync: dashboard

      1. In Vapi, open the **Phone Numbers** menu and click **Create Phone Number**.

      .. figure:: https://doc.didww.com/_images/vapi_number1.png
         :figclass: align-center
         :alt: Opening the Phone Numbers page in Vapi

         Fig. 26. Opening the Phone Numbers page in Vapi

      2. Select **BYO SIP Trunk Number**.
      3. In **Phone Number**, enter your DIDWW number in E.164 format with the ``+`` symbol (for example, ``+18648301018``).
      4. Leave **Allow non-E164 phone numbers** unchecked.
      5. In **SIP Trunk Credential**, select the Vapi inbound SIP trunk created in :ref:`Step 2: Create Inbound Trunk <vapi_create_vapi_inbound_trunk>`.
      6. Optionally, in **Label**, enter a descriptive name for the number (for example, ``My DIDWW Phone Number``).
      7. Click **Import SIP Phone Number**.

      .. figure:: https://doc.didww.com/_images/vapi_number2.png
         :figclass: align-center
         :alt: Importing a BYO SIP trunk number in Vapi

         Fig. 27. Importing a BYO SIP trunk number

      8. In **Assistant**, select the Vapi assistant that will handle inbound calls.
      9. Click **Save** to confirm the changes.

      .. figure:: https://doc.didww.com/_images/vapi_number3.png
         :figclass: align-center
         :alt: Assigning an assistant to an imported phone number in Vapi

         Fig. 28. Assigning an assistant to the imported phone number

      After saving, the imported number will appear in the **Phone Numbers** list and incoming calls to your DIDWW number will be routed to the selected assistant.

   .. tab-item:: cURL
      :sync: curl

      .. code-block:: bash

         curl -X POST https://api.vapi.ai/phone-number \
           -H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
           -H "Content-Type: application/json" \
           -d '{
             "provider": "byo-phone-number",
             "name": "DIDWW Number",
             "number": "+14155550123",
             "numberE164CheckEnabled": true,
             "credentialId": "YOUR_CREDENTIAL_ID",
             "assistantId": "YOUR_ASSISTANT_ID"
           }'

      Use the credential ``id`` returned when you created the ``DIDWW Inbound Trunk``. The optional ``assistantId`` assigns the assistant that handles inbound calls; omit it if you plan to configure inbound routing later.

Step 6: Test the Configuration
------------------------------

Verify that inbound calling, outbound calling, and call transfers are working as expected.

1. Place a test call to your **DIDWW DID number** to confirm that inbound calls are routed to Vapi and handled by the assigned **assistant**.
2. In the Vapi dashboard or API, place a test `outbound call <https://docs.vapi.ai/calls/outbound-calling>`_ through your DIDWW outbound trunk.
3. Place another test call to your DIDWW DID number and trigger the call transfer condition, for example by asking to speak with a live person.
4. Confirm that Vapi sends the transfer request and the call is connected to the live-person destination through DIDWW.

Ensure that calls are successfully established in both directions, that the correct assistant handles the interaction, and that transferred calls connect with two-way audio.

.. note::
   You can review call activity and verify call status or error codes in the DIDWW **Inbound** and **Outbound Call Logs**.
   See :ref:`Inbound Call Logs <inbound_cdr_logs>` and :ref:`Outbound Call Logs <outbound_cdr_logs>` for more details.


.. _ms_teams:

==============================
Microsoft Teams Direct Routing
==============================

Microsoft Teams Direct Routing allows your organization to use DIDWW as a SIP trunk provider for inbound and outbound voice services within Microsoft Teams. With this integration, you can retain your existing DIDWW phone numbers, take advantage of cost-effective calling rates, and leverage the full capabilities of the Microsoft Teams Phone System.

Integration benefits:

    - **Retain existing phone numbers:** Continue using your current DIDWW numbers within Microsoft Teams.
    - **Cost efficiency:** Take advantage of competitive DIDWW calling rates.
    - **Enhanced communication:** Fully leverage Microsoft Teams phone system features.

----

.. raw:: html

    <br>

Prerequisites
=============

Before setting up Microsoft Teams Direct Routing with DIDWW, make sure you have the following:

    - An `active DIDWW account <https://my.didww.com/users/sign_up>`_.
    - A DIDWW Microsoft Teams SBC domain. Contact `sales@didww.com <mailto:sales@didww.com>`_ for details.
    - :ref:`Access to outbound trunks <user_panel_voice_out_get_access>` (required only for outbound calling).
    - A Microsoft Phone System license with Direct Routing enabled. For details, see the `official Microsoft documentation <https://docs.microsoft.com/en-us/microsoftteams/direct-routing-plan#licensing-and-other-requirements>`_.

----

.. raw:: html

    <br>

Connect DIDWW Trunks with MS Teams
==================================

This guide provides detailed steps on integrating DIDWW Trunks with MS Teams. Follow the instructions below to complete the setup process.

.. raw:: html

    <br>

Step 1: Set up and verify the domain
------------------------------------

Complete the following steps to set up and verify your DIDWW domain in Microsoft Teams.

Add the domain in Microsoft 365
'''''''''''''''''''''''''''''''

    #. Sign in to the `Microsoft 365 admin center <https://admin.microsoft.com/Adminportal/>`_.
    #. Select **Settings > Domains**.
    #. Click **Add domain** and enter your domain which was provided to you by DIDWW.

.. figure:: https://doc.didww.com/_images/figure1.png
   :figclass: align-center
   :alt: Adding a domain in Microsoft 365

   Fig. 1. Adding a domain in Microsoft 365

Verify the domain
'''''''''''''''''

    #. Click **Use this domain**.
    #. Select **Add a TXT record** and save the provided TXT value (e.g., ``MS=ms83401203``).

.. figure:: https://doc.didww.com/_images/figure2.png
   :figclass: align-center
   :alt: Verifying your domain

   Fig. 2. Verifying your domain

Complete domain verification
''''''''''''''''''''''''''''

    #. Share the TXT record value with the DIDWW Support team at `support@didww.com <mailto:support@didww.com>`_.
    #. After confirmation from DIDWW, return to Microsoft 365 and select **Verify**.
    #. Choose **More Options**, then **Skip and do this later**, and click **Continue**.

    .. note::

       Microsoft DNS records aren't needed for Direct Routing.

.. figure:: https://doc.didww.com/_images/figure6.png
   :figclass: align-center
   :alt: Domain verification complete

   Fig. 3. Domain verification complete

----

.. raw:: html

    <br>

Step 2: Activate the domain
---------------------------

After your domain is verified, activate it by creating a user with the domain and assigning a Microsoft license.

Add a user with the verified domain
'''''''''''''''''''''''''''''''''''

    #. Sign in to the `Microsoft 365 admin center <https://admin.microsoft.com/Adminportal/>`_.
    #. Go to **Users > Active users**, and select **Add a user**.
    #. In the **Username** field, enter a user ID that includes your verified DIDWW domain.

      Example: ``DIDWW@0232-40e6-a468-38a329debdd7.teams.didww.com``

.. figure:: https://doc.didww.com/_images/figure7.png
   :figclass: align-center
   :alt: Activating the domain

   Fig. 4. Activating the domain

Assign a Microsoft license to the user
''''''''''''''''''''''''''''''''''''''

Assign a **Microsoft 365 Business** license with the **Phone System** add-on, or an **E5** license.

.. note::
    - For license requirements, refer to the `Direct Routing planning documentation <https://docs.microsoft.com/en-us/microsoftteams/direct-routing-plan#licensing-and-other-requirements>`_.
    - After you add the domain and user, it may take up to 24 hours for the domain to be fully provisioned in your tenant.

.. figure:: https://doc.didww.com/_images/figure8.png
   :figclass: align-center
   :alt: Assigning license to the user

   Fig. 5. Assigning license to the user

----

.. raw:: html

    <br>

Step 3: Configure Direct Routing
--------------------------------

You can configure Direct Routing via the Microsoft Teams Admin Center or PowerShell.

Sign in to the Teams Admin Center
'''''''''''''''''''''''''''''''''

    #. Click the link to open the `Teams Admin Center <https://admin.teams.microsoft.com>`_.
    #. Sign in using **Tenant Administrator** credentials.

.. figure:: https://doc.didww.com/_images/figure9.png
   :figclass: align-center
   :alt: Teams Admin Center

   Fig. 6. Teams Admin Center

Add the SBC
'''''''''''

In the Teams Admin Center, follow these steps to add the SBC:

    1. Click the **Voice** Menu.
    2. Click the **Direct Routing** sub-menu.
    3. Click **Add** under the **SBCs** tab.

.. figure:: https://doc.didww.com/_images/figure11.png
   :figclass: align-center
   :alt: Adding SBC to Direct Routing

   Fig. 7. Adding SBC to Direct Routing

In the **Add SBC** window, configure the following settings:

    - **SBC name** – Enter the SBC name provided by DIDWW.
    - **Description (optional)** – Enter a description to identify the purpose of this SBC.
    - **Enabled** – Turn on the toggle to enable the SBC.
    - **SIP signaling port** – Enter ``5061``.
    - **Send SIP options** – Turn on the toggle to enable SIP OPTIONS for activity monitoring.

Leave all other settings at their default values. Scroll down and click **Save** to create the SBC.

    .. figure:: https://doc.didww.com/_images/figure12.png
       :figclass: align-center
       :alt: Configuring new SBC

       Fig. 8. Configuring new SBC

PowerShell alternative
''''''''''''''''''''''

Alternatively, you can use the following PowerShell command:

.. code-block:: powershell

   New-CsOnlinePSTNGateway -Identity 0232-40e6-a468-38a329debdd7.teams.didww.com -SipSignalingPort 5061 -Enabled $True -MaxConcurrentSessions 100

----

.. raw:: html

    <br>

Step 4: Configure voice routing
-------------------------------

Add the voice route
'''''''''''''''''''

In the Teams Admin Center, follow these steps to configure voice routes:

    1. Click the **Voice** Menu.
    2. Open the **Direct Routing** sub-menu.
    3. In the **Direct Routing** page, open the **Voice routes** tab.
    4. Click **Add** under the **Voice Routes** tab.

    .. figure:: https://doc.didww.com/_images/figure13.png
       :figclass: align-center
       :alt: Adding a Voice Route

       Fig. 9. Adding a Voice Route

Create the voice route
''''''''''''''''''''''

To create the voice route, you will need to configure the following details:

    - Add the Dialed Number pattern
    - Assign the SBC
    - Add PSTN usage records

Add the Dialed Number pattern
'''''''''''''''''''''''''''''

To configure the Dialed Number pattern:

    - Leave the Priority on the default ``1`` value.
    - Use the pattern ``^(.*)$`` to match any dialed number in the exact format.

    .. note:: If you do not want to require dialing in E.164 format, configure alternate number patterns.

   For example, to allow dialing North American numbers without the ``+1`` prefix, use the pattern ``^(\+1[0-9]{10})$``.

   Update the pattern as necessary for other dialing formats and regions.

    .. figure:: https://doc.didww.com/_images/figure14.1.png
       :figclass: align-center
       :alt: Dialed number pattern

       Fig. 10. Dialed number pattern

Assign the SBC
''''''''''''''

After configuring the dialed number pattern:

    1. Click **Add SBCs**.
    2. In the **Select existing SBC to Add** dropdown, choose the SBC (e.g., ``0232-40e6-a468-38a329debdd7.teams.didww.com``).
    3. Click **Apply**.

    .. figure:: https://doc.didww.com/_images/figure15.png
       :figclass: align-center
       :alt: Assigning the SBC

       Fig. 11. Assigning the SBC

Add PSTN usage records
''''''''''''''''''''''

    1. Click **Add PSTN usage records**.
    2. In the pop-up screen, click **+ Add** or select the existing PSTN usage record (e.g., ``DIDWW``).
    3. Click **Save and apply**.

    .. figure:: https://doc.didww.com/_images/figure15.1.png
       :figclass: align-center
       :alt: Assigning PSTN usage record to the voice route

       Fig. 12. Assigning PSTN usage record to the voice route

    4. Finalize the voice route by clicking **Save**.

    .. figure:: https://doc.didww.com/_images/figure15.2.png
       :figclass: align-center
       :alt: Save the Voice Routing Settings

       Fig. 13. Save the Voice Routing Settings

PowerShell alternative
''''''''''''''''''''''

You can also configure the voice route using PowerShell:

.. code-block:: powershell

   Set-CsOnlinePstnUsage -Identity Global -Usage @{Add="DIDWW"}

   New-CsOnlineVoiceRoute -Identity "DIDWW" -NumberPattern "^(.*)$" -OnlinePstnGatewayList 0232-40e6-a468-38a329debdd7.teams.didww.com -Priority 1 -OnlinePstnUsages "DIDWW"

----

.. raw:: html

    <br>

Step 5: Create a voice routing policy
-------------------------------------

Add a voice routing policy
''''''''''''''''''''''''''

In the Teams Admin Center, follow these steps to configure a new voice routing policy:

    1. Click the **Voice** menu.
    2. Open the **Voice routing policies** sub-menu.
    3. Click **Manage policies**.
    4. Click **Add** to create a new voice routing policy.

.. figure:: https://doc.didww.com/_images/figure16.png
   :figclass: align-center
   :alt: Adding a new voice routing policy

   Fig. 14. Adding a new voice routing policy

Assign the PSTN usage record
''''''''''''''''''''''''''''

    1. Click **Add PSTN usage records**.
    2. In the pop-up screen, select the usage record (e.g., ``DIDWW``).
    3. Click **Apply**.

.. figure:: https://doc.didww.com/_images/figure16.1.png
   :figclass: align-center
   :alt: Assign PSTN usage records with new voice routing policy

   Fig. 15. Assign PSTN usage records with new voice routing policy

Save the voice routing policy
'''''''''''''''''''''''''''''

After assigning the PSTN usage record, click **Save** to create the policy.

.. figure:: https://doc.didww.com/_images/figure16.2.png
   :figclass: align-center
   :alt: Save the voice routing policy

   Fig. 16. Save the voice routing policy

PowerShell alternative
''''''''''''''''''''''

You can also create the voice routing policy using PowerShell:

.. code-block:: powershell

   New-CsOnlineVoiceRoutingPolicy "DIDWW Route" -OnlinePstnUsages "DIDWW"

----

.. raw:: html

    <br>

Step 6: Assign users to policies
--------------------------------

To assign voice routing policy in the Teams Admin Center, follow these steps:

    1. Click the **Users > Manage users** to open the Manage users sub-menu.
    2. Select one or more users from the list.
    3. Click **Edit settings**.
    4. Under **Voice routing policy**, select **DIDWW Route**.
    5. Under **Calling policy**, select **AllowCalling**.
    6. Click **Apply** to save the changes.

.. figure:: https://doc.didww.com/_images/figure18.png
   :figclass: align-center
   :alt: Assigning the DIDWW voice routing policy

   Fig. 17. Assigning the DIDWW voice routing policy

PowerShell alternative
''''''''''''''''''''''

Use the following commands to assign both the voice routing policy and the calling policy to a user:

.. code-block:: powershell

   Grant-CsOnlineVoiceRoutingPolicy -PolicyName "DIDWW Route" -Identity DIDWW@0232-40e6-a468-38a329debdd7.teams.didww.com

   Grant-CsTeamsCallingPolicy -PolicyName "AllowCalling" -Identity DIDWW@0232-40e6-a468-38a329debdd7.teams.didww.com

.. note::

   Policy changes may take several hours to propagate.

----

.. raw:: html

    <br>

Step 7: Assign a DIDWW phone number and verify call functionality
-----------------------------------------------------------------

Open the user profile
''''''''''''''''''''''

To begin assigning a DIDWW number to a user, first navigate to their profile:

    1. Click the **Users > Manage users** menu and sub-menu.
    2. Click the name of the user (e.g., **Technical Support**).

    .. figure:: https://doc.didww.com/_images/figure19.png
       :figclass: align-center
       :alt: Edit the user

       Fig. 18. Edit the user

Open the phone number editor
''''''''''''''''''''''''''''

From the user's account page, open the phone number assignment editor:

    - Under the **Assigned phone number** section, click **Edit**.

    .. figure:: https://doc.didww.com/_images/figure20.png
       :figclass: align-center
       :alt: Editing the assigned phone number

       Fig. 19. Editing the assigned phone number

Assign the DIDWW number
''''''''''''''''''''''''

In the phone number assignment pane, configure the DIDWW number:

    1. Set **Phone number type** to **Direct Routing**.
    2. Select the **Assigned phone number** from the dropdown.
    3. Click **Apply** to save the assignment.

    .. figure:: https://doc.didww.com/_images/figure20.1.png
       :figclass: align-center
       :alt: Assigning the DIDWW number

       Fig. 20. Assigning the DIDWW number

PowerShell alternative:
'''''''''''''''''''''''

To assign the DIDWW number using PowerShell, use the following command:

.. code-block:: powershell

   Set-CsPhoneNumberAssignment -Identity didww@0232-40e6-a468-38a329debdd7.teams.didww.com -PhoneNumber +99999999999 -PhoneNumberType DirectRouting

Verify call functionality
'''''''''''''''''''''''''

Use the Microsoft Teams client to:

    - Place an **outbound call** using the assigned DIDWW number.
    - Receive an **inbound call** to confirm routing is functioning correctly.

    .. note::

       For additional help, contact the DIDWW Support team at `support@didww.com <mailto:support@didww.com>`_.

----

.. raw:: html

    <br>

Additional Information
----------------------

.. card:: **Outbound Dialing**
    :link: outbound_dialing
    :link-type: ref

    Learn about outbound dialing, number format, local routes, and short numbers.


.. |br| raw:: html

  <br>

.. _3cx:

====
3CX
====

Use **3CX** with **DIDWW SIP Trunking** to deliver inbound and outbound voice services over the public telephone network.
DIDWW SIP trunks integrate with 3CX to bring calls from your DIDs into the PBX, apply 3CX call handling features, and route outbound calls through DIDWW termination.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Receive inbound calls from DIDWW in 3CX.
      - Route calls to users, groups, queues, or digital receptionists.
      - Use 3CX features such as office hours, voicemail, and call recording.

   .. grid-item::
      :class: left-align-block

      - Use DIDWW SIP trunks for local and international outbound calls.
      - Show DIDWW DIDs as caller ID based on 3CX rules and user settings.
      - Use DIDWW trunks with 3CX routing and extension permissions.

.. note::

   - This guide is intended for **3CX Version 20**.
   - DIDWW SIP trunk configuration is supported with **3CX PRO
     (Professional)** and **3CX ENT (Enterprise)** licenses.

----

.. raw:: html

    <br>

.. _3cx_inbound:

1. Create Inbound SIP Trunk
===========================

To begin connecting your **DIDWW account** with **3CX**, first create an **Inbound SIP Trunk**.
This trunk will establish the path for incoming calls from your DIDWW numbers to reach 3CX.

Choose how 3CX will receive inbound calls from DIDWW:

    - **SIP URI** - DIDWW sends calls directly to your 3CX IP or domain.
    - **SIP Registration** - 3CX registers to DIDWW using SIP credentials.

.. raw:: html

    <br>

Before You Begin
----------------

    - An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
    - At least one active **DID number** with capacity to receive incoming calls is required. `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_.
    - A public IP address or FQDN for your 3CX system is required if your deployment is self-hosted.

.. raw:: html

    <br>

Step 1: Create New SIP Trunk
----------------------------

    1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
    2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/didww_inbound1.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Fig. 1. Creating a new inbound SIP trunk

Step 2: Configure SIP Trunk Settings
------------------------------------

Depending on whether you plan to use a **Static Endpoint** or **Dynamic Registration**, the configuration differs slightly.

.. tab-set::
   :class: my-tabs
   :sync-group: versions

   .. tab-item:: Static Endpoint (SIP URI)
      :sync: sip-uri

      In the Create Inbound SIP Trunk form, enter the main requirements to route the calls to your 3CX PBX.

      1. Enter a descriptive **Name** for the trunk (for example, ``3CX Inbound Trunk``).
      2. Select **Static Endpoint**.
      3. In **Host**, enter the public IP address or FQDN of your 3CX PBX.

      .. note::
         If you are using a **cloud-hosted 3CX**, enter a placeholder IP address (for example, ``198.51.100.0``). The actual IP address will be retrieved later when you :ref:`configure the inbound SIP trunk in 3CX <3cx_configure_inbound_trunk>`.

      .. figure:: https://doc.didww.com/_images/didww_inbound2.png
         :figclass: align-center
         :alt: SIP URI inbound trunk configured to send calls to 3CX

         Fig. 2. SIP URI inbound trunk configured to send calls to 3CX

   .. tab-item:: Dynamic Registration
      :sync: sip-registration

      In the Create Inbound SIP Trunk form, configure the trunk for registration-based inbound calling.

      1. Enter a descriptive **Name** for the trunk (for example, ``3CX Registration``).
      2. Select **Dynamic Registration**.

      .. figure:: https://doc.didww.com/_images/didww_inbound2_registration.png
         :figclass: align-center
         :alt: SIP Registration inbound trunk configured for 3CX

         Fig. 3. SIP Registration inbound trunk configured for 3CX

Step 3: Click Create and Save Inbound SIP Trunk Configuration
-------------------------------------------------------------

When the required fields in the Create Inbound SIP Trunk form are filled, click **Create** to save your inbound SIP trunk.

.. note:: If your deployment requires additional features, see :ref:`Advanced Inbound SIP Trunk documentation <user_panel_sipin_trunk>`.

.. figure:: https://doc.didww.com/_images/didww_inbound3.png
   :figclass: align-center
   :alt: Inbound SIP trunk created

   Fig. 4. Create the Inbound SIP Trunk

Step 4: View Inbound Trunk Credentials (Dynamic Registration Only)
-------------------------------------------------------------------

If you are using **Dynamic Registration**, open the inbound trunk credentials and save them for later use in 3CX.

1. Go to **Voice > Inbound Trunks**.
2. Click the inbound trunk name.
3. Copy the **Username** and **Password**.

.. figure:: https://doc.didww.com/_images/didww_inbound_credentials.png
   :figclass: align-center
   :alt: Viewing inbound trunk credentials for SIP Registration

   Fig. 5. Viewing inbound trunk credentials for SIP Registration

Step 5: Assign Inbound SIP Trunk to Your DID Numbers
----------------------------------------------------

After creating the Inbound SIP Trunk for 3CX, assign it to the DID number or numbers that will deliver incoming calls to your 3CX PBX.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number or numbers you want to assign to the inbound SIP trunk.
3. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/didww_inbound4.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 6. Selecting **Update Trunks** from the Batch Actions menu

4. From the dropdown menu, choose the **3CX Inbound Trunk** you created earlier.
5. Click **Confirm** to apply the changes.

.. figure:: https://doc.didww.com/_images/didww_inbound5.png
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Fig. 7. Assigning the newly created SIP trunk to the selected DID(s)

----

.. raw:: html

    <br>

.. _3cx_outbound:

2. Create Outbound SIP Trunk
============================

To configure outbound calling from your 3CX PBX, create an **Outbound SIP Trunk** in the DIDWW User Panel.
This setup enables you to use 3CX to place outbound calls through DIDWW termination routes.

.. raw:: html

    <br>

Before You Begin
----------------

Access to **DIDWW Outbound Trunks** is required for making outbound calls. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

.. raw:: html

    <br>

Step 1: Create New Outbound Voice Trunk
---------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/didww_outbound1.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Fig. 8. Creating a new outbound SIP trunk

Step 2: Configure SIP Trunk Settings
------------------------------------

1. Update the **Friendly Name** (for example, ``3CX Outbound Trunk``).
2. Keep the default **Credentials & IP-based** authentication method selected. The SIP digest credentials (username and password) will be accessible after the trunk is created.
3. In **Allowed SIP IP addresses**, enter the public IP address or subnet from which your 3CX PBX will send outbound SIP traffic.

.. note::
   Enter the correct IP address or subnet so that outbound calls are accepted by DIDWW. If you are using a **cloud-hosted 3CX**, enter a placeholder IP address (for example, ``198.51.100.0``). The actual IP address will be retrieved later when you :ref:`configure the outbound SIP trunk in 3CX <3cx_configure_outbound_trunk>`.

.. figure:: https://doc.didww.com/_images/didww_outbound2.png
   :figclass: align-center
   :alt: Outbound SIP Trunk configuration for 3CX

   Fig. 9. Outbound SIP Trunk configuration for 3CX

Step 3: Click Create and Save Outbound SIP Trunk Configuration
--------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk form are filled, click **Create** to save your outbound SIP trunk.

.. note:: For advanced outbound SIP trunk configuration, see :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/didww_outbound3.png
   :figclass: align-center
   :alt: Outbound SIP trunk created

   Fig. 10. Outbound SIP trunk created and ready for use

Step 4: View Outbound Trunk Credentials
---------------------------------------

When the outbound trunk is created, you can view its credentials by selecting the key icon in the **Credentials** column on the Outbound Trunks page.

1. Go to **Voice > Outbound Trunks**.
2. Locate your outbound trunk and click the **key icon** in the **Credentials** column.

.. figure:: https://doc.didww.com/_images/didww_outbound4.png
   :figclass: align-center
   :alt: Accessing outbound trunk credentials

   Fig. 11. Opening the outbound trunk credentials view

3. The trunk credentials will appear, showing the **Username** and **Password**. Click the **eye icon** to reveal the password.
4. **Copy and save** these credentials for the next steps when :ref:`configuring the outbound SIP trunk on 3CX <3cx_configure_outbound_trunk>`.

.. warning:: If the credentials become exposed to unauthorized parties, :ref:`rotate them immediately in the DIDWW User Panel <view_outbound_trunk_credentials>`.

.. figure:: https://doc.didww.com/_images/didww_outbound5.png
   :figclass: align-center
   :alt: Accessing outbound trunk credentials

   Fig. 12. Viewing the outbound trunk credentials

----

.. raw:: html

    <br>

.. _3cx_configure:

3. Configure 3CX
================

To complete your integration, configure the DIDWW SIP trunking settings inside **3CX**.
This setup links your DIDWW Inbound and Outbound SIP Trunks to 3CX, allowing the PBX to manage call routing, features, and call handling for both inbound and outbound traffic.

.. raw:: html

    <br>

Before You Begin
----------------

- Administrator access to the 3CX Management Console is required.
- A configured :ref:`DIDWW Inbound SIP Trunk <3cx_inbound>` and :ref:`DIDWW Outbound SIP Trunk <3cx_outbound>` is required before proceeding.
- A 3CX PRO (Professional) or 3CX ENT (Enterprise) license is required to configure a custom or generic SIP trunk.
- At least one 3CX user, extension, queue, ring group, or digital receptionist should exist before assigning call routes.

.. raw:: html

    <br>

.. _3cx_configure_inbound_trunk:

Step 1: Configure the DIDWW Inbound SIP Trunk
---------------------------------------------

This trunk allows 3CX to receive inbound calls from your DIDWW DID numbers.

Add the Inbound Trunk in 3CX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. tab-set::
   :class: my-tabs
   :sync-group: versions

   .. tab-item:: SIP URI
      :sync: sip-uri

      1. In the 3CX Management Console, go to **Admin > Voice & Chat**.
      2. Click **Add Trunk**.
      3. Select any country and **Generic SIP Trunk (IP Based)** in the provider field.

      .. figure:: https://doc.didww.com/_images/3cx_inbound1.png
         :figclass: align-center
         :alt: Add SIP URI inbound trunk in 3CX

         Fig. 13. Add a new SIP URI inbound trunk in 3CX

   .. tab-item:: SIP Registration
      :sync: sip-registration

      1. In the 3CX Management Console, go to **Admin > Voice & Chat**.
      2. Click **Add Trunk**.
      3. Select any country and **Generic VoIP Provider (Registration)** in the provider field.

      .. figure:: https://doc.didww.com/_images/3cx_inbound1_registration.png
         :figclass: align-center
         :alt: Add SIP Registration inbound trunk in 3CX

         Fig. 14. Add a new SIP Registration inbound trunk in 3CX

Configure Trunk Settings
^^^^^^^^^^^^^^^^^^^^^^^^

.. tab-set::
   :class: my-tabs
   :sync-group: versions

   .. tab-item:: SIP URI
      :sync: sip-uri

      1. Enter a **Name** for the trunk (for example, ``DIDWW Inbound Trunk``).
      2. Clear the **Create an outbound rule for this SIP Trunk** checkbox.
      3. Enter your DID number in the **Main Trunk Number** field in **E.164 format without the plus sign** (for example, ``18489005419``).
      4. Select **Type of authentication** as ``Do not require - IP based``.
      5. In the **Registrar/Server** field, enter ``46.19.208.0/21``. In the **Port** field, enter ``5060``.

      .. note::
         If you plan to use the **AMS DIDWW PoP**, enter ``185.238.172.0/22`` instead of ``46.19.208.0/21`` in the **Registrar/Server** field. For more information, see :ref:`DIDWW SIP Inbound Technical Data <service_did_sip>`.

      .. figure:: https://doc.didww.com/_images/3cx_inbound2.png
         :figclass: align-center
         :alt: SIP URI trunk settings for the DIDWW inbound SIP trunk in 3CX

         Fig. 15. SIP URI trunk settings for the DIDWW inbound SIP trunk in 3CX

   .. tab-item:: SIP Registration
      :sync: sip-registration

      1. Enter a **Name** for the trunk (for example, ``DIDWW Registration``).
      2. Clear the **Create an outbound rule for this SIP Trunk** checkbox.
      3. Enter your DID number in the **Main Trunk Number** field in **E.164 format without the plus sign** (for example, ``18489005419``).
      4. Enter the DIDWW inbound trunk credentials in the **Authentication ID (SIP User ID)** and **Authentication password** fields.
      5. Make sure the **Type of authentication** is ``Register/Account based``.
      6. In the **Registrar/Server** field, enter ``sip.didww.com``. In the **Port** field, enter ``5060``.

      .. figure:: https://doc.didww.com/_images/3cx_inbound2_registration.png
         :figclass: align-center
         :alt: SIP Registration trunk settings for the DIDWW inbound SIP trunk in 3CX

         Fig. 16. SIP Registration trunk settings for the DIDWW inbound SIP trunk in 3CX

Configure Routing
^^^^^^^^^^^^^^^^^

During trunk creation, configure the default destination for inbound calls.

1. In the **Default route** section, select the destination type from the first dropdown (for example, **User**, **Ring Group**, **Queue**, or **Digital Receptionist**).
2. Depending on the selected type, configure the destination in the second field (for example, select a specific user, group, or queue).

.. figure:: https://doc.didww.com/_images/3cx_inbound3.png
   :figclass: align-center
   :alt: Configure the default route for inbound calls in 3CX

   Fig. 17. Configuring the default destination for inbound calls

Configure Additional DID Numbers (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you have multiple DID numbers, configure them on the trunk:

1. Open the **DID numbers** tab for the newly created trunk.
2. Click **Add** and enter your DID number or numbers in **E.164 format without the plus sign** (for example, ``16413545118``).

.. figure:: https://doc.didww.com/_images/3cx_inbound4.png
   :figclass: align-center
   :alt: Adding DID numbers to the inbound SIP trunk in 3CX

   Fig. 18. Adding DID numbers to the DIDWW Inbound SIP Trunk

Save the Inbound Trunk
^^^^^^^^^^^^^^^^^^^^^^

Click **Save** to create the trunk.

.. note::
   After the trunk is created, confirm that the DID numbers are listed correctly. 3CX may display an **Untested provider** warning. This warning indicates that the trunk uses a generic or custom provider profile and can be safely ignored.

.. figure:: https://doc.didww.com/_images/3cx_inbound5.png
   :figclass: align-center
   :alt: DIDWW inbound SIP trunk configured in 3CX

   Fig. 19. DIDWW Inbound SIP Trunk successfully configured on 3CX

Assign DIDs to Users or Destinations (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, inbound calls are routed according to the **Default route** configured during trunk creation.

If you have multiple DID numbers or require different routing per number, assign specific DIDs to users or other destinations.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Users

      1. In the 3CX Management Console, go to **Admin > Users**.
      2. Create a new user or edit an existing one.
      3. In **Assigned DID number(s)**, select the DID number that should route calls to this user.
      4. Click **Save**.

      .. figure:: https://doc.didww.com/_images/3cx_inbound_route_user.png
         :figclass: align-center
         :alt: Assign DID numbers to a user in 3CX

         Fig. 20. Assigning a DID number to a user in 3CX

   .. tab-item:: Call Handling

      1. In the 3CX Management Console, go to **Admin > Call Handling**.
      2. Create a new destination or edit an existing one, such as a **Ring Group**, **Queue**, or **Digital Receptionist**.
      3. Assign the DID number to the selected destination.
      4. Click **Save**.

      .. figure:: https://doc.didww.com/_images/3cx_inbound_route_call_handling.png
         :figclass: align-center
         :alt: Assign DID numbers in 3CX Call Handling

         Fig. 21. Assigning a DID number in 3CX Call Handling

----

.. raw:: html

    <br>

.. _3cx_configure_outbound_trunk:

Step 2: Configure the DIDWW Outbound SIP Trunk
----------------------------------------------

This trunk is used when 3CX places outbound calls to external phone numbers through DIDWW termination routes.

Add the Outbound Trunk in 3CX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the 3CX Management Console, go to **Admin > Voice & Chat**.
2. Click **Add Trunk**.
3. Select any country and **Generic SIP Trunk (IP Based)** in the provider field.

.. figure:: https://doc.didww.com/_images/3cx_outbound1.png
   :figclass: align-center
   :alt: Add outbound SIP trunk in 3CX

   Fig. 22. Add a new outbound SIP trunk in 3CX

Configure Trunk Settings
^^^^^^^^^^^^^^^^^^^^^^^^

1. Enter a **Name** for the trunk (for example, ``DIDWW Outbound Trunk``).
2. Ensure that **Create an outbound rule for this SIP Trunk** is selected.
3. Enter your DID number in the **Main Trunk Number** field in **E.164 format without the plus sign** (e.g., ``18489005419``).
4. Enter your **DIDWW Outbound Trunk Credentials** in the **Authentication ID (SIP User ID)** and **Authentication password** fields.
5. Select **Type of authentication** as ``Outbound - outbound only``.
6. In the **Registrar/Server** field, enter the DIDWW outbound SIP server (for example, ``out.didww.com``) or any other :ref:`DIDWW outbound signaling domain <services_voice_out>`. In the **Port** field, enter ``5060``.

.. figure:: https://doc.didww.com/_images/3cx_outbound2.png
   :figclass: align-center
   :alt: Outbound SIP trunk settings in 3CX

   Fig. 23. Trunk settings for the DIDWW Outbound SIP Trunk

Configure Additional DID Numbers (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you have multiple DID numbers, configure them on the trunk:

1. Open the **DID numbers** tab for the newly created trunk.
2. **Add** your DID number or numbers in **E.164 format without the plus sign** (e.g., ``16413545118``).

.. figure:: https://doc.didww.com/_images/3cx_outbound3.png
   :figclass: align-center
   :alt: Adding DID numbers to the outbound SIP trunk in 3CX

   Fig. 24. Adding DID numbers to the DIDWW Outbound SIP Trunk

Save the Outbound Trunk
^^^^^^^^^^^^^^^^^^^^^^^

Click **Save** to create the trunk.

Because **Create an outbound rule for this SIP Trunk** was selected during trunk configuration, 3CX opens the outbound rule configuration screen automatically.

.. note::
   After the trunk is created, confirm that the DID numbers are listed correctly. 3CX may display an **Untested provider** warning. This warning indicates that the trunk uses a generic or custom provider profile and can be safely ignored.

.. figure:: https://doc.didww.com/_images/3cx_outbound4.png
   :figclass: align-center
   :alt: DIDWW outbound SIP trunk configured in 3CX

   Fig. 25. DIDWW Outbound SIP Trunk successfully configured on 3CX

Configure Outbound Routing
^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In **Rule Name**, enter a name for the rule (for example, ``Outbound rule for DIDWW Outbound Trunk``).
2. In **Calls from Departments**, select at least one department that should be allowed to use this rule (for example, ``DEFAULT``).
3. In **Route 1**, select the **DIDWW Outbound Trunk**.
4. **Save** the outbound rule.

.. note:: Leave the remaining fields empty unless you want to restrict outbound calls by prefix, extension, or number length.

.. figure:: https://doc.didww.com/_images/3cx_outbound5.png
   :figclass: align-center
   :alt: Configure outbound rule in 3CX

   Fig. 26. Configuring outbound routing for DIDWW

Configure Caller ID (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, outbound calls use the caller ID defined by the trunk.

To control which DID number is presented for outbound calls, configure the caller ID on a per-user basis:

1. In the 3CX Management Console, go to **Admin > Users**.
2. Create a new user or edit an existing one.
3. In **Assigned DID number(s)**, select the DID number.
4. In **Outbound Caller ID**, select the DID number that should be presented for outbound calls.
5. Click **Save**.

.. note::
   The **Outbound Caller ID** field is available only when at least one DID number is assigned to the user.

.. figure:: https://doc.didww.com/_images/3cx_outbound_callerid.png
   :figclass: align-center
   :alt: Configure outbound caller ID in 3CX

   Fig. 27. Configuring additional outbound caller ID in 3CX

----

.. raw:: html

    <br>

.. _3cx_test_calls:

Step 3: Test Inbound and Outbound Calls
---------------------------------------

Before testing calls, ensure that at least one 3CX extension or client is registered.

Test Inbound Calls
^^^^^^^^^^^^^^^^^^

Verify that incoming calls from DIDWW numbers correctly reach your 3CX PBX.

    - From an external phone, call your DIDWW number.
    - Confirm that the call is delivered to 3CX and routed according to the configured inbound destination.
    - Answer the call and verify **two-way audio**.
    - If the call does not arrive, check the trunk settings, DID assignment, and firewall configuration.

Test Outbound Calls
^^^^^^^^^^^^^^^^^^^

Verify that outbound calls from 3CX are sent through the DIDWW Outbound Trunk.

    - From a registered 3CX extension, dial an external number.
    - Confirm that the call is routed through your **DIDWW Outbound Trunk**.
    - Verify **two-way audio**.
    - If the call fails, review outbound trunk registration, outbound rules, and caller ID settings.

.. note::
   - To troubleshoot, check the `DIDWW Inbound Call Logs <https://my.didww.com/#/call_logs>`_ and `Outbound Call Logs <https://my.didww.com/#/outbound_call_logs>`_ for response codes or call errors.

Additional Information
^^^^^^^^^^^^^^^^^^^^^^

For more details on configuring and managing your 3CX system, refer to the official 3CX documentation:

.. card:: **3CX User Manual**
    :link: https://www.3cx.com/docs/manual/
    :link-type: url

    Access the official 3CX documentation covering system configuration, SIP trunks, users, and call handling.

.. _3cx_releases_card:

.. card:: **3CX Release Notes**
    :link: https://www.3cx.com/blog/releases/
    :link-type: url

    Review the latest 3CX updates, feature releases, and improvements.

.. _3cx_sip_trunk_card:

.. card:: **3CX SIP Trunk Guides**
    :link: https://www.3cx.com/docs/manual/sip-trunks/
    :link-type: url

    Explore additional SIP trunk configuration examples and best practices.


.. _amazon:

.. |br| raw:: html

   <br />

================
Amazon Chime SDK
================

Introduction
============

Amazon Chime SDK is the underlying platform provided by Amazon Web Services (AWS) that enables businesses to receive phone calls over the internet with the help of Amazon Chime Voice Connector.

With Amazon Chime Voice Connector and DIDWW SIP Trunks, businesses can use their own telephone numbers to receive phone calls.
This allows businesses to maintain a consistent communication experience with their customers.

Amazon Chime Voice Connector is designed to be simple to set up and manage, and can be integrated with other AWS services, for example such as Amazon S3 and Amazon Lambda, for more advanced use cases.

This configuration guide describes how to set up Amazon Chime Voice Connector using SIP Media Application with basic Amazon Lambda sample code to interwork with DIDWW inbound SIP trunk services (Fig. 1).

If all required services are already active, the expected amount of time to complete this deployment/integration is 15-30 minutes.

.. figure:: https://doc.didww.com/_images/figure1.jpg
  :figclass: align-center
  :alt: Call flow between a DIDWW phone number, Amazon Chime Voice Connector, SIP Media Application, and AWS Lambda

  **Fig. 1.** Basic flow diagram.

Getting started
===============

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`_.
* `An inbound SIP trunk <https://doc.didww.com/voice/inbound-trunks/creating-a-new-sip-trunk.html>`_  at DIDWW.
* `A DID number provisioned from DIDWW <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`_.
* `Amazon Web Services console access <https://console.chime.aws.amazon.com/>`_.
* `Amazon Chime SDK Voice Connector  <https://us-east-1.console.aws.amazon.com/chime-sdk/home?region=us-east-1#/voiceConnectors>`_. 
* `Amazon Chime SDK SIP Media Application <https://us-east-1.console.aws.amazon.com/chime-sdk/home?region=us-east-1#/sipMediaApplications>`_.
* `Amazon Lambda <https://us-east-1.console.aws.amazon.com/lambda/home?region=us-east-1#/functions>`_.

AWS Requirements
================

This integration guide requires familiarity with AWS IAM - (Identity and Access Management), AWS Chime SDK and AWS Lambda node.js scripting.

**Billable AWS services will be required**

 * Amazon Chime SDK SIP Trunking: Depends on the region selected and operates on a pay-per-use billing model. No specific resource size allocation is needed. More details can be found `here <https://aws.amazon.com/chime/chime-sdk/pricing/>`__.
 * AWS Lambda: Depends on the region selected and is based on a pay-per-use billing model. No specific resource size allocation is needed. More details can be found `here <https://aws.amazon.com/lambda/pricing/>`__.
 * AWS S3 Bucket: The billing rate depends on object size, how long objects are stored during the month, and the storage class. In this guide, we will use the S3 Standard storage class. More details can be found `here <https://aws.amazon.com/s3/pricing/>`__.

**AWS Regions**

AWS regions are designed to be isolated from other regions to achieve the greatest possible fault tolerance and stability. By using regions, you can place resources, such as compute and storage, in multiple locations closer to your equipment, interconnection partners, or users.

This integration can be deployed in any of Amazon Web Services' (AWS) regions, provided that the selected region supports Amazon Chime SDK, AWS Lambda, and AWS S3 Bucket.

**AWS Security and backups**

No public access will be required for any of the AWS resources mentioned in this guide. Additionally, IAM or ROOT access key creation will not be necessary, as no programmatic calls to AWS will be used.
Sensitive users data will not be stored in any of these resources, and no proprietary data stores will be in use. Therefore, there are no specific recommendations for data backups. If you plan to use such types of storage in your own implementation, please consider `AWS backup service <https://docs.aws.amazon.com/aws-backup/>`_.

AWS root privileges are not required for this deployment/integration. The following IAM (Identity and Access Management) permission policies are required:

.. collapse:: CloudWatch Logs

    ::

            {
                "Version": "2012-10-17",
                "Statement": [
                    {
                        "Sid": "VisualEditor0",
                        "Effect": "Allow",
                        "Action": [
                            "logs:CreateLogDelivery",
                            "logs:DeleteLogDelivery",
                            "logs:GetLogDelivery",
                            "logs:ListLogDeliveries",
                            "logs:DescribeLogGroups",
                            "logs:DescribeLogStreams"
                        ],
                        "Resource": "*"
                    }
                ]
            }

.. collapse:: S3 Bucket

    ::

            {
                "Version": "2012-10-17",
                "Statement": [
                    {
                        "Sid": "VisualEditor0",
                        "Effect": "Allow",
                        "Action": [
                            "s3:ListAllMyBuckets",
                            "s3:ListBucket",
                            "s3:ListBucketVersions",
                            "s3:ListBucketMultipartUploads",
                            "s3:ListAccessPointsForObjectLambda",
                            "s3:ListAccessPoints",
                            "s3:ListMultipartUploadParts"
                        ],
                        "Resource": "*"
                    }
                ]
            }

.. collapse:: Chime

    ::

            {
                "Version": "2012-10-17",
                "Statement": [
                    {
                        "Sid": "VisualEditor0",
                        "Effect": "Allow",
                        "Action": "chime:*",
                        "Resource": "*"
                    }
                ]
            }

.. collapse:: Lambda

    ::

            {
                "Version": "2012-10-17",
                "Statement": [
                    {
                        "Sid": "VisualEditor0",
                        "Effect": "Allow",
                        "Action": "lambda:*",
                        "Resource": "*"
                    }
                ]
            }

|br|
**Routine Maintenance**

As no programmatic calls to AWS are required for this integration, there are no specific guidelines for managing IAM or ROOT access keys. However, if you do use access keys, it is recommended as a best practice to regularly rotate them. More details can be found `here <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_RotateAccessKey>`__.
There are no specific recommendations for software patches, updates, or license management, as this guide does not include any software. If you decide to include additional software in your integration, guidance for recommendations can be found `here <https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-manager.html>`__ and `here <https://docs.aws.amazon.com/license-manager/latest/userguide/license-manager.html>`__.
To ensure a proper functionality of the described integration, you can review your DIDWW `Call Logs <https://my.didww.com/#/call_logs>`_ and `Dashboard <https://my.didww.com/#/>`_ charts. It is also recommended to review AWS CloudWatch logs and monitoring options, as described `here <https://docs.aws.amazon.com/chime-sdk/latest/ag/monitoring-overview.html>`__.

**Emergency maintenance**

For handling fault conditions, a trouble ticket needs to be opened via email at support@didww.com. The ticket should include a fault description, information on affected services, account details, and sample call specifics if possible. The Technical Support team will investigate the reported fault and provide an update with a solution or advise on further actions that can be taken.
Regarding software recovery, this integration example does not necessitate specialized software. Therefore, you can simply recover it by following the configuration steps outlined in this guide. If you have incorporated any additional software, it falls under your responsibility to maintain backups for emergency recovery scenarios.

.. _amazon_chime_voice_connector:

Creating Amazon Chime Voice Connector
=====================================

**Step 1.**

•	Select *Voice connector* in the Chime SDK menu.
•	Click *Create new voice connector* button. (Fig. 2).

.. figure:: https://doc.didww.com/_images/figure2.png
  :figclass: align-center
  :alt: Amazon Chime SDK Voice connectors page with the Create new voice connector button

  **Fig. 2.** Creating a new voice connector.

**Step 2.**

•	Enter *Voice connector name*.
•	For Encryption (TLS) select *Enabled* or *Disabled* for UDP (Fig. 3).

.. figure:: https://doc.didww.com/_images/figure3.png
  :figclass: align-center
  :alt: Amazon Chime Voice Connector creation form showing its name and encryption settings

  **Fig. 3.** Voice connector configuration.

**Step 3.**

•	In the Voice connector select tab *Termination*.
•	Set Termination status to *Enabled*.
•	Copy/note *Outbound host name*. (Fig. 4). (Outbound host name will be used later when configuring DIDWW SIP inbound trunk.)

.. figure:: https://doc.didww.com/_images/figure4.png
  :figclass: align-center
  :alt: Amazon Chime Voice Connector Termination tab showing the outbound host name

  **Fig. 4.** Termination tab configuration.

**Step 4.**

Add DIDWW inbound signaling IP addresses to the Amazon Chime SDK voice connector *Allowed hosts list* tab, as shown in the example below (Fig. 5).

.. code-block::

  46.19.209.14 (for New York POP)
  46.19.210.14 (for Frankfurt POP)
  46.19.212.14 (for Los Angeles POP)
  46.19.213.14 (for Miami POP)
  46.19.214.14 (for Singapore POP)
  46.19.215.14 (for Hong Kong POP)
  185.238.173.14 (for Amsterdam POP)

.. figure:: /img/new_user_panel/integrations/amazon/figure5.png
  :figclass: align-center
  :alt: Amazon Chime Voice Connector Allowed hosts list containing DIDWW signaling IP addresses

  **Fig. 5.** Adding DIDWW inbound signalling IPs.

Creating Amazon Lambda function
===============================

**Step 1.**

•	In the *AWS Lambda* menu choose *Functions*.
•	Click *Create function*. (Fig. 6).

.. figure:: https://doc.didww.com/_images/figure6.png
  :figclass: align-center
  :alt: AWS Lambda Functions page with the Create function button

  **Fig. 6.** Creating AWS Lambda function.

**Step 2.**

•	Choose to use code from available blueprints.
•	Select *“Hello world function”*.
•	In the *“Function”* name field enter the function name of your choice.
•   For the *“Execution role”* leave the default selection *(“Create a new role with basic Lambda permissions”)* (Fig. 7).
•   Click the *“Create”* button at the bottom of the page.

.. figure:: https://doc.didww.com/_images/figure7.png
  :figclass: align-center
  :alt: AWS Lambda function creation form configured from a blueprint

  **Fig. 7.** Creating AWS Lambda function.

**Step 3.**

•	The next window allows you to write, deploy, and test your Lambda code.
•   Copy/note *Function ARN* name (Fig. 8). (It will be used in the next step.)

A basic example of *Lambda node.js* code that passes Source and Destination Number to an external URL.

.. code-block:: js

            const https = require('https');
        exports.handler = async (event) => {
           let dataString = '';
           var source='';
           source=event.CallDetails?.Participants[0].From;
           var destination='';
           destination=event.CallDetails?.Participants[0].To;

           const response = await new Promise((resolve, reject) => {
               const req = https.get(`https://example.com/?source=${source}&destination=${destination}`, function(res) {
                 res.on('data', chunk => {
                   dataString += chunk;
                 });
                 res.on('end', () => {
                   resolve({
                       statusCode: 200,
                        body: (dataString),
                   });
                 });
               });
               req.on('error', (e) => {
                 reject({
                     statusCode: 500,
                     body: 'Something went wrong!'
                 });
               });
           });
           return response;
         };

.. figure:: /img/new_user_panel/integrations/amazon/figure8.png
  :figclass: align-center
  :alt: AWS Lambda function overview showing the function ARN and code editor

  **Fig. 8.** Function overview.

Creating Amazon Chime SIP Media Application
===========================================

**Step 1.**

•	Choose *SIP media applications* in your Chime SDK menu.
•	Click *Create* (Fig. 9).

.. figure:: https://doc.didww.com/_images/figure9.png
  :figclass: align-center
  :alt: Amazon Chime SDK SIP media applications page with the Create button

  **Fig. 9.** Creating SIP media application.

**Step 2.**

•	Enter a SIP media application name of your choice.
•	Paste the previously copied *Lambda Function ARN* name (Fig. 8).
•	Click *“Create a SIP media application”* (Fig. 10).

.. figure:: https://doc.didww.com/_images/figure10.png
  :figclass: align-center
  :alt: Amazon Chime SIP media application creation form with a Lambda function ARN

  **Fig. 10.** Filling in the required data.

Creating Amazon Chime SIP rule
==============================

**Step 1.**

•	Choose *SIP rules* in your Chime menu.
•	Click *Create SIP rule* (Fig. 11).

.. figure:: https://doc.didww.com/_images/figure11.png
  :figclass: align-center
  :alt: Amazon Chime SDK SIP rules page with the Create SIP rule button

  **Fig. 11.** Creating SIP rule.

**Step 2.**

•	Enter a rule name of your choice.
•	In the *Trigger type* dropdown menu select *Request URI hostname*.
•	In the *Request URI hostname* select the previously created *Amazon Chime Voice Connector* hostname (Fig. 4).
•	In the *SIP media applications* add previously created *SIP media application* (Fig. 10).
•	Click *Create SIP rule* (Fig. 12).

.. figure:: https://doc.didww.com/_images/figure12.png
  :figclass: align-center
  :alt: Amazon Chime SIP rule form configured with a request URI hostname and SIP media application

  **Fig. 12.** Selecting fields.

Creating DIDWW SIP trunk
========================

Step 1: Create New SIP Trunk
----------------------------

1. `Sign in to the DIDWW User Panel <https://my.didww.com/users/sign_in>`_.
2. Go to **Voice > Inbound Trunks**.
3. Click **Create New > SIP Trunk** (Fig. 13).

.. figure:: https://doc.didww.com/_images/figure13.png
  :figclass: align-center
  :alt: DIDWW Inbound Trunks page with the Create New menu open and SIP Trunk selected

  **Fig. 13.** Creating a new SIP trunk.

Step 2: Configure SIP Trunk Settings
------------------------------------

In the **General** tab:

1. Enter a descriptive **Name** for the trunk (for example, ``Amazon Chime``).
2. Select **Static Endpoint**.
3. Enter ``+{DID}`` in **User Part of R-URI**.
4. In **Host**, enter the Amazon SIP connector **Outbound host name** copied when :ref:`creating the Amazon Chime Voice Connector <amazon_chime_voice_connector>` (Fig. 4).
5. Select the **Transport** used by the Amazon Chime Voice Connector.
6. Enter the corresponding **Port**:

   - ``5060`` for **UDP** or **TCP**
   - ``5061`` for **TLS**

.. figure:: https://doc.didww.com/_images/figure14.png
  :figclass: align-center
  :alt: DIDWW inbound SIP trunk General tab configured for Amazon Chime

  **Fig. 14.** Configuring general tab for a new SIP trunk.

In the **Number Translations** tab:

1. Select **E.164 - International format** in **CLI Format**.
2. Enter ``+`` in **CLI Prefix**.
3. Click **Create** to save the inbound SIP trunk.

.. figure:: https://doc.didww.com/_images/figure14.5.png
  :figclass: align-center
  :alt: DIDWW inbound SIP trunk Number Translations tab configured for Amazon Chime

  **Fig. 15.** Configuring Number Translations tab and creating the sip trunk.

Assigning SIP trunk to your number at DIDWW
===========================================

Step 1: Open the Trunk Assignment
---------------------------------

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Locate the DID number and click its trunk name or **Voice: none** in the **Trunk** column (Fig. 16).

.. figure:: https://doc.didww.com/_images/figure15.png
  :figclass: align-center
  :alt: DIDWW My Numbers page showing the Trunk column for a DID number

  **Fig. 16.** Editing DID number voice trunk.

Step 2: Assign the SIP Trunk
----------------------------

1. Select the previously created Amazon Chime inbound SIP trunk.
2. Click **Confirm** (Fig. 17).

.. figure:: https://doc.didww.com/_images/figure16.png
  :figclass: align-center
  :alt: DIDWW trunk assignment dialog with the Amazon Chime inbound SIP trunk selected

  **Fig. 17.** Assigning voice trunk.

Testing and Troubleshooting
===========================

Testing and troubleshooting can be performed by following these steps: |br| |br|
•   Place a test call to DIDWW DID number; |br|
•   Check `Call Logs <https://my.didww.com/#/call_logs>`_ in your DIDWW account to determine if the test call reached your DIDWW DID number; |br|
•   By using `AWS CloudWatch <https://console.aws.amazon.com/cloudwatch/>`_ or directly via `AWS S3 <https://s3.console.aws.amazon.com/s3>`_ storage check Chime Voice Connector and Lambda Function logs to see if both were executed successfully; |br|
•   Validate if request from AWS Lambda Function was successfully received on your external URL/HTTP server. |br|

Support and Additional Resources
================================

* `For additional information, please review Amazon Chime SDK documentation <https://aws.amazon.com/chime/chime-sdk/resources/>`_.
* For more information or additional troubleshooting please contact DIDWW Technical Support Team at support@didww.com. Support is available 24/7/365 for all current customers. We do not utilize a Support Tiers system. Service Level Agreements (SLAs) are provided in accordance with our general terms and agreements.


.. _yeastar:

====================
Yeastar P-Series PBX
====================

Use the **Yeastar P-Series PBX System** with **DIDWW SIP Trunking** to deliver inbound and outbound voice services over the public telephone network.
DIDWW SIP trunks integrate with Yeastar to bring calls from your DIDs into the PBX, apply Yeastar call control features, and route outbound calls through DIDWW termination.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Bring inbound calls from your DIDWW DIDs into Yeastar P-Series PBX.
      - Route calls to extensions, ring groups, queues, or IVRs.
      - Apply Yeastar features such as time conditions, voicemail, and call recording.

   .. grid-item::
      :class: left-align-block

      - Use DIDWW outbound SIP trunks for local and international calling.
      - Present DIDWW DIDs as caller ID based on Yeastar outbound rules.
      - Combine DIDWW connectivity with Yeastar dialing plans and user permissions.

----

.. _yeastar_inbound:

1. Create Inbound SIP Trunk
===========================

To begin connecting your **DIDWW account** with the **Yeastar P-Series PBX**, first create an **Inbound SIP Trunk**.
This trunk will establish the path for incoming calls from your DIDWW numbers to reach Yeastar.

Before You Begin
-----------------

    - An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
    - At least one active **DID number** with capacity to receive incoming calls is required. `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_.

Step 1: Create New SIP Trunk
----------------------------

    1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
    2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/didww_inbound1.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Fig. 1. Creating a new inbound SIP trunk

.. _yeastar_inbound_sip_tunk_settings:

Step 2: Configure SIP Trunk Settings
------------------------------------

Depending on whether you plan to use the self-hosted version of the PBX or the cloud-based version of the PBX, the configuration will differ slightly.

.. tab-set::
   :class: my-tabs
   :sync-group: versions

   .. tab-item:: Self-Hosted Version
      :sync: self-hosted

      In the Create Inbound SIP Trunk form, enter the main requirements to route the calls to your Yeastar P-Series PBX.

      1. In the **General** tab, enter a descriptive **Name** for the trunk (e.g., ``Yeastar Trunk``).
      2. Select **Static Endpoint**.
      3. In **Host**, enter the public IP address or FQDN of your Yeastar P-Series PBX.
      4. Select the **Transport** supported by your Yeastar P-Series PBX.
      5. Enter the corresponding **Port**:

         - ``5060`` for **UDP** or **TCP**
         - ``5061`` for **TLS**

      .. figure:: https://doc.didww.com/_images/didww_inbound2.png
         :figclass: align-center
         :alt: SIP trunk configured to send calls to Yeastar

         Fig. 2. SIP trunk configured to send calls to self-hosted Yeastar P-Series PBX

   .. tab-item:: Cloud-Based Version
      :sync: cloud-based

      In the Create Inbound SIP Trunk form, enter the main requirements to route the calls to your Yeastar P-Series PBX.

      1. In the **General** tab, enter a descriptive **Name** for the trunk (e.g., ``Yeastar Trunk``).
      2. Select **Static Endpoint**.
      3. Select the **Preferred Server** (e.g., ``DE, FRA``).
      4. In **Host**, enter a **placeholder** IP address (e.g., ``198.51.100.0``).
      5. Select the **Transport** supported by your Yeastar P-Series PBX.
      6. Enter the corresponding **Port**:

         - ``5060`` for **UDP** or **TCP**
         - ``5061`` for **TLS**

      .. note::
         - The **Preferred Server** defaults to ``DE, FRA`` on the cloud-based Yeastar P-Series PBX. If you select a different **Preferred Server**, additional steps will be required on the Yeastar PBX side.
         - The real host IP address will be revealed once you :ref:`add the trunk on the Yeastar PBX <yeastar_configure>`.

      .. figure:: https://doc.didww.com/_images/didww_inbound2_cloud.png
         :figclass: align-center
         :alt: SIP trunk configured to send calls to Yeastar

         Fig. 3. SIP trunk configured to send calls to cloud-based Yeastar P-Series PBX

.. _yeastar_create_inbound_trunk_authentication:

Step 3: Click Create and Save Inbound SIP Trunk Configuration
-------------------------------------------------------------

When the required fields in the Create Inbound SIP Trunk are filled, click **Create** to save your inbound SIP trunk.

.. note:: If your deployment requires additional features, see :ref:`Advanced Inbound SIP Trunk documentation <user_panel_sipin_trunk>`.

.. figure:: https://doc.didww.com/_images/didww_inbound3.png
   :figclass: align-center
   :alt: Inbound SIP trunk created

   Fig. 4. Create the Inbound SIP Trunk

Step 4: Assign Inbound SIP Trunk to Your DID Numbers
----------------------------------------------------

After creating the Inbound SIP Trunk for Yeastar, assign it to the DID number(s) that will deliver incoming calls to your Yeastar P-Series PBX.

    1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
    2. Select the DID number(s) you want to assign to the inbound SIP trunk.
    3. At the bottom of the page, click **Batch Actions > Update Trunks**.

    .. figure:: https://doc.didww.com/_images/didww_inbound4.png
       :figclass: align-center
       :alt: Assigning a SIP trunk to DID numbers

       Fig. 5. Selecting **Update Trunks** from the Batch Actions menu

    4. From the dropdown menu, choose the **Yeastar Trunk** you created earlier.
    5. Click **Confirm** to apply the changes.

    .. figure:: https://doc.didww.com/_images/didww_inbound5.png
       :figclass: align-center
       :alt: Assigning a SIP trunk to DID numbers

       Fig. 6. Assigning the newly created SIP trunk to the selected DID(s)

----

.. _yeastar_outbound:

2. Create Outbound SIP Trunk
============================

To configure outbound calling from your Yeastar P-Series PBX, create an **Outbound SIP Trunk** in the DIDWW User Panel.
This setup enables you to use Yeastar to place outbound calls through DIDWW termination routes.

Before You Begin
-----------------

    - Access to **DIDWW Outbound Trunks** is required for making outbound calls. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

Step 1: Create New Outbound Voice Trunk
---------------------------------------

    1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Outbound Trunks**.
    2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/didww_outbound1.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Fig. 7. Creating a new outbound SIP trunk

.. _yeastar_outbound_sip_trunk_settings:

Step 2: Configure SIP Trunk Settings
------------------------------------

Depending on whether you plan to use the self-hosted version of the PBX or the cloud-based version of the PBX, the configuration will differ slightly.

.. tab-set::
   :class: my-tabs
   :sync-group: versions

   .. tab-item:: Self-Hosted Version
      :sync: self-hosted

      1. Update the **Friendly Name** (e.g., ``Yeastar Outbound Trunk``).
      2. Keep the default **Credentials & IP-based** authentication method selected. The SIP digest credentials (username and password) will be accessible after the trunk is created.
      3. In **Allowed SIP IP addresses**, enter the public IP address or subnet from which your Yeastar P-Series PBX will send outbound SIP traffic.

      .. note::
         Make sure you add the correct IP address or subnet so that outbound calls are accepted by DIDWW.

      .. figure:: https://doc.didww.com/_images/didww_outbound2.png
         :figclass: align-center
         :alt: Outbound SIP Trunk configuration for self-hosted Yeastar P-Series PBX

         Fig. 8. Outbound SIP Trunk configuration for self-hosted Yeastar P-Series PBX

   .. tab-item:: Cloud-Based Version
      :sync: cloud-based

      1. Update the **Friendly Name** (e.g., ``Yeastar Outbound Trunk``).
      2. Keep the default **Credentials & IP-based** authentication method selected. The SIP digest credentials (username and password) will be accessible after the trunk is created.
      3. In **Allowed SIP IP addresses**, enter a **placeholder** IP address (e.g., ``198.51.100.0``).

      .. note::
         - The real host IP address will be revealed once you :ref:`add the trunk on the Yeastar PBX <yeastar_configure>`.
         - Optionally you can allow all traffic by adding ``0.0.0.0/0``, which removes all IP restrictions. Although SIP Digest Authentication will still verify requests using valid credentials, this setup is not recommended.

      .. figure:: https://doc.didww.com/_images/didww_outbound2_cloud.png
         :figclass: align-center
         :alt: Outbound SIP Trunk configuration for cloud-based Yeastar P-Series PBX

         Fig. 9. Outbound SIP Trunk configuration for cloud-based Yeastar P-Series PBX

.. _yeastar_create_outbound_trunk:

Step 3: Click Create and Save Outbound SIP Trunk Configuration
--------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk are filled, click **Create** to save your outbound SIP trunk.

.. note:: For advanced outbound SIP trunk configuration, see :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/didww_outbound3.png
   :figclass: align-center
   :alt: Outbound SIP trunk created

   Fig. 10. Outbound SIP trunk created and ready for use

.. _yeastar_create_outbound_trunk_copy_credentials:

Step 4: View Outbound Trunk Credentials
---------------------------------------

When the outbound trunk is created you can view its credentials by selecting the key icon in the **Credentials** column on the Outbound Trunks page.

    1. Go to **Voice > Outbound Trunks**.
    2. Locate your outbound trunk and click the **key icon** in the **Credentials** column.

    .. figure:: https://doc.didww.com/_images/didww_outbound4.png
       :figclass: align-center
       :alt: Accessing outbound trunk credentials

       Fig. 11. Opening the outbound trunk credentials view

    3. The trunk credentials will appear, showing the **Username** and **Password** (click the **eye icon** to reveal the password).
    4. **Copy and save** these credentials for further steps :ref:`configuring the outbound SIP trunk <yeastar_configure_outbound_trunk>` on your Yeastar P-Series PBX.

    .. warning:: If the credentials become exposed to unauthorized parties, :ref:`rotate them immediately in the DIDWW User Panel <view_outbound_trunk_credentials>`.

    .. figure:: https://doc.didww.com/_images/didww_outbound5.png
       :figclass: align-center
       :alt: Accessing outbound trunk credentials

       Fig. 12. Opening the outbound trunk credentials view

----

.. _yeastar_configure:

3. Configure the Yeastar P-Series PBX
=====================================

To complete your integration, configure the DIDWW SIP trunking settings inside the **Yeastar P-Series PBX**.
This setup links your DIDWW Inbound and Outbound SIP Trunks to Yeastar, allowing the PBX to manage call routing, features, and call handling for both inbound and outbound traffic.

.. note::
   For more information, see the official
   `Yeastar P-Series PBX SIP Trunk Configuration Guide <https://www.yeastar.com/itsp-partners/p-series-pbx-register-trunk-configuration-guide/>`_.

Before You Begin
-----------------

    - Administrator access to the Yeastar P-Series PBX interface is required.
    - A configured :ref:`DIDWW Inbound SIP Trunk <yeastar_inbound>` and :ref:`DIDWW Outbound SIP Trunk <yeastar_outbound>` is required before proceeding.
    - If using the **Self-Hosted** edition behind a firewall or NAT:

        - Port forwarding on your router should be in place for SIP and RTP traffic (UDP 5060 for SIP, UDP 10000–12000 for RTP audio).
        - The **Public IP** address should be correctly defined in the Yeastar Network settings.

.. _yeastar_configure_inbound_trunk:

Step 1: Configure the DIDWW Inbound SIP Trunk
----------------------------------------------

This trunk is used for Yeastar P-Series PBX to receive calls forwarded from the DIDWW DID number through DIDWW Inbound SIP Trunk.

Add the Inbound Trunk in Yeastar PBX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. In the Yeastar PBX Admin interface, go to **Extension & Trunk > Trunk**.
    2. Click **Add**.

.. figure:: https://doc.didww.com/_images/yeastar_inbound1.png
   :figclass: align-center
   :alt: Add Trunk Button on Yeastar P-Series PBX

   Fig. 13. Add Trunk Button on Yeastar P-Series PBX

Configure Basic Settings
^^^^^^^^^^^^^^^^^^^^^^^^

    1. Enter a **Name** for the trunk (e.g., ``DIDWW_Inbound_Trunk``).
    2. In **ITSP Template**, select the template corresponding to your region. DIDWW templates are available for:

        - France
        - Germany
        - Spain
        - Singapore
        - Thailand

    3. In **ITSP**, select **DIDWW-Inbound**.
    4. Ensure **Trunk Status** is set to **Enabled**.

.. note::
   Selecting a DIDWW ITSP template automatically fills most required SIP parameters in the **Detailed Configuration** section.

.. figure:: https://doc.didww.com/_images/yeastar_inbound2.png
   :figclass: align-center
   :alt: Yeastar P-Series PBX Inbound SIP Trunk Basic Settings

   Fig. 14. Basic settings for the DIDWW Inbound SIP Trunk

Detailed Configuration
^^^^^^^^^^^^^^^^^^^^^^

This section is part of the basic trunk setup.
The detailed configuration depends on whether you are using the **self-hosted** or **cloud-based** version of the Yeastar P-Series PBX.

.. tab-set::
   :class: my-tabs
   :sync-group: versions

   .. tab-item:: Self-Hosted Version
      :sync: self-hosted

      The default values provided by the DIDWW template are sufficient.
      No additional configuration changes are required.

      .. note::
         The DIDWW template automatically configures the primary IP (e.g., ``46.19.210.14``) and whitelists the necessary backup IPs in the background. This configuration works for all regions and ensures that calls from :ref:`any DIDWW Point of Presence <service_did_sip>` are accepted.

   .. tab-item:: Cloud-Based Version
      :sync: cloud-based

      1. Copy the **Static IP Address** displayed in the trunk form.
         You will later replace placeholder Hostname/IP values in your DIDWW trunks using this IP.
      2. If you selected a different **Preferred Server** in the DIDWW User Panel, update the **Hostname/IP** and **Domain** fields to match the correct signaling PoP.
         Refer to the :ref:`DIDWW inbound SIP endpoints <service_did_sip>` for the correct regional IP.

      .. figure:: https://doc.didww.com/_images/yeastar_inbound3_cloud.png
         :figclass: align-center
         :alt: Cloud-Based Yeastar P-Series PBX Inbound SIP Trunk Detailed Configuration

         Fig. 15. Cloud-Based Yeastar P-Series PBX Inbound SIP Trunk Detailed Configuration

      .. raw:: html

           <br>
           <h4
            id="replace-placeholders-cloud"
            >Enter Yeastar Static IPs in DIDWW SIP Trunks<a class="headerlink" href="#replace-placeholders-cloud"></a>
           </h4>

      During the initial **Create Inbound and Outbound SIP Trunk** steps, a temporary placeholder IP address was entered to allow the trunks to be created.
      After receiving the **Static IP Address** for your Yeastar Cloud PBX in the configuration details, update both DIDWW trunks so that call traffic is routed to the correct Yeastar endpoint.

      .. raw:: html

           <br>
           <h5
            id="replace-placeholders-inbound-trunk"
            >Update Inbound SIP Trunk<a class="headerlink" href="#replace-placeholders-inbound-trunk"></a>
           </h5>

      1. Open the `Inbound Trunks <https://my.didww.com/#/trunks/>`_ page in the DIDWW User Panel.
      2. Open the actions menu for your DIDWW inbound trunk and click **Edit**.
      3. In the **General** tab, replace the placeholder **Host** with the **Static IP Address** obtained from Yeastar Cloud PBX.
      4. Click **Submit**.

      .. figure:: https://doc.didww.com/_images/yeastar_inbound4_cloud.png
         :figclass: align-center
         :alt: Replace the Placeholder IP Address for DIDWW Inbound SIP Trunk

         Fig. 16. Updating the Host for the DIDWW Inbound SIP Trunk

      .. raw:: html

           <br>
           <h5
            id="replace-placeholders-outbound-trunk"
            >Update Outbound SIP Trunk<a class="headerlink" href="#replace-placeholders-outbound-trunk"></a>
           </h5>

      1. Open the `Outbound Trunks <https://my.didww.com/#/outbound_trunks/>`_ page in the DIDWW User Panel.
      2. Click **Actions > Edit** on your DIDWW outbound trunk.
      3. Replace the placeholder in **Allowed SIP IP Addresses** with the **Static IP Address** obtained from Yeastar Cloud PBX.
      4. Click **Submit**.

      .. figure:: https://doc.didww.com/_images/yeastar_inbound5_cloud.png
         :figclass: align-center
         :alt: Replace the allowed SIP IP address for the DIDWW Outbound SIP Trunk

         Fig. 17. Updating Allowed SIP IP Addresses for the DIDWW Outbound SIP Trunk

.. _yeastar_configure_inbound_trunk_advanced:

Configure Advanced Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. Open the **Advanced** tab.
    2. Under **VoIP Settings**, enable **Qualify**.
       This allows the PBX to monitor trunk reachability using SIP OPTIONS packets.

.. figure:: https://doc.didww.com/_images/yeastar_inbound6.png
   :figclass: align-center
   :alt: Yeastar P-Series PBX Inbound SIP Trunk Advanced Settings

   Fig. 18. Advanced settings for the DIDWW Inbound SIP Trunk

Add DIDs to the Yeastar Inbound SIP Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. Open the **DIDs/DDIs** tab.
    2. Click **Add**.
    3. In the pop-up window, configure:

        - **Create Method**: ``Single DID``
        - **DID/DDI**: Enter your DID in **E.164 format without the +**, e.g., ``18489005419``
        - **DID/DDI Name**: Provide a friendly label (e.g., ``My US DIDWW Number``).

    4. Click **Confirm**, then click **Save** to finalize the trunk.

.. figure:: https://doc.didww.com/_images/yeastar_inbound7.png
   :figclass: align-center
   :alt: Add a DID and Save the Yeastar P-Series PBX Inbound SIP Trunk

   Fig. 19. Adding a DID to the Yeastar Inbound SIP Trunk

Apply the Changes to the Yeastar Inbound SIP Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once you return to the **Trunk** list, click **Apply** to activate the configuration.

.. figure:: https://doc.didww.com/_images/yeastar_inbound8.png
   :figclass: align-center
   :alt: Apply changes on the Yeastar PBX

   Fig. 20. Applying changes to the trunk configuration

The trunk status will update to **Reachable** once the connection is established.

.. figure:: https://doc.didww.com/_images/yeastar_inbound9.png
   :figclass: align-center
   :alt: Yeastar inbound trunk reachable

   Fig. 21. DIDWW Inbound SIP Trunk successfully configured on Yeastar

----

.. _yeastar_configure_outbound_trunk:

Step 2: Configure the DIDWW Outbound Trunk
---------------------------------------------

This trunk is used when the Yeastar P-Series PBX places outbound calls to external phone numbers through DIDWW.

Add the Outbound Trunk in Yeastar PBX
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. In the Yeastar PBX Admin interface, go to **Extension & Trunk > Trunk**.
    2. Click **Add**.

.. figure:: https://doc.didww.com/_images/yeastar_outbound1.png
   :figclass: align-center
   :alt: Add a new outbound SIP trunk on Yeastar P-Series PBX

   Fig. 22. Add a new outbound SIP trunk

Configure Basic Settings
^^^^^^^^^^^^^^^^^^^^^^^^

Begin by configuring the general trunk parameters:

    1. Enter a **Name** for the trunk (e.g., ``DIDWW_Outbound_Trunk``).
    2. In **ITSP Template**, select the template corresponding to your region. DIDWW templates are available for:

        - France
        - Germany
        - Spain
        - Singapore
        - Thailand

    3. In **ITSP**, select **DIDWW-Outbound**.
    4. Ensure **Trunk Status** is set to **Enabled**.

.. figure:: https://doc.didww.com/_images/yeastar_outbound2.png
   :figclass: align-center
   :alt: Yeastar Outbound SIP Trunk basic settings

   Fig. 23. Basic settings for the DIDWW Outbound SIP Trunk

Enter Authentication Details
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Enter your DIDWW Outbound Trunk username and password in the corresponding **Username and Password** fields.

.. figure:: https://doc.didww.com/_images/yeastar_outbound3.png
   :figclass: align-center
   :alt: Yeastar Outbound SIP Trunk Detailed Configuration

   Fig. 24. Yeastar P-Series PBX Outbound SIP Trunk Detailed Configuration

.. _yeastar_configure_outbound_trunk_advanced:

Configure Advanced Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Open the **Advanced** tab.
2. Under **VoIP Settings**, enable **Qualify**.
   This allows the PBX to monitor trunk reachability using SIP OPTIONS packets.

.. figure:: https://doc.didww.com/_images/yeastar_outbound4.png
   :figclass: align-center
   :alt: Yeastar Outbound SIP Trunk Advanced Settings

   Fig. 25. Enable Qualify in Advanced Settings

Add DIDs to the Outbound Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Although outbound trunks do not require DID mapping, the Yeastar interface still expects a DID entry for consistency.

    1. Open the **DIDs/DDIs** tab.
    2. Click **Add**.
    3. In the pop-up window:

       - **Create Method**: ``Single DID``
       - **DID/DDI**: Enter your outbound Caller ID (E.164 format, no ``+``).
       - **DID/DDI Name**: Enter a descriptive name (e.g., ``DIDWW Outbound Caller ID``).

    4. Click **Confirm**, then **Save**.

.. figure:: https://doc.didww.com/_images/yeastar_outbound5.png
   :figclass: align-center
   :alt: Yeastar Outbound SIP Trunk Add DID

   Fig. 26. Adding a DID to the Outbound SIP Trunk

Apply Outbound Trunk Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once you return to the **Trunk** menu, you will see your new outbound trunk in the list.
Click **Apply** to finalize the configuration.

.. figure:: https://doc.didww.com/_images/yeastar_outbound6.png
   :figclass: align-center
   :alt: Apply Outbound Trunk Changes

   Fig. 27. Applying Yeastar Outbound Trunk Configuration

The outbound trunk will show status **Registered** when authentication succeeds.

.. figure:: https://doc.didww.com/_images/yeastar_outbound7.png
   :figclass: align-center
   :alt: Apply Outbound Trunk Changes

   Fig. 28. DIDWW Outbound SIP Trunk successfully registered on Yeastar

.. _yeastar_configure_extensions:

Step 3: Add Extension
-------------------------

Before configuring Inbound or Outbound Routes, create at least one **Extension** that will receive and place calls through the DIDWW SIP trunks.

    1. In the Yeastar admin interface, go to **Extension & Trunk > Extension**.
    2. Click **Add > Add** to create a new extension.

    .. figure:: https://doc.didww.com/_images/yeastar_extensions1.png
       :figclass: align-center
       :alt: Add extensions button in Yeastar P-Series PBX

       Fig. 29. Add extensions button in Yeastar P-Series PBX

    3. Enter the **User information**:

       - **First Name** (e.g., ``Support Agent``).
       - **Email Address**
       - Update the placeholder **User Password**.

    .. note::
       The **Email Address** and **User Password** are used to sign in to the
       `Yeastar Linkus Desktop Client <https://www.yeastar.com/linkus-softphone/desktop/>`_
       for handling calls.

    .. figure:: https://doc.didww.com/_images/yeastar_extensions2.png
       :figclass: align-center
       :alt: Extensions User Information in Yeastar P-Series PBX

       Fig. 30. Extensions User Information in Yeastar P-Series PBX

    4. Configure Extension Information:

       - Select the **Extension Number** (e.g., 1000).
       - Set the **Caller ID** to match the extension number (e.g., ``1000``).

    5. Click **Save** to create the extension.

    .. note::
       A default **Extension Group** is automatically created and includes all extensions.
       To modify the default group or create a new one, refer to the
       `Yeastar Extension Group documentation <https://help.yeastar.com/en/p-series-appliance-edition/administrator-guide/extension-group-overview.html>`_.

    .. figure:: https://doc.didww.com/_images/yeastar_extensions3.png
       :figclass: align-center
       :alt: Extension Information in Yeastar P-Series PBX

       Fig. 31. Extension Information in Yeastar P-Series PBX

    6. Click **Apply** to finalize the configuration.

    .. figure:: https://doc.didww.com/_images/yeastar_extensions4.png
       :figclass: align-center
       :alt: Configured Extensions in Yeastar P-Series PBX

       Fig. 32. Configured Extensions in Yeastar P-Series PBX

.. _yeastar_configure_inbound_route:

Step 4: Configure an Inbound Route
-----------------------------------

Create an inbound route to deliver calls from your DIDWW DID to the correct destination inside your Yeastar P-Series PBX.

Add the Inbound Route
^^^^^^^^^^^^^^^^^^^^^^

    1. In the Yeastar admin interface, go to **Call Control > Inbound Route**.
    2. Click **Add** to create a new inbound route.

    .. figure:: https://doc.didww.com/_images/inbound_route1.png
       :figclass: align-center
       :alt: Add inbound route in Yeastar P-Series PBX

       Fig. 33. Add a new inbound route

Configure Inbound Route Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. In the **General** section, enter a **Name** for the route
       (e.g., ``DIDWW_Inbound_Route``).

    2. In the **Trunk** panel, select your **DIDWW Inbound Trunk** from the list and move it to the **Selected** column.

    .. figure:: https://doc.didww.com/_images/inbound_route2.png
       :figclass: align-center
       :alt: Select inbound trunk for Yeastar inbound route

       Fig. 34. General settings and Selecting the inbound trunk

    3. Scroll to **DID Pattern** and enter your DID number in **E.164 format without the +**
       (e.g., ``18489005419``).

    .. figure:: https://doc.didww.com/_images/inbound_route3.png
       :figclass: align-center
       :alt: DID Pattern configuration in Yeastar inbound route

       Fig. 35. Adding the DID pattern

    4. In **Default Destination**, choose where incoming calls should be routed
       (e.g., **IVR**, **Extension**, **Ring Group**, etc.).

    5. After completing the DID Pattern and Default Destination settings, click **Save** at the bottom of the form.

    .. figure:: https://doc.didww.com/_images/inbound_route4.png
       :figclass: align-center
       :alt: Selecting the default destination and saving the inbound route

       Fig. 36. Selecting the default destination and saving the inbound route

    6. When returned to the **Inbound Route** list, click **Apply** to activate the configuration.

    .. figure:: https://doc.didww.com/_images/inbound_route5.png
       :figclass: align-center
       :alt: Applying inbound route changes in Yeastar P-Series PBX

       Fig. 37. Applying the inbound route changes

.. _yeastar_configure_outbound_route:

Step 5: Configure an Outbound Route
-------------------------------------

Create an outbound route to allow Yeastar extensions to make external calls through your **DIDWW Outbound SIP Trunk**.

Add the Outbound Route
^^^^^^^^^^^^^^^^^^^^^^^^^

    1. In the Yeastar admin interface, go to **Call Control > Outbound Route**.
    2. Click **Add**.

    .. figure:: https://doc.didww.com/_images/outbound_route1.png
       :figclass: align-center
       :alt: Add outbound route in Yeastar P-Series PBX

       Fig. 38. Add outbound route in Yeastar P-Series PBX

Configure Outbound Route Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    1. Under **General**, enter a **Name** for the route
       (e.g., ``DIDWW_Outbound_Extension``).

    2. Under **Dial Pattern**, configure:

       - **Pattern**: ``X.``
         (allows dialing any external number)

    .. figure:: https://doc.didww.com/_images/outbound_route2.png
       :figclass: align-center
       :alt: Outbound route general settings and Dial Pattern configuration

       Fig. 39. Outbound route general settings and Dial Pattern configuration

    3. Under **Trunk**, select your **DIDWW Outbound Trunk** and move it to the **Selected** column.

    .. figure:: https://doc.didww.com/_images/outbound_route3.png
       :figclass: align-center
       :alt: Dial Pattern configuration for outbound route

       Fig. 40. Selecting the DIDWW Outbound Trunk

    4. Under **Extension / Extension Group**, select the extensions that should be allowed to make outbound calls
       (e.g., the default ``Extension Group``).

    5. Click **Save** to create the outbound route.

    .. figure:: https://doc.didww.com/_images/outbound_route4.png
       :figclass: align-center
       :alt: Assigning extensions to the outbound route and Saving outbound route

       Fig. 41. Assigning extensions to the outbound route and Saving outbound route

    6. When returned to the **Outbound Route** list, click **Apply** to activate the configuration.

    .. figure:: https://doc.didww.com/_images/outbound_route5.png
       :figclass: align-center
       :alt: Apply outbound route changes

       Fig. 42. Apply outbound route changes

.. _yeastar_activate_extension:

Step 6: Test Inbound and Outbound Calls
---------------------------------------

Before testing calls, ensure that at least one extension is **registered**.
You may use the **Yeastar Linkus Desktop or Mobile Client** to register an extension easily.

Register an Extension
^^^^^^^^^^^^^^^^^^^^^^^

    1. Download the `Linkus client <https://www.yeastar.com/linkus-softphone/download/>`_ for your operating system.
    2. Sign in using the **Email Address** and **User Password** configured for the extension.
    3. Once logged in, the extension status will change to **Registered** in the Yeastar PBX interface.

.. note::
   You may also register extensions using any SIP-compatible softphone or IP phone.
   For more details, refer to the official `Yeastar SIP Extension Settings documentation <https://www.yeastar.com/linkus-download/>`_.

Test Inbound Calls
^^^^^^^^^^^^^^^^^^

Verify that incoming calls from DIDWW numbers correctly reach your Yeastar PBX.

    - From an external phone, call your DIDWW number.
    - Confirm the call is delivered to Yeastar and routed according to your **Inbound Route** destination.
    - Answer the call and verify **two-way audio**.
    - If the call does not arrive, check the trunk status and DID Pattern configuration.

Test Outbound Calls
^^^^^^^^^^^^^^^^^^^

Verify that outbound calls from Yeastar extensions are sent through the DIDWW Outbound Trunk.

    - From the registered Yeastar extension, dial any external number that matches your **Dial Pattern**.
    - Confirm that the call is routed through your **DIDWW Outbound Trunk**.
    - Verify **two-way audio**.
    - If the call fails, review trunk registration status and outbound routing permissions.

.. note::
   - To troubleshoot, check the `DIDWW Inbound Call Logs <https://my.didww.com/#/call_logs>`_ and `Outbound Call Logs <https://my.didww.com/#/outbound_call_logs>`_ for response codes or call errors or contact our technical support team at support@didww.com.


Asterisk
========

Use `Asterisk <https://asterisk.org/>`_ with **DIDWW SIP Trunking** to build
a self-managed IP PBX that routes inbound and outbound calls through Asterisk.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Route incoming calls from DIDWW numbers to Asterisk.
      - Deliver calls to internal SIP endpoints through the Asterisk dialplan.
      - Use DIDWW numbers with Static Endpoint or Dynamic Registration trunks.

   .. grid-item::
      :class: left-align-block

      - Place outbound calls through DIDWW Outbound Trunks.
      - Configure SIP signaling and media with Asterisk PJSIP.
      - Use existing DIDWW phone numbers for inbound and outbound calling.

.. note::

    - Choose the guide that matches the SIP channel driver used by the Asterisk
      installation. Use **Asterisk PJSIP Configuration (v20–23)** for Asterisk 21 and later. For
      Asterisk 20, use the PJSIP configuration unless the installation is explicitly
      configured with ``chan_sip`` and ``sip.conf``.
    - Asterisk deprecated ``chan_sip`` in version 17, stopped including it in
      default builds in version 19, and removed it entirely in version 21.

.. raw:: html

   <br>

.. grid:: 1 1 2 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Asterisk PJSIP Configuration (v20–23)**
      :link: current-versions
      :link-type: doc
      :text-align: left

      Configure inbound and outbound calling for Asterisk v20-23 using ``chan_pjsip`` and ``pjsip.conf``.

   .. grid-item-card:: **Legacy Asterisk Configuration**
      :link: legacy-versions
      :link-type: doc
      :text-align: left

      Use the preserved configuration for Asterisk v20 or earlier only when
      the installation still uses ``chan_sip`` and ``sip.conf``.

.. toctree::
   :maxdepth: 1
   :hidden:

   PJSIP Configuration (v20–23) <current-versions.rst>
   Legacy Configuration <legacy-versions.rst>



=====================================
Asterisk PJSIP Configuration (v20–23)
=====================================

Connect a plain Asterisk installation to DIDWW by using ``chan_pjsip``. This
guide covers inbound calls through a Static Endpoint or Dynamic Registration
trunk and outbound calls through a DIDWW outbound trunk.

For general information about the channel driver and its configuration model,
see the official `Configuring res_pjsip
<https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/>`_
documentation.

This configuration applies to **Asterisk 20, 21, 22, and 23 versions** and uses the configuration schema included with stock Asterisk.
It does not require third-party patches.

.. note::

   For Asterisk installations managed through FreePBX, use the
   :doc:`../freepbx/index` guide. For an older installation that still has
   ``chan_sip`` installed, see the :doc:`legacy-versions` guide.

----

1. Configure inbound voice trunk
==================================

Configure an Inbound SIP Trunk in the DIDWW User Panel to send incoming calls
from your DIDWW numbers to Asterisk. Select the delivery method that matches
your Asterisk deployment.

Before you begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `create a DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- At least one active **DID number** with capacity to receive incoming calls is
  required. If you do not have one, see
  :doc:`../../phone-numbers/buy-numbers/how-to-buy`.

Step 1: Create New Inbound SIP trunk
------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to
   **Voice > Inbound Trunks**.
2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/create-inbound-sip-trunk.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Creating a new inbound SIP trunk.

Step 2: Configure general SIP trunk settings
---------------------------------------------

In the Create Inbound SIP Trunk form, enter the settings for the selected
trunk type.

.. tab-set::
   :sync-group: asterisk-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      1. Enter a descriptive **Name** for the trunk (e.g., ``Asterisk``).
      2. Select **Static Endpoint** as the trunk **Type**.
      3. In **Host**, enter the public IP address of the Asterisk server or a
         domain name that resolves to it.
      4. Select the signaling **Transport** and enter the corresponding
         **Port** used by Asterisk. The standard port is ``5060`` for UDP or
         TCP and ``5061`` for TLS. If Asterisk uses a custom listening port,
         enter that port instead.
      5. Set **User Part of R-URI** to ``{DID}``. This placeholder inserts the
         called DID in E.164 format into the user part of the Request-URI.

      .. figure:: https://doc.didww.com/_images/configure-static-endpoint.webp
         :figclass: align-center
         :alt: Configuring a Static Endpoint inbound SIP trunk in the DIDWW User Panel

         Static Endpoint trunk settings.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      1. Enter a descriptive **Name** for the trunk (e.g., ``Asterisk``).
      2. Select **Dynamic Registration** as the trunk **Type**.
      3. Enable **Use DID in R-URI** so the called DID replaces the registered
         contact user part in inbound requests.

      .. figure:: https://doc.didww.com/_images/configure-dynamic-registration.webp
         :figclass: align-center
         :alt: Selecting Dynamic Registration and Use DID in R-URI for an inbound SIP trunk

         Dynamic Registration trunk settings.

Step 3: Click Create and Save Inbound SIP Trunk Configuration
-------------------------------------------------------------

When all required fields in the Create Inbound SIP Trunk form are filled,
click **Create** to save the trunk.

.. note::

   For advanced SIP trunk configuration, see
   :ref:`Advanced Inbound SIP Trunk documentation
   <user_panel_sipin_trunk_advanced_configuration>`.

.. tab-set::
   :sync-group: asterisk-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      .. figure:: https://doc.didww.com/_images/save-static-inbound-trunk.webp
         :figclass: align-center
         :alt: Saving the Static Endpoint inbound SIP trunk

         Creating the Static Endpoint inbound SIP trunk.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      .. figure:: https://doc.didww.com/_images/save-dynamic-inbound-trunk.webp
         :figclass: align-center
         :alt: Saving the Dynamic Registration inbound SIP trunk

         Creating the Dynamic Registration inbound SIP trunk.

Step 4: Copy Inbound Trunk Credentials (Dynamic Registration Only)
------------------------------------------------------------------

For a Dynamic Registration trunk, open the created trunk and copy its
generated username, password, and registration endpoint. You will use these
values in ``pjsip.conf``. Static Endpoint trunks do not use registration
credentials.

.. figure:: https://doc.didww.com/_images/inbound-registration-credentials.webp
   :figclass: align-center
   :alt: Viewing generated Dynamic Registration credentials and endpoints

   Dynamic Registration credentials and endpoints.

Step 5: Assign inbound SIP trunk to your DID numbers
----------------------------------------------------

After creating the Inbound SIP Trunk for Asterisk, assign it to the DID
number(s) that will deliver incoming calls to Asterisk.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number(s) you want to assign to the inbound SIP trunk.
3. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/select-dids-update-trunks.webp
   :figclass: align-center
   :alt: Selecting DID numbers and Update Trunks from the Batch Actions menu

   Selecting **Update Trunks** from the Batch Actions menu.

4. From the dropdown menu, choose the **Asterisk SIP trunk** you created
   earlier.
5. Click **Confirm** to apply the changes.

.. figure:: https://doc.didww.com/_images/assign-inbound-trunk.webp
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Assigning the newly created SIP trunk to the selected DID(s).

----

2. Configure outbound voice trunk
===================================

Configure an Outbound SIP Trunk in the DIDWW User Panel to allow Asterisk to
place outbound calls through DIDWW. This trunk provides the SIP credentials
and routing settings required for outbound calls to external phone numbers.

Before you begin
----------------

Access to **DIDWW Outbound Trunks** is required for making outbound calls. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

Step 1: Create New Outbound SIP Trunk
---------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice >
   Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/create-outbound-sip-trunk.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Creating a new outbound SIP trunk.

Step 2: Configure Authentication
--------------------------------

1. Update the **Friendly Name** (e.g., ``Asterisk``).
2. Keep the default **Credentials & IP-based** authentication method selected.
   The SIP digest credentials (username and password) will be provided after
   the trunk is created.
3. In **Allowed SIP IP addresses**, enter the public IP address or subnet from
   which Asterisk will send outbound SIP traffic.
4. Configure **Allowed CLI(s)** and the other termination settings required by
   your deployment.

.. note::

   Make sure you add the correct public IP address or subnet so that outbound
   calls are accepted by DIDWW.

.. figure:: https://doc.didww.com/_images/configure-outbound-trunk.webp
   :figclass: align-center
   :alt: Configuring credentials and allowed SIP addresses for an outbound trunk

   Entering allowed SIP IP addresses for outbound authentication.

Step 3: Click Create and Save Outbound SIP Trunk Configuration
--------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk are filled, click
**Create** to save your outbound SIP trunk.

.. note::

   For advanced outbound SIP trunk configuration, see
   :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/save-outbound-trunk.webp
   :figclass: align-center
   :alt: Saving the outbound SIP trunk

   Outbound SIP trunk created and ready for use.

Step 4: View Outbound Trunk Credentials
---------------------------------------

After the outbound trunk is created, you can view its credentials by selecting
the key icon in the Credentials column on the Outbound Trunks page.

1. Go to **Voice > Outbound Trunks**.
2. Locate your outbound trunk and click the **key icon** in the **Credentials**
   column.

.. figure:: https://doc.didww.com/_images/open-outbound-trunk-credentials.webp
   :figclass: align-center
   :alt: Selecting the credentials icon for the Asterisk outbound trunk

   Opening the Asterisk outbound trunk credentials.

3. The trunk credentials will appear, showing the **Username** and **Password**
   (click the **eye icon** to reveal the password).
4. Copy and securely store these credentials. You will need them when
   configuring outbound calling in Asterisk.

.. figure:: https://doc.didww.com/_images/outbound-trunk-credentials.webp
   :figclass: align-center
   :alt: Viewing the Asterisk outbound trunk username, password, and hostnames

   Asterisk outbound trunk credentials and hostnames.

----

3. Configure Asterisk
=====================

Configure Asterisk to use the DIDWW inbound and outbound trunks created in the
previous sections. Add the required PJSIP transport, trunk, and dialplan
settings for your deployment.

Before you begin
----------------

Asterisk 20 or later is required with ``chan_pjsip`` and ``res_pjsip`` loaded. See the official `Configuring res_pjsip <https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/>`_ documentation.

.. note::

   The examples use ``/etc/asterisk/pjsip.conf`` and
   ``/etc/asterisk/extensions.conf``. Replace all uppercase placeholder values
   before applying the configuration.

   For an explanation of the transport,
   endpoint, authentication, AoR, registration, and identify objects, see the
   official `PJSIP Configuration Sections and Relationships
   <https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/PJSIP-Configuration-Sections-and-Relationships/>`_
   documentation.

Step 1: Configure SIP trunks (pjsip.conf)
-----------------------------------------

Complete the core trunk configuration first. Then add only the optional
settings required by the Asterisk deployment.

Core trunk configuration
^^^^^^^^^^^^^^^^^^^^^^^^

In ``/etc/asterisk/pjsip.conf``, configure the SIP transport and the inbound
and outbound DIDWW trunks. These settings establish the core SIP signaling
and media configuration required for calling through DIDWW.

Configure SIP transport
~~~~~~~~~~~~~~~~~~~~~~~

Define the signaling transport in ``pjsip.conf``. For inbound calling, the
transport and port must match the DIDWW inbound trunk settings. Skip this step
if ``pjsip.conf`` already contains the required transport.

.. tab-set::

   .. tab-item:: UDP

      Add the UDP transport:

      .. code-block:: ini

         [transport-udp]
         type = transport
         protocol = udp
         bind = 0.0.0.0:5060

   .. tab-item:: TCP

      Add the TCP transport:

      .. code-block:: ini

         [transport-tcp]
         type = transport
         protocol = tcp
         bind = 0.0.0.0:5060

   .. tab-item:: TLS

      Add the TLS transport:

      .. code-block:: ini

         [transport-tls]
         type = transport
         protocol = tls
         bind = 0.0.0.0:5061
         method = tlsv1_2
         cert_file = /etc/asterisk/keys/asterisk.crt
         priv_key_file = /etc/asterisk/keys/asterisk.key
         verify_server = yes
         ca_list_file = /etc/ssl/certs/ca-certificates.crt

      Replace ``cert_file`` and ``priv_key_file`` with the paths to the
      Asterisk TLS certificate and private key. Update ``ca_list_file`` if the
      system CA bundle uses a different path.

.. note::

    The remaining examples use UDP. If Asterisk is behind NAT, complete :ref:`asterisk-nat`.

For Asterisk transport selection rules and additional examples, see the
official `PJSIP Transport Selection
<https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/PJSIP-Transport-Selection/>`_
documentation.

Configure inbound trunk
~~~~~~~~~~~~~~~~~~~~~~~

Add the configuration that matches the inbound trunk type selected in the
DIDWW User Panel to ``pjsip.conf``.

.. tab-set::
   :sync-group: asterisk-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      Add the inbound endpoint and ``identify`` object:

      .. code-block:: ini

         [didww-in]
         type = endpoint
         transport = transport-udp
         context = from-didww
         disallow = all
         allow = alaw,ulaw
         dtmf_mode = rfc4733
         direct_media = no

         [didww-in-identify]
         type = identify
         endpoint = didww-in
         match = 46.19.209.14
         match = 46.19.210.14
         match = 46.19.212.14
         match = 46.19.213.14
         match = 46.19.214.14
         match = 46.19.215.14
         match = 185.238.173.14

      Replace ``transport-udp`` with ``transport-tcp`` or ``transport-tls``
      when using TCP or TLS. **Preferred Server** is set to **Auto** by
      default, so add all addresses listed under :ref:`SIP Signaling Addresses
      <service_did_sip>`.

      .. note::

         - The ``identify`` object maps incoming DIDWW traffic to the
           ``didww-in`` endpoint. No ``aor`` or ``registration`` object is
           required.
         - This guide uses IPv4. For IPv6, use the DIDWW addresses under
           :ref:`SIP Signaling Addresses <service_did_sip>` and configure an
           IPv6 `PJSIP transport
           <https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/PJSIP-Transport-Selection/>`_.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      Add the inbound endpoint and registration using the credentials provided
      by DIDWW:

      .. code-block:: ini

         [didww-reg-auth]
         type = auth
         auth_type = userpass
         username = INBOUND_TRUNK_USERNAME
         password = INBOUND_TRUNK_PASSWORD

         [didww-reg]
         type = registration
         transport = transport-udp
         outbound_auth = didww-reg-auth
         server_uri = sip:sip.didww.com
         client_uri = sip:INBOUND_TRUNK_USERNAME@sip.didww.com
         retry_interval = 60
         expiration = 3600
         line = yes
         endpoint = didww-in

         [didww-in]
         type = endpoint
         transport = transport-udp
         context = from-didww
         disallow = all
         allow = alaw,ulaw
         dtmf_mode = rfc4733
         direct_media = no

      Replace ``transport-udp`` with ``transport-tcp`` when using TCP. When
      using TLS, set ``transport = transport-tls`` and include port ``5061``
      in both registration URIs:

      .. code-block:: ini

         server_uri = sip:sip.didww.com:5061\;transport=tls
         client_uri = sip:INBOUND_TRUNK_USERNAME@sip.didww.com:5061\;transport=tls

      ``sip.didww.com`` selects the registration location automatically. See
      :ref:`SIP Registrars <service_did_sip>` to use a regional hostname.

      .. note::

         - Replace ``INBOUND_TRUNK_USERNAME`` and
           ``INBOUND_TRUNK_PASSWORD`` with the credentials copied from the
           DIDWW User Panel.
         - ``line = yes`` and ``endpoint = didww-in`` associate incoming calls
           with the ``didww-in`` endpoint. No ``identify`` object or signaling
           IP address list is required.

For both trunk types, the called DID is sent to the ``from-didww`` dialplan
context in E.164 format.

The inbound examples use G.711 A-law and G.711 µ-law. See
:ref:`Supported codecs <service_did_sip_codecs>` to use other inbound codecs.

Configure outbound trunk
~~~~~~~~~~~~~~~~~~~~~~~~

Add the outbound trunk to ``pjsip.conf``:

.. code-block:: ini

   [didww-out-auth]
   type = auth
   auth_type = userpass
   username = OUTBOUND_TRUNK_USERNAME
   password = OUTBOUND_TRUNK_PASSWORD

   [didww-out]
   type = aor
   contact = sip:any.out.didww.com
   qualify_frequency = 60

   [didww-out]
   type = endpoint
   transport = transport-udp
   disallow = all
   allow = alaw,ulaw,g729
   dtmf_mode = rfc4733
   direct_media = no
   outbound_auth = didww-out-auth
   aors = didww-out
   from_user = AUTHORIZED_CALLER_ID

.. note::

   - Replace ``OUTBOUND_TRUNK_USERNAME`` and ``OUTBOUND_TRUNK_PASSWORD`` with
     the credentials copied from the DIDWW User Panel.
   - Replace ``AUTHORIZED_CALLER_ID`` with a caller ID allowed by the outbound
     trunk's CLI settings, for example, ``12025550123``.
   - Send destination and caller ID numbers in E.164 format. See
     :doc:`../../voice/outbound-trunks/routing-dialing/outbound-dialing`.

In ``/etc/asterisk/pjsip.conf``, add the following setting to the existing
``type = endpoint`` object for each internal PJSIP endpoint that is allowed to
make outbound calls. The ``outbound`` dialplan context is configured in
:ref:`Step 2 <asterisk-configure-dialplan>`.

.. code-block:: ini

   context = outbound

The example uses UDP and the DIDWW anycast endpoint
``any.out.didww.com``. Anycast uses network routing to select a DIDWW point of
presence. See :ref:`SIP Protocol Details <services_voice_out>` to use a
regional endpoint instead.

For TCP, replace
``transport-udp`` with ``transport-tcp``. For TLS, use ``transport-tls`` and a
regional endpoint on port ``5061``. Replace the ``contact`` and ``transport``
values with, for example:

.. code-block:: ini

   ; In the didww-out aor object
   contact = sip:nyc.us.out.didww.com:5061\;transport=tls

   ; In the didww-out endpoint object
   transport = transport-tls

The outbound example uses G.711 A-law, G.711 µ-law, and G.729. See
:ref:`SIP Protocol Details <services_voice_out>` to use other outbound codecs.

.. note::

   In Asterisk PJSIP, ``dtmf_mode = rfc4733`` configures the RTP
   telephone-event method commonly referred to as RFC 2833. See
   :ref:`DTMF transport methods <service_did_sip_dtmf>`.

Optional trunk configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use only the sections required by your deployment. Configure NAT when Asterisk
is behind NAT. Media encryption and T.38 fax are optional.

.. _asterisk-nat:

Configure NAT and firewall rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When Asterisk is behind NAT, add the following settings to each transport
object used with DIDWW:

.. code-block:: ini

   external_media_address = PUBLIC_IP_ADDRESS
   external_signaling_address = PUBLIC_IP_ADDRESS
   local_net = 192.168.0.0/16

Replace ``PUBLIC_IP_ADDRESS`` with the public IP address of the Asterisk server
and adjust ``local_net`` to the local network in CIDR format.

Allow DIDWW signaling and media traffic through the firewall using the
addresses and ports listed in :ref:`General SIP Information
<service_did_sip>` and :ref:`SIP Protocol Details <services_voice_out>`.
Allow the configured Asterisk SIP port and the RTP range defined in
``rtp.conf`` through the firewall. If the Asterisk server is behind port-based
NAT, forward these ports to the server.

For details about the Asterisk NAT settings, see `Configuring res_pjsip to work through NAT
<https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/Configuring-res_pjsip-to-work-through-NAT/>`_.

Configure media encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~

The Asterisk media-encryption method must match the **SRTP Mode** of the
:ref:`inbound trunk <user_panel_sipin_trunk_media_dtmf>` and the **Media
Encryption** setting of the :ref:`outbound trunk
<outbound_trunk_create_media>`.

Add one of the following configurations to each DIDWW-facing endpoint.

.. tab-set::

   .. tab-item:: SRTP SDES

      Use TLS signaling to protect the SRTP keys included in the SDP.

      .. code-block:: ini

         media_encryption = sdes

   .. tab-item:: SRTP DTLS

      .. code-block:: ini

         media_encryption = dtls
         dtls_auto_generate_cert = yes
         dtls_verify = fingerprint
         dtls_setup = actpass

DIDWW also supports ZRTP key negotiation, but stock Asterisk PJSIP does not.
SRTP requires the ``res_srtp`` module. See the `Asterisk PJSIP endpoint
options <https://docs.asterisk.org/Asterisk_21_Documentation/API_Documentation/Module_Configuration/res_pjsip/>`_
and the DIDWW encryption details for :ref:`inbound calling
<service_did_sip>` and :ref:`outbound calling <services_voice_out>`.

.. note::

   Encryption applies only to the call leg between DIDWW and Asterisk. It is
   not end-to-end encryption.

Configure T.38 fax
~~~~~~~~~~~~~~~~~~

For an inbound DID that supports T.38, add the following setting to the
``didww-in`` endpoint:

.. code-block:: ini

   t38_udptl = yes

This setting enables T.38 negotiation and does not affect normal voice calls.
The dialplan must route fax calls to a T.38-capable application or endpoint.
If Asterisk relays T.38 to another PJSIP endpoint, enable ``t38_udptl`` on that
endpoint as well.

When Asterisk is behind NAT, also add ``t38_udptl_nat = yes`` and allow the
UDPTL port range configured in ``udptl.conf``. For T.38 availability and G.711
fax alternatives, see :doc:`../../voice/inbound-trunks/technical-data/fax-services`.

.. important::

   Run ``pjsip reload`` from the `Asterisk CLI
   <https://docs.asterisk.org/Operation/Asterisk-Command-Line-Interface/CLI-Syntax-and-Help-Commands/>`_
   after changing PJSIP endpoints, authentication objects, or registrations.
   Transport changes require a complete Asterisk restart.

.. _asterisk-configure-dialplan:

Step 2: Configure the dialplan (extensions.conf)
------------------------------------------------

Add the inbound and outbound routing contexts to ``extensions.conf``.

.. code-block:: ini

   [from-didww]
   exten => INBOUND_DID,1,NoOp(DIDWW inbound call to ${EXTEN})
    same => n,Dial(PJSIP/INTERNAL_ENDPOINT,30)
    same => n,Hangup()

   [outbound]
   ; Send an E.164 destination through the DIDWW outbound trunk.
   exten => _X.,1,Set(CALLERID(num)=AUTHORIZED_CALLER_ID)
    same => n,Dial(PJSIP/${EXTEN}@didww-out)
    same => n,Hangup()

Replace ``INBOUND_DID`` with the DID in E.164 format, for example,
``12025550123``; ``INTERNAL_ENDPOINT`` with the destination PJSIP endpoint,
for example, ``1001``; and ``AUTHORIZED_CALLER_ID`` with a caller ID allowed
by the outbound trunk, for example, ``12025550123``.

.. warning::

   Keep the ``from-didww`` and ``outbound`` contexts separate. Do not allow
   inbound calls to access the ``didww-out`` endpoint.

For dialplan concepts and ``extensions.conf`` syntax, see the official
`Asterisk dialplan <https://docs.asterisk.org/Configuration/Dialplan/>`_
documentation.

.. note::

   Run ``dialplan reload`` from the `Asterisk CLI
   <https://docs.asterisk.org/Operation/Asterisk-Command-Line-Interface/CLI-Syntax-and-Help-Commands/>`_
   after changing ``extensions.conf``.

Step 3: Verify and troubleshoot the configuration
-------------------------------------------------

Use the following `Asterisk CLI
<https://docs.asterisk.org/Operation/Asterisk-Command-Line-Interface/CLI-Syntax-and-Help-Commands/>`_
commands to confirm that Asterisk loaded the configuration and can communicate
with DIDWW:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Check
     - Command
   * - Loaded endpoints
     - ``pjsip show endpoints``
   * - Configured transports
     - ``pjsip show transports``
   * - IP-based endpoint matches
     - ``pjsip show identifies``
   * - Registration state
     - ``pjsip show registrations``
   * - Gateway reachability
     - ``pjsip show aors`` and ``pjsip show contacts``
   * - Loaded dialplan contexts
     - ``dialplan show from-didww`` and ``dialplan show outbound``
   * - Live SIP trace
     - ``pjsip set logger on``
   * - Force an inbound registration attempt
     - ``pjsip send register didww-reg``

Common issues
^^^^^^^^^^^^^

.. dropdown:: Inbound calls return ``401`` or ``404``, or Asterisk reports ``No matching endpoint``.

   For a Static Endpoint trunk, confirm that the request source is present
   in the ``identify`` object.

   For a Dynamic Registration trunk, confirm that ``line = yes`` and
   ``endpoint = didww-in`` are set on the registration.

.. dropdown:: An inbound call reaches Asterisk but does not reach the internal endpoint.

   Run ``dialplan show from-didww`` and confirm that the DID received in
   the Request-URI matches ``INBOUND_DID`` in ``extensions.conf``.

   Confirm that ``INTERNAL_ENDPOINT`` identifies an available PJSIP endpoint.

.. dropdown:: A call has one-way audio.

   Check ``external_media_address``, ``local_net``, and the firewall rules.

   Confirm that the applicable DIDWW RTP ranges and the Asterisk RTP port
   range are allowed.

.. dropdown:: A call fails with ``488`` Not Acceptable Here.

   Confirm that Asterisk and the corresponding DIDWW trunk have a common
   codec.

   If media encryption is enabled, confirm that the configured SRTP method
   matches the trunk settings.

.. dropdown:: DTMF input is not recognized.

   Confirm that the endpoint uses ``dtmf_mode = rfc4733``.

   This is the Asterisk PJSIP setting for the RTP telephone-event method
   commonly referred to as RFC 2833.

.. dropdown:: Outbound calls return ``403`` or repeat ``407`` challenges.

   Confirm the outbound trunk credentials, the public Asterisk address in
   Allowed SIP IP addresses, and the caller ID in the trunk's CLI settings.

.. dropdown:: Asterisk cannot establish a TLS connection.

   Confirm that the TLS transport is loaded, the certificate and CA bundle
   paths are correct, and the configured DIDWW hostname uses port ``5061``.

   For outbound TLS, use a regional DIDWW endpoint.

   Run ``pjsip set logger on`` to inspect the failure.

.. dropdown:: A Dynamic Registration trunk remains ``Rejected``.

   Confirm that the username in ``client_uri`` matches the generated trunk
   username.

   Run ``pjsip set logger on`` to inspect the authentication challenge and
   response.

.. dropdown:: A Dynamic Registration trunk remains ``Unregistered`` or cannot reach the registrar.

   Confirm that the selected transport is loaded and that the firewall
   permits signaling to the configured DIDWW registrar and port.

   Confirm that ``server_uri`` uses the same transport and port.

For additional diagnostic procedures, see the official `Asterisk PJSIP
Troubleshooting Guide
<https://docs.asterisk.org/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/Asterisk-PJSIP-Troubleshooting-Guide/>`_.


=============================
Legacy Asterisk Configuration
=============================

This page preserves the legacy DIDWW configuration for Asterisk installations
that still use ``chan_sip`` and ``sip.conf``. ``chan_sip`` was deprecated in
Asterisk 17, was no longer built by default beginning with Asterisk 19, and was
removed in Asterisk 21.

.. warning::

   Do not use this configuration for new installations. For current Asterisk
   releases, see :doc:`current-versions`.

DIDWW SIP trunks can be used with Asterisk for inbound and outbound calls.

Dialplan example
================

Add the inbound context to ``extensions.conf``:

.. code-block:: ini

   [from-didww]
   exten => _X.,1,Ringing
   exten => _X.,n,Answer
   exten => _X.,n,Echo
   exten => _X.,n,Wait(600)
   exten => _X.,n,Hangup

Inbound trunk example
=====================

Add the following peers to ``sip.conf``:

.. code-block:: ini

   [didww-ny]
   host=46.19.209.14
   dtmfmode=rfc2833
   dtmf=rfc2833
   type=peer
   context=from-didww
   insecure=invite,port
   nat=never
   allow=all

   [didww-fra]
   host=46.19.210.14
   dtmfmode=rfc2833
   dtmf=rfc2833
   type=peer
   context=from-didww
   insecure=invite,port
   nat=never
   allow=all

   [didww-la]
   host=46.19.212.14
   dtmfmode=rfc2833
   dtmf=rfc2833
   type=peer
   context=from-didww
   insecure=invite,port
   nat=never
   allow=all

   [didww-mia]
   host=46.19.213.14
   dtmfmode=rfc2833
   dtmf=rfc2833
   type=peer
   context=from-didww
   insecure=invite,port
   nat=never
   allow=all

   [didww-sg]
   host=46.19.214.14
   dtmfmode=rfc2833
   dtmf=rfc2833
   type=peer
   context=from-didww
   insecure=invite,port
   nat=never
   allow=all

   [didww-hk]
   host=46.19.215.14
   dtmfmode=rfc2833
   dtmf=rfc2833
   type=peer
   context=from-didww
   insecure=invite,port
   nat=never
   allow=all

For the current signaling address list, including Amsterdam and IPv6
addresses, see :ref:`SIP Signaling Addresses <service_did_sip>`.

Outbound trunk example
======================

Add the outbound peer to ``sip.conf``:

.. code-block:: ini

   [didww-outbound]
   type=peer
   dtmfmode=rfc2833
   dtmf=rfc2833
   fromuser=DID_NUMBER
   auth=USERNAME:PASSWORD@out.didww.com
   secret=PASSWORD
   host=any.out.didww.com
   fromdomain=ASTERISK_IP_ADDRESS

Replace the placeholder values with your DIDWW outbound trunk details. For the
current gateway list and authentication realm, see
:ref:`SIP Protocol Details <services_voice_out>`.

.. note::

   If Asterisk cannot find an extension within the given context, it returns an
   unhelpful *No such context/extension* error. Use the catch-all ``_X.``
   pattern while troubleshooting, then replace it with the routing rules
   required by your deployment.


==========
FreeSWITCH
==========

`FreeSWITCH <https://freeswitch.org/>`_ is an open-source telecommunications
platform for building IP PBXs, voice applications, gateways, and other
real-time communication systems. It uses SIP profiles, gateways, and dialplans
to control call signaling, media, and routing.

Use FreeSWITCH with **DIDWW SIP Trunking** to receive calls through a Static
Endpoint or Dynamic Registration trunk and place outbound calls through a
DIDWW outbound trunk. This guide configures DIDWW connectivity through the
external Sofia SIP profile.

This configuration applies to **FreeSWITCH 1.10 and 1.11** with the default
configuration and ``mod_sofia``. It does not require third-party modules.

.. note::

   FreeSWITCH configuration paths depend on the installation method. Package
   installations commonly use ``/etc/freeswitch``. Source installations
   commonly use ``/usr/local/freeswitch/conf``. The examples in this guide use
   ``/etc/freeswitch``.

----

1. Configure inbound voice trunk
==================================

Configure an Inbound SIP Trunk in the DIDWW User Panel to send incoming calls
from your DIDWW numbers to FreeSWITCH. Select the delivery method that matches
your FreeSWITCH deployment.

Before you begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `create a DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- At least one active **DID number** with capacity to receive incoming calls is
  required. If you do not have one, see
  :doc:`../../phone-numbers/buy-numbers/how-to-buy`.

.. _freeswitch-create-inbound-trunk:

Step 1: Create New Inbound SIP trunk
------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to
   **Voice > Inbound Trunks**.
2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/create-inbound-sip-trunk.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Creating a new inbound SIP trunk.

.. _freeswitch-configure-inbound-trunk-settings:

Step 2: Configure general SIP trunk settings
---------------------------------------------

In the Create Inbound SIP Trunk form, enter the settings for the selected
trunk type.

.. tab-set::
   :sync-group: freeswitch-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      1. Enter a descriptive **Name** for the trunk (e.g., ``FreeSWITCH``).
      2. Select **Static Endpoint** as the trunk **Type**.
      3. In **Host**, enter the public IP address of the FreeSWITCH server or a
         domain name that resolves to it.
      4. Select the signaling **Transport** and enter the corresponding
         **Port** used by the external Sofia profile. The default profile uses
         port ``5080`` for UDP or TCP and ``5081`` for TLS. If FreeSWITCH uses
         a custom listening port, enter that port instead.
      5. Set **User Part of R-URI** to ``{DID}``. This placeholder inserts the
         called DID in E.164 format into the user part of the Request-URI.

      .. figure:: https://doc.didww.com/_images/configure-static-endpoint.webp
         :figclass: align-center
         :alt: Configuring a Static Endpoint inbound SIP trunk in the DIDWW User Panel

         Static Endpoint trunk settings.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      1. Enter a descriptive **Name** for the trunk (e.g., ``FreeSWITCH``).
      2. Select **Dynamic Registration** as the trunk **Type**.
      3. Configure the remaining media and signaling settings required by your
         deployment.

      .. important::

         The Dynamic Registration setup in this guide sends all incoming calls
         to one FreeSWITCH destination. It does not configure DID-based routing
         for Dynamic Registration. The Static Endpoint example in this guide
         routes calls by DID.

      .. figure:: https://doc.didww.com/_images/configure-dynamic-registration.webp
         :figclass: align-center
         :alt: Configuring a Dynamic Registration inbound SIP trunk in the DIDWW User Panel

         Dynamic Registration trunk settings.

.. _freeswitch-save-inbound-trunk:

Step 3: Click Create and Save Inbound SIP Trunk Configuration
-------------------------------------------------------------

When all required fields in the Create Inbound SIP Trunk form are filled,
click **Create** to save the trunk.

.. note::

   For advanced SIP trunk configuration, see
   :ref:`Advanced Inbound SIP Trunk documentation
   <user_panel_sipin_trunk_advanced_configuration>`.

.. tab-set::
   :sync-group: freeswitch-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      .. figure:: https://doc.didww.com/_images/save-static-inbound-trunk.webp
         :figclass: align-center
         :alt: Saving the Static Endpoint inbound SIP trunk

         Creating the Static Endpoint inbound SIP trunk.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      .. figure:: https://doc.didww.com/_images/save-dynamic-inbound-trunk.webp
         :figclass: align-center
         :alt: Saving the Dynamic Registration inbound SIP trunk

         Creating the Dynamic Registration inbound SIP trunk.

.. _freeswitch-copy-inbound-trunk-credentials:

Step 4: Copy Inbound Trunk Credentials (Dynamic Registration Only)
------------------------------------------------------------------

For a Dynamic Registration trunk, open the created trunk and copy its
generated username, password, and registration endpoint. You will use these
values when you :ref:`configure the FreeSWITCH inbound gateway
<freeswitch-configure-inbound-gateway>`. Static Endpoint trunks do not use
registration credentials.

.. figure:: https://doc.didww.com/_images/inbound-registration-credentials.webp
   :figclass: align-center
   :alt: Viewing generated Dynamic Registration credentials and endpoints

   Dynamic Registration credentials and endpoints.

.. _freeswitch-assign-inbound-trunk:

Step 5: Assign inbound SIP trunk to your DID numbers
----------------------------------------------------

After creating the Inbound SIP Trunk for FreeSWITCH, assign it to the DID
number(s) that will deliver incoming calls to FreeSWITCH.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number(s) you want to assign to the inbound SIP trunk.
3. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/select-dids-update-trunks.webp
   :figclass: align-center
   :alt: Selecting DID numbers and Update Trunks from the Batch Actions menu

   Selecting **Update Trunks** from the Batch Actions menu.

4. From the dropdown menu, choose the **FreeSWITCH SIP trunk** created in
   :ref:`Step 3 <freeswitch-save-inbound-trunk>`.
5. Click **Confirm** to apply the changes.

.. figure:: https://doc.didww.com/_images/assign-inbound-trunk.webp
   :figclass: align-center
   :alt: Assigning a SIP trunk to DID numbers

   Assigning the newly created SIP trunk to the selected DID(s).

----

2. Configure outbound voice trunk
===================================

Configure an Outbound SIP Trunk in the DIDWW User Panel to allow FreeSWITCH to
place outbound calls through DIDWW. This trunk provides the SIP credentials
and routing settings required for outbound calls to external phone numbers.

Before you begin
----------------

Access to **DIDWW Outbound Trunks** is required for making outbound calls. See
:ref:`Get access to outbound trunks
<user_panel_voice_out_get_access>`.

.. _freeswitch-create-outbound-trunk:

Step 1: Create New Outbound SIP Trunk
-------------------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to
   **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/create-outbound-sip-trunk.png
   :figclass: align-center
   :alt: Creating a new outbound SIP trunk

   Creating a new outbound SIP trunk.

.. _freeswitch-configure-outbound-authentication:

Step 2: Configure Authentication
--------------------------------

1. Update the **Friendly Name** (e.g., ``FreeSWITCH``).
2. Keep the default **Credentials & IP-Based** authentication method selected.
   The SIP digest credentials (username and password) will be provided after
   the trunk is created.
3. In **Allowed SIP IP addresses**, enter the public IP address or subnet from
   which FreeSWITCH will send outbound SIP traffic.
4. Configure **Allowed CLI(s)** and the other termination settings required by
   your deployment.

.. note::

   Make sure you add the correct public IP address or subnet so that outbound
   calls are accepted by DIDWW.

.. figure:: https://doc.didww.com/_images/configure-outbound-trunk.webp
   :figclass: align-center
   :alt: Configuring credentials and allowed SIP addresses for an outbound trunk

   Entering allowed SIP IP addresses for outbound authentication.

.. _freeswitch-save-outbound-trunk:

Step 3: Click Create and Save Outbound SIP Trunk Configuration
--------------------------------------------------------------

When all required fields in the Create Outbound SIP Trunk are filled, click
**Create** to save your outbound SIP trunk.

.. note::

   For advanced outbound SIP trunk configuration, see
   :ref:`Outbound SIP Trunk Guide <outbound_trunk_create>`.

.. figure:: https://doc.didww.com/_images/save-outbound-trunk.webp
   :figclass: align-center
   :alt: Saving the outbound SIP trunk

   Outbound SIP trunk created and ready for use.

.. _freeswitch-view-outbound-trunk-credentials:

Step 4: View Outbound Trunk Credentials
---------------------------------------

After the outbound trunk is created, you can view its credentials by selecting
the key icon in the Credentials column on the Outbound Trunks page.

1. Go to **Voice > Outbound Trunks**.
2. Locate your outbound trunk and click the **key icon** in the **Credentials**
   column.

.. figure:: https://doc.didww.com/_images/open-outbound-trunk-credentials.webp
   :figclass: align-center
   :alt: Selecting the credentials icon for the FreeSWITCH outbound trunk

   Opening the FreeSWITCH outbound trunk credentials.

3. The trunk credentials will appear, showing the **Username** and **Password**
   (click the **eye icon** to reveal the password).
4. Copy and securely store these credentials. You will need them when you
   :ref:`configure the FreeSWITCH outbound gateway
   <freeswitch-configure-outbound-gateway>`.

.. figure:: https://doc.didww.com/_images/outbound-trunk-credentials.webp
   :figclass: align-center
   :alt: Viewing the FreeSWITCH outbound trunk username, password, and hostnames

   FreeSWITCH outbound trunk credentials and hostnames.

----

3. Configure FreeSWITCH
=======================

Configure the external Sofia profile, DIDWW gateways, and XML dialplan. The
examples keep internet-facing trunk traffic separate from authenticated
internal users.

Before you begin
----------------

FreeSWITCH **1.10** or **1.11** is required with ``mod_sofia`` loaded and the external
Sofia profile running.

.. note::

   The examples use ``/etc/freeswitch`` as the configuration directory. Adjust
   the paths if FreeSWITCH uses a different configuration directory. Back up
   the current configuration before making changes.

.. _freeswitch-configure-sofia-profile-and-gateways:

Step 1: Configure the Sofia profile and gateways
------------------------------------------------

Complete the core SIP configuration first. Then add only the optional
settings required by your deployment.

1. Core SIP configuration
^^^^^^^^^^^^^^^^^^^^^^^^^

Configure the external Sofia profile, DIDWW ACL, and inbound and outbound
gateways required for calling through DIDWW.

1.1 Configure the external Sofia profile and transport
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default external profile loads gateway files from
``sip_profiles/external``. In
``/etc/freeswitch/sip_profiles/external.xml``, confirm or add the following
settings inside the profile's ``settings`` element:

.. code-block:: xml

   <param name="sip-port" value="$${external_sip_port}"/>
   <param name="inbound-codec-prefs" value="PCMA,PCMU"/>
   <param name="outbound-codec-prefs" value="PCMA,PCMU"/>
   <param name="dtmf-type" value="rfc2833"/>
   <param name="auth-calls" value="false"/>
   <param name="apply-inbound-acl" value="didww:from-didww"/>

The extended ACL value accepts traffic from the ``didww`` list and sends it
to the ``from-didww`` dialplan context. Requests that fail the ACL are
rejected.

The examples use G.711 A-law and G.711 µ-law. See the DIDWW codec details for
:ref:`inbound calling <service_did_sip_codecs>` and :ref:`outbound calling
<services_voice_out>` before enabling other codecs.

Select the signaling transport used by the corresponding DIDWW trunks. Skip
settings that are already present in the external profile.

.. tab-set::

   .. tab-item:: UDP

      Use port ``5080``. UDP is enabled on the default external profile, so no
      additional transport settings are required.

   .. tab-item:: TCP

      Use port ``5080``. TCP is enabled on the default external profile, so no
      additional transport settings are required.

   .. tab-item:: TLS

      Use port ``5081``. In ``/etc/freeswitch/vars.xml``, enable TLS and
      confirm the external TLS port:

      .. code-block:: xml

         <X-PRE-PROCESS cmd="set" data="external_ssl_enable=true"/>
         <X-PRE-PROCESS cmd="set" data="external_tls_port=5081"/>

      In the external profile, confirm or add the TLS settings:

      .. code-block:: xml

         <param name="tls" value="$${external_ssl_enable}"/>
         <param name="tls-bind-params" value="transport=tls"/>
         <param name="tls-sip-port" value="$${external_tls_port}"/>
         <param name="tls-cert-dir" value="/etc/freeswitch/tls"/>

      Replace ``/etc/freeswitch/tls`` if the SIP TLS certificate and trust
      chain are stored elsewhere. The directory must contain the certificate
      files required by the external Sofia profile.

For additional Sofia profile settings, see the official FreeSWITCH `SIP
profiles
<https://developer.signalwire.com/freeswitch/users-and-endpoints/sip-profiles/>`_
documentation.

1.2 Configure the DIDWW ACL
~~~~~~~~~~~~~~~~~~~~~~~~~~~

In ``/etc/freeswitch/autoload_configs/acl.conf.xml``, add the following list
inside ``network-lists``:

.. code-block:: xml

   <list name="didww" default="deny">
     <node type="allow" cidr="46.19.208.0/21"/>
     <node type="allow" cidr="185.238.172.0/22"/>
   </list>

The list deliberately uses the published DIDWW IPv4 network blocks because
``apply-inbound-acl`` applies to the complete external profile. This permits
inbound calls and in-dialog SIP requests associated with outbound calls. The
ACL controls SIP access only; configure media access separately in the
firewall.

Before applying the ACL, verify the current addresses in :ref:`General SIP
Information <service_did_sip>` and :ref:`SIP Protocol Details
<services_voice_out>`. This guide uses IPv4. Add the published IPv6 ranges if
your deployment uses IPv6. If the external profile also serves other
carriers, include their trusted SIP sources without removing an existing
security policy.

.. _freeswitch-configure-inbound-gateway:

1.3 Configure the inbound trunk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. tab-set::
   :sync-group: freeswitch-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      No gateway file is required. DIDWW sends calls directly to the external
      Sofia profile.

      The ACL identifies trusted DIDWW traffic and routes it to the
      ``from-didww`` context. The dialplan configured in :ref:`Step 2
      <freeswitch-configure-xml-dialplan>` matches the called DID from the
      Request-URI.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      Create
      ``/etc/freeswitch/sip_profiles/external/didww-in.xml``:

      .. code-block:: xml

         <include>
           <gateway name="didww-in">
             <param name="proxy" value="nyc.sip.didww.com"/>
             <param name="realm" value="sip.didww.com"/>
             <param name="username" value="INBOUND_TRUNK_USERNAME"/>
             <param name="auth-username" value="INBOUND_TRUNK_USERNAME"/>
             <param name="password" value="INBOUND_TRUNK_PASSWORD"/>
             <param name="register" value="true"/>
             <param name="register-transport" value="udp"/>
             <param name="expire-seconds" value="3600"/>
             <param name="retry-seconds" value="30"/>
             <param name="context" value="from-didww"/>
             <param name="extension" value="didww-inbound"/>
           </gateway>
         </include>

      Replace ``INBOUND_TRUNK_USERNAME`` and ``INBOUND_TRUNK_PASSWORD`` with
      the generated trunk credentials.

      For TCP, change the registration transport:

      .. code-block:: xml

         <param name="register-transport" value="tcp"/>

      For TLS, use the registrar's TLS port and change the registration
      transport:

      .. code-block:: xml

         <param name="proxy" value="nyc.sip.didww.com:5061"/>
         <param name="register-transport" value="tls"/>

      ``sip.didww.com`` is the authentication realm. The example uses
      ``nyc.sip.didww.com`` as the registration proxy. To use automatic
      location selection or another published regional proxy, see
      :ref:`SIP Registrars <service_did_sip>` and change the proxy hostname.
      Keep the port and transport required by the selected signaling
      transport.

      The fixed ``extension`` sets the FreeSWITCH dialplan destination to
      ``didww-inbound`` for calls received through this gateway. To route by
      called DID instead, enable **Use DID in R-URI** in the DIDWW User Panel
      and set the gateway ``extension`` to ``auto_to_user``. That variation is
      not used in this guide.

.. _freeswitch-configure-outbound-gateway:

1.4 Configure the outbound trunk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create ``/etc/freeswitch/sip_profiles/external/didww-out.xml``:

.. code-block:: xml

   <include>
     <gateway name="didww-out">
       <param name="proxy" value="nyc.us.out.didww.com"/>
       <param name="realm" value="out.didww.com"/>
       <param name="username" value="OUTBOUND_TRUNK_USERNAME"/>
       <param name="auth-username" value="OUTBOUND_TRUNK_USERNAME"/>
       <param name="password" value="OUTBOUND_TRUNK_PASSWORD"/>
       <param name="register" value="false"/>
       <param name="caller-id-in-from" value="true"/>
       <param name="ping" value="30"/>
     </gateway>
   </include>

Replace ``OUTBOUND_TRUNK_USERNAME`` and ``OUTBOUND_TRUNK_PASSWORD`` with the
credentials copied from the DIDWW User Panel.

Use the ``proxy`` parameter for the selected signaling transport:

.. tab-set::

   .. tab-item:: UDP

      .. code-block:: xml

         <param name="proxy" value="sip:nyc.us.out.didww.com:5060;transport=udp"/>

   .. tab-item:: TCP

      .. code-block:: xml

         <param name="proxy" value="sip:nyc.us.out.didww.com:5060;transport=tcp"/>

   .. tab-item:: TLS

      .. code-block:: xml

         <param name="proxy" value="sip:nyc.us.out.didww.com:5061;transport=tls"/>

``out.didww.com`` is the fixed digest authentication realm. The example uses
``nyc.us.out.didww.com`` as the call-routing proxy. Select the appropriate
regional hostname under :ref:`Signaling Endpoints
<voice-out-signaling-endpoints>` and change the proxy hostname. Keep the port
and URI transport parameter required by the selected signaling transport.

.. important::

   Keep ``register`` set to ``false``. DIDWW authenticates outbound INVITE
   requests by the allowed source IP address and SIP digest credentials. The
   outbound trunk does not register to DIDWW.

For additional gateway settings, see the official FreeSWITCH `gateways
<https://developer.signalwire.com/freeswitch/users-and-endpoints/gateways/>`_
documentation.

2. Optional trunk configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use only the sections required by your deployment. Configure NAT when
FreeSWITCH is behind NAT. Media encryption and T.38 fax are optional.

2.1 Configure NAT and firewall rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If FreeSWITCH is behind NAT, set the public signaling and media addresses in
``/etc/freeswitch/vars.xml``:

.. code-block:: xml

   <X-PRE-PROCESS cmd="set" data="external_sip_ip=203.0.113.10"/>
   <X-PRE-PROCESS cmd="set" data="external_rtp_ip=203.0.113.10"/>

Replace ``203.0.113.10`` with the public IP address and forward the external
Sofia signaling port and the configured FreeSWITCH RTP range to the server.

For inbound calls, allow signaling and media from the addresses and ports in
:ref:`General SIP Information <service_did_sip>`. For outbound calls, allow
FreeSWITCH to reach the signaling endpoints and exchange media using the
addresses and ports in :ref:`SIP Protocol Details <services_voice_out>`.

This guide assumes that RTP media passes through FreeSWITCH. If you enable
bypass media, configure the firewall and NAT rules for direct RTP between
DIDWW and the call endpoint.

For details about Sofia NAT settings, see the official `SIP profile NAT
reference
<https://developer.signalwire.com/freeswitch/users-and-endpoints/sip-profiles/#nat-traversal>`_.

2.2 Configure SRTP media encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The FreeSWITCH media-encryption configuration must match the corresponding
DIDWW trunk. DIDWW supports SDES, DTLS, and ZRTP for SRTP key negotiation.
This guide uses SDES because it is supported by the standard FreeSWITCH Sofia
SIP trunk configuration. FreeSWITCH primarily uses DTLS-SRTP for WebRTC, and
ZRTP is not covered by this configuration.

The following dialplan action requires SDES-SRTP on an outbound leg:

.. code-block:: xml

   <action application="set" data="rtp_secure_media_outbound=mandatory:AES_CM_128_HMAC_SHA1_80"/>

Add the action before ``bridge`` in :ref:`Configure outbound routing
<freeswitch-configure-outbound-routing>`. When every call on the external
profile must use SRTP, you can also add the following profile setting:

.. code-block:: xml

   <param name="require-secure-rtp" value="true"/>

Select SDES as the SRTP method in the :ref:`inbound trunk
<user_panel_sipin_trunk_media_dtmf>` and :ref:`outbound trunk
<outbound_trunk_create_media>` settings. Use TLS signaling to protect SDES
keys carried in SDP.

For FreeSWITCH behavior and supported suites, see the official `secure media
documentation
<https://developer.signalwire.com/freeswitch/media-and-codecs/handling/#secure-media-with-srtp>`_.

.. note::

   Encryption applies only to the call leg between DIDWW and FreeSWITCH. It is
   not end-to-end encryption.

2.3 Configure T.38 fax passthrough
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For an inbound DID that supports T.38, add this setting to the external Sofia
profile:

.. code-block:: xml

   <param name="t38-passthru" value="true"/>

The dialplan must bridge the call to a T.38-capable endpoint or application.
For T.38 availability and G.711 fax alternatives, see
:doc:`../../voice/inbound-trunks/technical-data/fax-services`. For FreeSWITCH
fax behavior, see the official `Fax and T.38 documentation
<https://developer.signalwire.com/freeswitch/applications/fax/>`_.

.. _freeswitch-configure-xml-dialplan:

Step 2: Configure the XML dialplan
----------------------------------

The FreeSWITCH XML dialplan determines how calls are routed. Add rules that
send inbound DIDWW calls to a local extension and send outbound calls through
the DIDWW gateway.

.. _freeswitch-configure-inbound-routing:

1. Configure inbound routing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create ``/etc/freeswitch/dialplan/didww-inbound.xml`` with the configuration
for the selected inbound trunk type.

.. tab-set::
   :sync-group: freeswitch-inbound-method

   .. tab-item:: Static Endpoint
      :sync: static-endpoint

      Match the DID from the Request-URI and bridge the call to internal user
      ``1001``:

      .. code-block:: xml

         <include>
           <context name="from-didww">
             <extension name="didww-inbound">
               <condition field="destination_number" expression="^12025550123$">
                 <action application="set" data="hangup_after_bridge=true"/>
                 <action application="bridge" data="user/1001@$${domain}"/>
               </condition>
             </extension>
           </context>
         </include>

      Replace ``12025550123`` with the assigned DID and ``1001`` with the
      internal user, application, or destination that should receive the
      call.

   .. tab-item:: Dynamic Registration
      :sync: dynamic-registration

      Match the fixed extension from the ``didww-in`` gateway and bridge the
      call to internal user ``1001``:

      .. code-block:: xml

         <include>
           <context name="from-didww">
             <extension name="didww-inbound">
               <condition field="destination_number" expression="^didww-inbound$">
                 <action application="set" data="hangup_after_bridge=true"/>
                 <action application="bridge" data="user/1001@$${domain}"/>
               </condition>
             </extension>
           </context>
         </include>

      Replace ``1001`` with the internal user, application, or destination
      that should receive the call.

.. _freeswitch-configure-outbound-routing:

2. Configure outbound routing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add the following extension to a dialplan context used only by authenticated
internal users. A standard FreeSWITCH installation normally assigns these
users to the dialplan context named ``default``.

Create ``/etc/freeswitch/dialplan/default/10_didww_outbound.xml``:

.. code-block:: xml

   <include>
     <extension name="didww-outbound">
       <condition field="destination_number" expression="^(\d{8,15})$">
         <action application="set" data="effective_caller_id_number=12025550123"/>
         <action application="set" data="hangup_after_bridge=true"/>
         <action application="bridge" data="sofia/gateway/didww-out/$1"/>
       </condition>
     </extension>
   </include>

Replace ``12025550123`` with a caller ID allowed by the outbound trunk. Send
destination and caller ID numbers in E.164 format. For example, dial
``12025550199``. See :doc:`../../voice/outbound-trunks/routing-dialing/outbound-dialing`
for the supported number formats.

.. warning::

   Do not place the outbound extension in ``from-didww`` or ``public``. Those
   contexts receive internet-facing traffic and must not provide access to the
   outbound gateway.

For XML dialplan concepts and syntax, see the official `FreeSWITCH XML
dialplan documentation
<https://developer.signalwire.com/freeswitch/dialplan/xml/>`_.

.. _freeswitch-load-and-verify-configuration:

Step 3: Load and verify the configuration
-----------------------------------------

Run the following command from the operating-system shell to connect to the
FreeSWITCH console:

.. code-block:: bash

   fs_cli

From the FreeSWITCH console, reload the XML configuration and ACL, then rescan
the external profile for gateway changes:

.. code-block:: console

   reloadxml
   reloadacl
   sofia profile external rescan

Changes to profile settings such as the listening port, TLS, or profile ACL
may require a profile restart. Run the following command from the FreeSWITCH
console:

.. code-block:: console

   sofia profile external restart reloadxml

.. warning::

   Restarting a Sofia profile ends active calls on that profile. Perform the
   restart during a maintenance window.

Use the following commands to confirm that FreeSWITCH loaded the
configuration and can communicate with DIDWW:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Check
     - Command
   * - FreeSWITCH status
     - ``status``
   * - Loaded Sofia profiles
     - ``sofia status``
   * - External profile details
     - ``sofia status profile external``
   * - Inbound gateway registration
     - ``sofia status gateway didww-in``
   * - Outbound gateway
     - ``sofia status gateway didww-out``
   * - Active calls
     - ``show calls``
   * - Active channels
     - ``show channels``
   * - Live SIP trace
     - ``sofia global siptrace on``

The ``didww-in`` gateway check applies only to Dynamic Registration. Its state
should be ``REGED`` before testing inbound calls. The ``didww-out`` gateway
does not register, so verify that it is loaded and available rather than
expecting a registration state.

Place an inbound test call to the DID configured in the inbound dialplan and
confirm that the configured internal destination rings. Then place an outbound
test call from an authenticated internal user to a valid destination. Confirm
two-way audio and DTMF in both directions.

Common issues
^^^^^^^^^^^^^

.. dropdown:: A profile, gateway, or dialplan rule does not load.

   Run ``reloadxml`` and check the FreeSWITCH console for the file name and
   line number of any XML error.

   Use ``sofia status profile external`` to check the profile. Use
   ``sofia status gateway didww-in`` or ``sofia status gateway didww-out`` to
   check a gateway. After changing a gateway file, run
   ``sofia profile external rescan``.

.. dropdown:: Inbound calls receive ``403`` Forbidden.

   This normally means that the ``didww`` ACL rejected the request. Confirm
   that the source address appears in the current DIDWW signaling ranges.

   Run ``reloadacl`` after changing ``acl.conf.xml`` and use
   ``sofia global siptrace on`` to inspect the request source.

.. dropdown:: A Static Endpoint call reaches FreeSWITCH but does not reach the internal endpoint.

   Confirm that the User Panel trunk uses ``{DID}`` as the User Part of R-URI
   and sends calls to the external profile's public host and port.

   Confirm that the received ``destination_number`` matches the DID in
   ``didww-inbound.xml``.

.. dropdown:: A Dynamic Registration gateway remains unregistered.

   Run ``sofia status gateway didww-in``. Confirm the inbound username and
   password, the registrar hostname, port, and signaling transport.

   Keep ``sip.didww.com`` as the realm even when a regional registrar is used
   as the proxy. Use ``sofia global siptrace on`` to inspect the REGISTER
   request and authentication response.

.. dropdown:: A Dynamic Registration call uses ``didww-inbound`` instead of the called DID.

   This is expected with the Dynamic Registration example. The gateway uses a
   fixed ``extension`` value. See :ref:`Configure the inbound trunk
   <freeswitch-configure-inbound-gateway>` for the fixed-destination behavior
   and the DID-based alternative.

.. dropdown:: Outbound calls return ``403`` or repeat ``407`` challenges.

   Confirm the outbound trunk credentials, the public FreeSWITCH address in
   **Allowed SIP IP addresses**, and the caller ID in the trunk's CLI settings.

   Keep ``out.didww.com`` as the digest realm even when a regional hostname is
   used as the proxy. Use ``sofia global siptrace on`` to check the response
   from DIDWW.

.. dropdown:: An outbound call does not use the DIDWW gateway.

   Confirm that the authenticated user enters the dialplan context containing
   the outbound rule. The example uses the context named ``default``.

   Confirm that the dialed number matches the rule in
   ``didww-outbound.xml``. The example accepts an E.164 number without the
   leading ``+``.

.. dropdown:: A call has one-way audio.

   Check ``external_sip_ip``, ``external_rtp_ip``, port forwarding, and
   firewall rules.

   Confirm that the applicable DIDWW RTP ranges and the FreeSWITCH RTP port
   range are allowed.

.. dropdown:: A call fails with ``488`` Not Acceptable Here.

   Confirm that FreeSWITCH and the corresponding DIDWW trunk have a common
   codec.

   If media encryption is enabled, confirm that the configured SRTP method
   matches the trunk settings.

.. dropdown:: DTMF input is not recognized.

   Confirm that the external profile uses ``dtmf-type`` value ``rfc2833``.

   This is the FreeSWITCH setting for the RTP telephone-event method commonly
   referred to as RFC 2833.

.. dropdown:: FreeSWITCH cannot establish a TLS connection.

   Confirm that TLS is enabled on the external profile and that the certificate
   files are valid.

   For a Static Endpoint inbound trunk, confirm that the DIDWW User Panel sends
   calls to the external profile's TLS port, ``5081`` in this guide. For
   Dynamic Registration and outbound calling, confirm that the DIDWW registrar
   or proxy uses port ``5061`` and ``transport=tls``.

   For outbound TLS, use a regional DIDWW proxy and keep the authentication
   realm set to ``out.didww.com``. Use ``sofia global siptrace on`` to inspect
   the TLS connection and SIP exchange.

For additional diagnostic procedures, see the official FreeSWITCH
`troubleshooting toolbox
<https://developer.signalwire.com/freeswitch/troubleshooting/toolbox/>`_,
`call setup troubleshooting
<https://developer.signalwire.com/freeswitch/troubleshooting/call-setup/>`_,
and `audio troubleshooting
<https://developer.signalwire.com/freeswitch/troubleshooting/audio/>`_.


Twilio BYOC
===========

The following guide will explain the steps necessary to configure the Twilio Console with DIDWW SIP trunks.

Getting started
---------------

What you need to get started:

For **Termination (Inbound)**:

    * Access to `DIDWW self-service portal <https://my.didww.com/#/users/sign_in>`_ to create :ref:`Inbound SIP trunk <user_panel_sipin_trunk>`  and :ref:`assign <user_panel_assign_trunk>` it to the preferred DID number.
    * Access to `Twilio Console <https://console.twilio.com/>`_.

For **Origination (Outbound)**:

    * Access to `DIDWW self-service portal <https://my.didww.com/#/users/sign_in>`_ to create :ref:`Outbound SIP trunk <user_panel_voice_out>`.
    * Access to `Twilio Console <https://console.twilio.com/>`_ and Account SID.

Termination (Inbound)
---------------------

To configure the DIDWW Inbound SIP Trunk using the Twilio Console, follow these steps:

**Step 1.** In the Twilio Console, expand the "Voice" section, then "Manage", and select "IP access control lists" (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Twilio Console window.

**Step 2.** In the IP / CIDR Access Control Lists window, click "Create new Access Control List" (Fig. 2).

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** IP / CIDR Access Control Lists window.

**Step 3.**  In the window that opens, enter an "ACL friendly name" and, optionally, the "IP range friendly name". Then, input the "CIDR Network Address" (IP address) of :ref:`DIDWW POPs <service_did_sip>`, and select the range (Fig. 3).

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 3.** Create new Access Control List window.

.. note:: 
    If you would like to add only a few IPs, they can all be added under one control list. Once the ACL is created, you can add them by selecting "Create New IP Address Range" in the window (Fig. 4).

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 4.** ACL list edit window.

**Step 4.** After the ACL list is created, select "SIP Domains" in the sidebar and click on the blue plus icon (Fig. 5).

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 5.** SIP domains window.

**Step 5.**  In the "New SIP Domain" window, enter the Friendly Name and SIP URI. In the "Voice Authentication" section, select the access control list you created, and in the "Call Control Configuration" section, choose the BYOC Trunk (Fig. 6).

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center

  **Fig. 6.** New SIP Domain window.

.. note:: 
    Do not forget the SIP URI (companydomain.sip.twilio.com). It will be your host while creating the :ref:`DIDWW Inbound SIP trunk <user_panel_sipin_trunk>`.

**Step 6.** After the SIP domain is created, select "BYOC Trunks". In the window that opens, click the blue plus icon. In the new window, enter the trunk name and click "Create BYOC Trunk" (Fig. 7).

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center

  **Fig. 7.** BYOC Trunks window.

**Step 7.** In the "General Settings" window, select the SIP domain you created in **Step 5.** for the "From Domain" field. Make sure that you select the same SIP domain (Fig. 8).

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center

  **Fig. 8.** BYOC Trunk, General Settings window.

**Step 8.** In the "Application Configuration" section, enter your system URLs for handling incoming calls. Three URLs are required: a Primary URL, a Failover URL, and a URL for call status changes. Once completed, click "Save" to apply the changes (Fig. 9).

.. note:: 
    Examples about handling incoming calls from Twilio and more can be found in `Twilio Docs <https://www.twilio.com/docs/voice#build-your-app>`_

.. figure:: https://doc.didww.com/_images/fig9.png
  :figclass: align-center

  **Fig. 9.** BYOC Trunk, Application Configuration section.

Your BYOC trunk is ready to accept calls from DIDWW Inbound SIP Trunk.

Origination (Outbound)
----------------------

To configure the DIDWW Outbound SIP trunk with the Twilio Console, proceed with the following steps:

**Step 1.** In the Twilio Console, expand the "Voice", and then "Manage" sections, and select "Origination connection policy" (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig1.png
  :figclass: align-center

  **Fig. 1.** Twilio Console window.

**Step 2.** Once the Origination Connection Policy window opens, click the blue plus icon, enter a friendly name, and then click "Create" (Fig. 2).

.. figure:: https://doc.didww.com/_images/fig2.png
  :figclass: align-center

  **Fig. 2.** Origination Connection Policy window.

**Step 3.** In the same window, click on the connection policy you created. In the window that opens, select "Add New Origination Target" or click the blue plus icon (Fig. 3).

.. figure:: https://doc.didww.com/_images/fig3.png
  :figclass: align-center

  **Fig. 3.** Origination Connection Policy window.

**Step 4.** When a new window opens, enter the origination SIP URI in the following format: "sip:domain.com". The `domain.com` is one of :ref:`DIDWW Outbound Endpoints <services_voice_out>` or use `out.didww.com`. Finally, click "Save" to add a target (Fig. 4).

.. figure:: https://doc.didww.com/_images/fig4.png
  :figclass: align-center

  **Fig. 4.** Create Origination Target window.

After this, you can either create a new BYOC (Bring Your Own Carrier) trunk or add the Connection Policy to an existing trunk. The following sections will explain both scenarios:

Creating BYOC Trunk with Connection Policy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Step 1.** Select "BYOC Trunks." In the window that opens, click the blue plus icon. In the new window, enter the trunk name and click "Create BYOC Trunk" (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig5.png
  :figclass: align-center

  **Fig. 1.** BYOC Trunks window.

**Step 2.** In the General Settings, go to the "Origination Connection Policy (to your Carrier)" section. Under "Destination", select the Connection Policy you created, then click "Save" to apply the changes (Fig. 2).

.. figure:: https://doc.didww.com/_images/fig6.png
  :figclass: align-center

  **Fig. 2.** General Settings window.

Add Policy to existing BYOC Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Step 1.** Select "BYOC Trunks." In the window that opens, choose your trunk name (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig7.png
  :figclass: align-center

  **Fig. 1.** BYOC Trunks window.

**Step 2.** In the General Settings, go to the "Origination Connection Policy (to your Carrier)" section. Under "Destination", select the Connection Policy you created, then click "Save" to apply the changes (Fig. 2).

.. figure:: https://doc.didww.com/_images/fig8.png
  :figclass: align-center

  **Fig. 2.** General Settings window.

Now, an `Outbound SIP Trunk <https://doc.didww.com/voice/outbound-trunks/how-to-guides/create-outbound-trunk.html>`_ can be created by selecting the "Twilio Account SID" as the authentication method and entering your account SID, which can be found in main Console window.

Your BYOC trunk is ready to originate calls via DIDWW Outbound Trunk.


.. _avaya:

Avaya
======

Introduction to Avaya Aura® Communication Manager
-------------------------------------------------

Avaya Aura® Communication Manager is an  IP telephony platform that can be deployed as an IP PBX that delivers communications to large and small enterprises.
Designed to run on a variety of Linux-based media servers, Communication Manager is a core component of the Avaya Aura® platform and the foundation for delivering real-time voice, video, messaging, and other services.

Getting started
----------------

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`_.
* `Inbound <https://doc.didww.com/voice/inbound-trunks/creating-a-new-sip-trunk.html>`_ and/or `Outbound <https://doc.didww.com/voice/outbound-trunks/how-to-guides/create-outbound-trunk.html>`_ SIP trunks, depending on what service you want to use in Avaya Communication Manager.
* `A DID number provisioned from DIDWW <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`_.
* :ref:`Inbound trunk assigned to the DID number <user_panel_assign_trunk>`.

Configuring DIDWW SIP Trunks with Avaya
---------------------------------------

Avaya provides a detailed Application note for integrating with DIDWW.
The `Application Note <https://www.devconnectprogram.com/fileMedia/download/3828885f-d764-4243-a84b-7f7d5b69c358>`_ describes the steps used to configure Session Initiation Protocol (SIP) trunking between the DIDWW SIP Trunk Service and an Avaya SIP-enabled enterprise solution. The Avaya solution consists of the following: Avaya Aura ® Communication Manager R8.1 (Communication Manager); Avaya Aura ® Session Manager R8.1 (Session Manager) and Avaya Session Border Controller for Enterprise R8.1 (Avaya SBCE).

.. important:: Download the application note here: :download:`Avaya-DIDWW Application Note.pdf`


.. _ribbon:

Ribbon
======

Introduction to SWE Edge & CNe Edge
-----------------------------------

The SBC SWe Edge is virtualized SBC software that can be deployed on Commercial Off-the-Shelf (COTS) Intel® x86 hardware platform running KVM, VMware® ESXi, and Microsoft Hyper-V hypervisors.
It can also be deployed in public cloud environments including Microsoft Azure and AWS.

The Ribbon SBC Cloud Native edition Edge (CNe Edge) is a public cloud-based enterprise SBC.
The CNe Edge breaks the main SBC SWe Edge functions into separate services: the media and the signalling. This enables increased session density and support resiliency.
The SBC CNe Edge node is based on Kubernetes orchestration and initially available in Microsoft Azure Kubernetes Service (AKS) in a cluster.

This configuration guide describes how to set up Ribbon SWE Edge or CNe Edge SBCs to interwork with DIDWW Inbound and Outbound SIP trunk services.

Getting started
---------------

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`_.
* `Inbound <https://doc.didww.com/voice/inbound-trunks/creating-a-new-sip-trunk.html>`_ and/or `Outbound <https://doc.didww.com/voice/outbound-trunks/how-to-guides/create-outbound-trunk.html>`_ SIP trunks, depending on what service you want to use in Ribbon SBC.
* `A DID number provisioned from DIDWW <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`_.
* :ref:`An inbound trunk assigned to the DID number <user_panel_assign_trunk>`.
* The initial SWE Edge or CNe Edge SBC installation, networking and hostname.

Ribbon inbound voice trunk configuration
----------------------------------------

Enter the public IP address of the SBC or the FQDN/DNS name and login with your username and password (Fig. 1).

.. figure:: https://doc.didww.com/_images/figure1.png
  :figclass: align-center

  **Fig. 1.** Ribbon SBC login page.

After login, navigate to Tasks -> SBC Easy Setup -> Easy Config Wizard (Fig. 2).

.. figure:: https://doc.didww.com/_images/figure2.png
  :figclass: align-center

  **Fig. 2.** Ribbon SBC interface.

**Step 1:**

Select "SIP Trunk" for your application (Fig. 3).

Enter scenario description e.g. "DIDWW Inbound"

Select the "Telephone Country"

Enter the number of maximum allowed concurrent SIP sessions

.. figure:: https://doc.didww.com/_images/figure3.png
  :figclass: align-center

  **Fig. 3.** Easy Config Wizard.

**Step 2:**

Enter DIDWW IP, protocol and port information (Fig. 4).

DIDWW New York IP is used in this example.

Border Element Server	 – **46.19.209.14**

Protocol - **UDP**

Port Number - **5060**

.. figure:: https://doc.didww.com/_images/figure4.png
  :figclass: align-center

  **Fig. 4.** Inbound SIP trunk details.

**Step 3:**

Confirm the details and click *Finish* to save the config.

**Step 4:**

Navigate to *Settings* -> *Signalling Groups* and click *DIDWW Inbound: Border Element*

Add inbound signalling IPs into the Ribbon SBC, as shown in the example below (Fig. 5).

A full list of DIDWW inbound signalling IPs:

.. code-block::

  46.19.209.14:5060 (for New York POP)
  46.19.210.14:5060 (for Frankfurt POP)
  46.19.212.14:5060 (for Los Angeles POP)
  46.19.213.14:5060 (for Miami POP)
  46.19.214.14:5060 (for Singapore POP)
  46.19.215.14:5060 (for Hong Kong PoP)
  185.238.173.14:5060 (for Amsterdam PoP)

.. figure:: img/figure5.png
  :figclass: align-center

  **Fig. 5.** Allowing DIDWW signalling IPs.

**Step 5:**

Navigate to *Settings* -> *SIP* -> *SIP Server Tables*  and click *DIDWW Inbound: Border Element*

Select *SIP Options* as shown in the example below (Fig. 6).

Enter any preferred Local and Peer usernames

.. figure:: https://doc.didww.com/_images/figure6.png
  :figclass: align-center

  **Fig. 6.** Enabling SIP options.

Ribbon outbound voice trunk configuration
-----------------------------------------

Navigate to Tasks -> SBC Easy Setup -> Easy Config Wizard (Fig. 1).

**Step 1:**

Select "SIP Trunk" for your application

Enter scenario description e.g. "DIDWW Outbound"

Select the "Telephone Country"

Enter the number of maximum allowed concurrent SIP sessions

.. figure:: https://doc.didww.com/_images/figure7.png
  :figclass: align-center

  **Fig. 1.** Easy Config Wizard.

**Step 2:**

Enter DIDWW FQDN, protocol and port information (Fig. 2).

Select the preferred DIDWW outbound FQDN from the list below:

.. code-block::

  nyc.us.out.didww.com
  fra.eu.out.didww.com
  lac.us.out.didww.com
  mia.us.out.didww.com
  sg.out.didww.com

DIDWW New York FQDN is used in the following example

Border Element Server	 – **nyc.us.out.didww.com**

Protocol - **UDP**

Port Number - **5060**

.. figure:: https://doc.didww.com/_images/figure8.png
  :figclass: align-center

  **Fig. 2.** Outbound SIP trunk details.

**Step 3:**

Confirm the details and click *Finish* to save the config.

**Step 4:**

Navigate to *Settings* -> *SIP* -> *Remote Authorization Table* and click on *Create Remote Authorization Table* (Fig. 3).

.. figure:: https://doc.didww.com/_images/figure9.png
  :figclass: align-center

  **Fig. 3.** Creating Remote Authorization Table.

**Step 5:**

Select the created authorization table and click on *Create Remote Authorization Entry* (Fig. 4).

Realm - **out.didww.com**

Authentication ID	- **Outbound Trunk Username**

Password - **Outbound Trunk Password**

Confirm Password - **Outbound Trunk Password**

From URI User Match	- **Regex**

Match Regex	- **(.*)**

This RegEx expression means “Everything”.

.. figure:: https://doc.didww.com/_images/figure10.png
  :figclass: align-center

  **Fig. 4.** Creating Remote Authorization Entry.

**Step 6:**

Navigate to *Settings* -> *SIP* -> *SIP Server Tables*  and click on *DIDWW Outbound: Border Element*

Add *DIDWW Digest* Remote Authorization table.

Configure *SIP Options* as shown in the example below (Fig. 5).

.. figure:: https://doc.didww.com/_images/figure11.png
  :figclass: align-center

  **Fig. 5.** DIDWW Outbound SIP server table configuration.

**Step 7:**

Navigate to *Settings* -> *Call Routing Table* -> *DIDWW Outbound : From SIP Trunk* and click *Create Call Routing Entry*

Under *Destination Signalling Groups* -> Add *DIDWW Outbound: Border Element* (Fig. 6).

.. figure:: https://doc.didww.com/_images/figure12.png
  :figclass: align-center

  **Fig. 6.** Creating Call Route Entry.

SIP connectivity
----------------

After successfully configuring both trunks, the *“Service Status”* should be displayed as *Up* (Fig. 1).

.. figure:: https://doc.didww.com/_images/figure13.png
  :figclass: align-center

  **Fig. 1.** SIP connection status.

To check detailed SIP connectivity status of your Signaling Group, click *Counters* (Fig. 2).
You should see SIP options pings in the *Outgoing* tab as well as 200OK responses in the *Incoming* tab.

.. figure:: https://doc.didww.com/_images/figure14.png
  :figclass: align-center

  **Fig. 2.** SIP Message Counters.

To confirm that the outbound trunk setup was successful, simply make a test call using Ribbon test calling tool (Fig. 3).

Navigate to -> Diagnostics -> Tools -> Test A Call

Destination Number	- enter destination number

Origination/Calling Number	- enter originating number

Call Routing Table - DIDWW Outbound: From SIP Trunk

A green checkmark indicates a successful completion of a test call.

.. figure:: https://doc.didww.com/_images/figure15.png
  :figclass: align-center

  **Fig. 3.** Test Call Tool.

Troubleshooting
----------------

Ribbon provides a Packet Capture feature for troubleshooting (Fig. 1). This option is used to identify and better understand SIP signalling issues.

To start capturing packets:

1. In the Ribbon web interface, click the *Diagnostics* tab.

2. In the navigation bar, select *Ribbon Service Troubleshooting* > *Packet Capture.*

3. Click *Start Capture.*

4. Select the network interface (including IP version) from which the packets will be captured.

5. Select protocols to capture the packets.

6. Configure any relevant information in the *Other Options* section.

7. Click OK.

.. figure:: https://doc.didww.com/_images/figure16.png
  :figclass: align-center

  **Fig. 1.** Starting packet capture.

Once the packet capture is complete, simply open the PCAP file with Wireshark for a full analysis of the SIP Signalling stream (Fig. 2).

.. figure:: https://doc.didww.com/_images/figure17.png
  :figclass: align-center

  **Fig. 2.** SIP signalling stream via Wireshark.


.. _telinta:

Telinta
=======

Introduction to Telinta TeliCore Solution & DIDWW phone.systems™
------------------------------------------------------------------
Telinta offers cloud-based switching and billing solutions for VoIP service providers around the world. These white label solutions enable Telinta customers to operate a VoIP business without deploying their own infrastructure.

As a part of its portfolio, Telinta offers upgraded integration of DIDWW phone.systems™ Cloud PBX which can be used together with DIDWW’s DID numbers and PSTN termination.

Telinta’s hosted `TeliCore™ <https://www.telinta.com/hosted-softswitch/>`_ softswitch platform enables VoIP service providers to offer phone.systems™ to both end user customers and resellers.
This integration allows a single hosted platform to manage key functions for switching, billing and customer management, as well as have access to DIDWW DIDs, PSTN termination, and phone.systems™ PBX.

The solution includes Telinta’s multi-currency, multi-language brandable portals.
With Telinta’s billing and integration with dozens of credit card processors, VoIP service providers can charge monthly fees, per-channel and per-minute fees, create volume discounts and special promotions, offer both prepaid and postpaid VoIP services.

`phone.systems™ <https://phone.systems/>`_ is a fully-featured, cloud-based virtual PBX that is specifically designed to interconnect with any service provider.
There is no special hardware to purchase and maintain, and phone.systems™ is compatible with all landlines, mobile phones and computers, SIP devices and multi-line desktop phones.
Operator APIs have been built to open up the phone.systems™ software products for integration with service operators, MVNOs, resellers, enterprise customers and other types of telecommunication service providers.
The Operator API endpoints provide the ability to provision and combine third-party SIP resources and services with the cloud based PBX phone.systems™ and deliver full PBX solutions to customers via the operator’s self-service portal.

Telinta TeliCore™ features:

* Real-time call detail records for both prepaid and postpaid services.
* On-the-spot analysis of key metrics.
* Self-care portals for end users to review their account, make payments, recharge prepaid balances and more.
* Auto-Provisioning for hundreds of popular SIP devices.
* Bilateral billing agreements.
* Multiple-currency billing, with auto-fetch for current exchange rates.
* Billing for end users and resellers.
* Ability to create volume discounts and promotions.
* Payments via Paypal, credit cards, in-person cash payments.
* Access to third-party billing compliance services for telecom taxation in more than 100 countries.

Getting started
---------------

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`_
* `DIDWW API3 key <https://doc.didww.com/api3/configuration.html>`_
* `Phone.systems™ Operator plan <https://my.didww.com/#/phone_systems>`_
* `Outbound SIP trunk <https://doc.didww.com/voice/outbound-trunks/how-to-guides/create-outbound-trunk.html>`_
* `Telinta TeliCore™ solution <https://telinta.com/billing/>`_

Administration portal
----------------------------------------

Auth Customers management page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Auth customers management page allows administrators to:

* View new customers
* View new DID orders
* Approve payments
* Reject payments
* Block/unblock new DID orders
* View charged DID number subscriptions
* Restore canceled DID numbers

.. figure:: https://doc.didww.com/_images/7.png
  :figclass: align-center

  **Fig. 1.** Viewing new customers.

.. figure:: https://doc.didww.com/_images/8.png
  :figclass: align-center

  **Fig. 2.** Approving/rejecting customers.

DID subscription plan management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Subscritpion plan management page allows administrators to provide discounts based on DID purchasing period, add promotional periods, change DID periodic fee.

.. figure:: https://doc.didww.com/_images/9.png
  :figclass: align-center

  **Fig. 3.** Editing subscription plan.

Customer management
^^^^^^^^^^^^^^^^^^^
Customer management allows administrators to:

* View billing information
* Configure automatic payments
* Trigger e-commerce payments
* Apply DID subscriptions manually
* Manage email notifications
* Access customer phone.systems™ PBX tenant as an admin
* Port DID numbers manually

.. figure:: https://doc.didww.com/_images/10.png
  :figclass: align-center

  **Fig. 4.** Custom fields of phone.systems™ management.

.. figure:: https://doc.didww.com/_images/11.png
  :figclass: align-center

  **Fig. 5.** Customer purchased DIDs field.

.. figure:: https://doc.didww.com/_images/12.png
  :figclass: align-center

  **Fig. 6.** Web self-care management as customer.

.. figure:: https://doc.didww.com/_images/13.png
  :figclass: align-center

  **Fig. 7.**  Forwarding options to phone.systems™.

End-user portal
----------------

New customer sign-up
^^^^^^^^^^^^^^^^^^^^

End users signing up are able to:

* Browse countries and DID numbers
* Fill out registration form (if applicable)
* Fill out subscriber info
* Choose payment method
* Complete anti-bot verification (Google captcha)
* Confirm email address
* Receive welcome email

.. figure:: https://doc.didww.com/_images/1.png
  :figclass: align-center

  **Fig. 8.**  Browsing countries and DID numbers.

.. figure:: https://doc.didww.com/_images/2.png
  :figclass: align-center

  **Fig. 9.**  Filling out registration form.

.. figure:: https://doc.didww.com/_images/3.png
  :figclass: align-center

  **Fig. 10.**  Filling out subscriber information.

.. figure:: https://doc.didww.com/_images/4.png
  :figclass: align-center

  **Fig. 11.**  Choosing payment method.

.. figure:: https://doc.didww.com/_images/5.png
  :figclass: align-center

  **Fig. 12.**  Accepting terms and agreements, completing anti-bot verification.

.. figure:: https://doc.didww.com/_images/6.png
  :figclass: align-center

  **Fig. 13.**  Filling out credit card information.

Customer self-care portal
^^^^^^^^^^^^^^^^^^^^^^^^^

End users are able to:

* Browse and purchase DIDs (virtual numbers)
* View CDRs (call history)
* Manage PBX (phone.systems™)
* View billing info (my account)
* Make payments
*	Enter new credit cards

.. figure:: https://doc.didww.com/_images/14.png
  :figclass: align-center

  **Fig. 14.**  My account section.

.. figure:: https://doc.didww.com/_images/15.png
  :figclass: align-center

  **Fig. 15.**  Virtual numbers section.

.. figure:: https://doc.didww.com/_images/16.png
  :figclass: align-center

  **Fig. 16.**  Manage phone.systems™ PBX section.


.. _zapier:

Zapier
======

Introduction
------------

Zapier https://zapier.com/ allows to interact between popular applications and empowers you to automate your tasks across many different apps. Creates automated workflows and tasks to use different web applications together. It is often described as a translator between web APIs, helping to increase worker productivity by saving time through automation of recurring tasks, and business processes such as lead management. Through an interface in which users can set up workflow rules to determine how its automations function,
it orchestrates flow of data between tools and online services that wouldn't otherwise communicate with one another.

This configuration guide describes how to set up Zapier to interwork with DIDWW SMS and/or Voice call-events services.

DIDWW SMS OUT App enabled by Zapier
-----------------------------------

DIDWW SMS OUT App allows you to send SMS messages from your existing DIDWW SMS-enabled DID number to any other SMS enabled destination number. It can be used with apps from Zapier platform, enabling non-sms capable applications to send SMS messages. For example, an SMS message notification may be triggered by a certain action on your CRM or other task management software. Please `read more <https://doc.didww.com/services/outgoing-sms/index.html>`__ about SMS OUT service at DIDWW.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`__.
* `At least one SMS enabled DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`__.
* `An SMS HTTP OUT Trunk at DIDWW (credentials of which will be used later in this guide) <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-out.html>`__.

**Configuring DIDWW SMS OUT App**

As a use case example, we will connect Google form to send SMS messages upon form submission. Answers submitted to Google form will be sent via SMS message to the configured phone number.

**Step 1.** Create a Google form with two short answer type questions:  *SMS Destination Number, and SMS Text* (Fig. 1).

.. figure:: https://doc.didww.com/_images/1.png
  :figclass: align-center

  **Fig. 1.** Google form.

**Step 2.** Create Zap in your Zapier account (Fig. 2).

.. figure:: https://doc.didww.com/_images/2.png
  :figclass: align-center

  **Fig. 2.** Creating a new Zap.

**Step 3.** In the Zap creation process, under the *App Event*, search for *Google Forms* and select it (Fig. 3).

.. figure:: https://doc.didww.com/_images/3.png
  :figclass: align-center

  **Fig. 3.** Trigger App selection.

**Step 4.** Select the *New Form Response* as your Trigger Event (Fig. 4).

.. figure:: https://doc.didww.com/_images/4.png
  :figclass: align-center

  **Fig. 4.** Trigger Event selection.

**Step 5.** Sign in to your Google Account on which the Google Form was created (Fig. 5). After successful authentication, continue to the next step.

.. figure:: https://doc.didww.com/_images/5.png
  :figclass: align-center

  **Fig. 5.** Signing in to your Google Account.

**Step 6.** Select your previously created Google Form and click to continue (Fig. 6). After a successful Google Form verification, click *Continue* to move to the *Actions* section.

.. figure:: https://doc.didww.com/_images/6.png
  :figclass: align-center

  **Fig. 6.** Selecting the previously created Google Form.

**Step 7.**  Search for *DIDWW SMS OUT* under the *App event* search menu and select it (Fig. 7).

.. figure:: https://doc.didww.com/_images/7.png
  :figclass: align-center

  **Fig. 7.** Selecting the previously created Google Form.

**Step 8.** Under the *Event* selection menu search for *Send SMS* and select it. Click *Continue*. (Fig. 8).

.. figure:: https://doc.didww.com/_images/8.png
  :figclass: align-center

  **Fig. 8.** Selecting the *Send SMS* event.

**Step 9.** Click *Sign in* and connect the DIDWW SMS OUT App with credentials from the DIDWW SMS OUT Trunk (Fig. 9).

.. figure:: https://doc.didww.com/_images/9.png
  :figclass: align-center

  **Fig. 9.** Connecting the DIDWW SMS OUT Zapier App.

**Step 10.** In the next window (Fig. 10) enter your DIDWW HTTP SMS OUT trunk username and password which were generated upon `SMS HTTP OUT Trunk creation <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-out.html>`_. Also, you may specify the trunk name for better identification (in case multiple trunks are authenticated). Click *Continue* after successful authentication.

.. figure:: https://doc.didww.com/_images/10.png
  :figclass: align-center

  **Fig. 10.** Entering HTTP SMS OUT trunk credentials.

**Step 11.** Open up the *Set up action* tab (Fig. 11) where you can add static values or take placeholders of previously created and connected Google Form (Fig. 1).

* For the *DID Number* add a static phone number. This should be an `SMS enabled DID number <https://www.didww.com/coverage-and-prices/coverage>`_ existing on your DIDWW account and added to the *SMS HTTP OUT trunk* source addresses list. The accepted number formats are: E.164 or +E.164 (Country Code + Area Code + Number).
* For the *Destination Number* select the *SMS Destination Number* Google Form from the dropdown menu. The accepted number formats are: E.164 or +E.164 (Country Code + Area Code + Number).
* For the *SMS Text* select the *SMS Text* Google Form from the dropdown menu.

After all fields have been selected click *“Continue”* (Fig. 11).

.. figure:: https://doc.didww.com/_images/11.png
  :figclass: align-center

  **Fig. 11.** Configuring action values.

**Step 12.** After clicking “Continue” an automatic test will be initiated and an SMS message will be sent with your configured values. Also, the result response data (message type and id) will be shown in the Zapier test action window (Fig. 12). Proceed to publishing your Zap (Fig. 12).

.. figure:: https://doc.didww.com/_images/12.png
  :figclass: align-center

  **Fig. 12.** Testing the action and publishing Zap.

**Step 13.** Open your previously created Google Form, enter *SMS Destination Number*, *SMS Text* and click *Submit* (Fig. 13). An SMS message should be sent to the specified destination number with the entered text in it.
If something went wrong and the SMS did not reach the destination number, you can check the Outbound SMS Log on your `DIDWW account <https://my.didww.com/#/users/sign_in>`_ or in the Zap History log.

.. figure:: https://doc.didww.com/_images/13.png
  :figclass: align-center

  **Fig. 13.** Submitting Google Form.

DIDWW SMS HTTP IN and Zapier Webhook
------------------------------------

DIDWW SMS IN service allows you to receive SMS messages to your existing DIDWW SMS enabled DID numbers. Zapier Webhook allows DIDWW SMS IN service to be used with Apps available on Zapier platform, enabling non-sms capable applications to receive SMS messages. For example, an incoming SMS message can create an event or task in your CRM or other task management software. Please `read more <https://doc.didww.com/sms/sms-trunks/index.html>`__ about DIDWW SMS IN service.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/>`_.
* `At least one SMS enabled DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`_.
* `An SMS HTTP IN Trunk at DIDWW <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-in.html>`_.
* `SMS HTTP IN Trunk assigned to your SMS enabled DID <https://doc.didww.com/sms/sms-trunks/assigning-an-sms-trunk.html>`_.

**Configuring DIDWW SMS HTTP IN and Zapier Webhook**

As a use case example, we will connect a DIDWW SMS enabled DID number for incoming messages to be stored in Google Sheets. You may choose any other available Zapier App required for your idea/automation/task/project as an *Action* for incoming DIDWW SMS messages.

**Step 1.** Create Zap in your Zapier account (Fig. 1).

.. figure:: https://doc.didww.com/_images/1.png
  :figclass: align-center

  **Fig. 1.** Creating a new Zap.

**Step 2.** Select *Webhooks by Zapier* as your trigger for the App event. (Fig.2).

.. figure:: https://doc.didww.com/_images/2.png
  :figclass: align-center

  **Fig. 2.** Selecting *Webhooks by Zapier* trigger.

**Step 3.** Select “Catch Hook” in the event dropdown menu (Fig.3)

.. figure:: https://doc.didww.com/_images/3.png
  :figclass: align-center

  **Fig. 3.** Selecting “Catch Hook”.

**Step 4.** Leave the *Child Key* field empty and click *Continue* (Fig.4).

.. figure:: https://doc.didww.com/_images/4.png
  :figclass: align-center

  **Fig. 4.** *Child key* field is left empty.

**Step 5.** A *webhook* URL will be generated for testing your trigger. Copy it for the next step (Fig. 5) and click the *Test trigger* button.

.. figure:: https://doc.didww.com/_images/5.png
  :figclass: align-center

  **Fig. 5.** Copy Zapier webhook URL.

**Step 6.** On your DIDWW account create or edit the previously created SMS HTTP IN trunk (Fig. 6). Make the following trunk configurations:

* HTTP method – select POST
* Request URL – paste URL which was copied in **Step 5**
* Body type - select JSON
* Request body – add placeholders which you need. 
  
  For example: 

  .. code-block::

    {"TIME":"{SMS_TIME}","SRC":"{SMS_SRC_ADDR}","DID":"{SMS_DST_ADDR}","TEXT":"{SMS_TEXT}"}
* *Submit* to save changes to the HTTP IN trunk.

.. figure:: https://doc.didww.com/_images/6.png
  :figclass: align-center

  **Fig. 6.** Configure DIDWW SMS HTTP IN trunk.

**Step 7.** Send any test SMS message from your mobile device to the DIDWW DID number which the SMS trunk was previously configured for. If everything was done correctly you should see the values configured on DIDWW SMS trunk appear (Fig. 7). Click *Continue*.

.. figure:: https://doc.didww.com/_images/7.png
  :figclass: align-center

  **Fig. 7.** Testing Zapier webhook trigger.

**Step 8.** Next, we will be configuring an Action event after a successful trigger. This guide uses Google Sheets as an example. (Fig. 8). Click *Google Sheets* in the event selection menu.

.. figure:: https://doc.didww.com/_images/8.png
  :figclass: align-center

  **Fig. 8.** Selecting Action *Google Sheets*.

**Step 9.** Select *Create Spreadsheet Row* from the event selection dropdown list (Fig. 9).

.. figure:: https://doc.didww.com/_images/9.png
  :figclass: align-center

  **Fig. 9.** Selecting *Create Spreadsheet Row* event.

**Step 10.** Before moving to the next step, prepare a spreadsheet in Google Sheets with any relevant information, such as *Time*, *Source number*, *DID number*, *SMS text* (Fig. 10).

.. figure:: https://doc.didww.com/_images/10.png
  :figclass: align-center

  **Fig. 10.** Example of a Google Spreadsheet.

**Step 11.** Sign in to your *Google Sheets* account (Fig. 11), select it, and click *Continue* (Fig. 12).

.. figure:: https://doc.didww.com/_images/11.png
  :figclass: align-center

  **Fig. 11.** Sign in to *Google Sheets*.

.. figure:: https://doc.didww.com/_images/12.png
  :figclass: align-center

  **Fig. 12.** Select your *Google Sheets* account.

**Step 12.** Select the following in the *Set up Actions* menu (Fig.13):

* Drive – Google Drive location of the created spreadsheet
* Spreadsheet – spreadsheet which was created in step 10
* Worksheet – sheet of the spreadsheet
* Column Time – TIME placeholder
* Column Source number - SRC placeholder
* Column DID number -DID placeholder
* Column SMS text – TEXT placeholder

After selecting all the values click *Continue* (Fig. 13).

.. figure:: https://doc.didww.com/_images/13.png
  :figclass: align-center

  **Fig. 13.** Setting up action for Google Spreadsheet Row creation.

**Step 13.** Click *Test Action* button and after successful testing proceed to *Publish Zap* (Fig. 14).

.. figure:: https://doc.didww.com/_images/14.png
  :figclass: align-center

  **Fig. 14.** Publishing your Zap.

DIDWW Voice IN Call Events and Zapier Webhook
---------------------------------------------

DIDWW Voice IN Call Events allow you to receive events upon incoming calls to your existing DIDWW DID numbers. Together with Zapier Webhook it can be used to enable other applications to receive info about started, connected or ended calls made to a specific DID number. As an example, incoming voice calls can create an event or task in your favorite CRM or tasks management software. Please read more about DIDWW :ref:`Voice IN Call Events <did_call_events>`.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/>`_.
* `At least one DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`_.

**Configuring DIDWW Voice IN Call Events and Zapier Webhook**

As a use case example, we will configure DIDWW Voice IN Call Events for a DID number. All the details of a call to that number will be sent to and stored in a Google Sheet after the call ends. You may choose any other available Zapier App required for your idea/automation/task/project as an Action for DIDWW Voice IN Call Events.

**Step 1.** Create Zap in your Zapier account (Fig. 1).

.. figure:: https://doc.didww.com/_images/1.png
  :figclass: align-center

  **Fig. 1.** Creating a new Zap.

**Step 2.** Select *Webhooks by Zapier* as your trigger for the App event. (Fig. 2).

.. figure:: https://doc.didww.com/_images/2.png
  :figclass: align-center

  **Fig. 2.** Selecting *Webhooks by Zapier* trigger.

**Step 3.** Select *Catch Hook* in the event dropdown menu (Fig. 3).

.. figure:: https://doc.didww.com/_images/3.png
  :figclass: align-center

  **Fig. 3.** Selecting *Catch Hook*.

**Step 4.** Leave the *Child Key* field empty and click *Continue* (Fig. 4).

.. figure:: https://doc.didww.com/_images/4.png
  :figclass: align-center

  **Fig. 4.** *Child key* is left empty.

**Step 5.** A *webhook URL* will be generated for testing your trigger. Copy it for the next step (Fig. 5).

.. figure:: https://doc.didww.com/_images/5.png
  :figclass: align-center

  **Fig. 5.** Copy Zapier webhook URL.

**Step 6.** `Log in to your DIDWW account <https://my.didww.com/#/users/sign_in>`_ and navigate to section *APIs* -> *Call Events API* -> *Call Events* and then click *Configure* for Voice IN service (Fig. 6).

.. figure:: https://doc.didww.com/_images/6.png
  :figclass: align-center

  **Fig. 6.** Enabling and configuring DIDWW Voice IN Call Events.

**Step 7.** On the Voice IN Call Events configuration page (Fig. 7) add the Zapier *Webhook URL* address generated in step 5, disable GZIP compression, and click *Submit* to save the configuration.

.. figure:: https://doc.didww.com/_images/7.png
  :figclass: align-center

  **Fig. 7.** Add Zapier URL address and disable GZIP compression.

**Step 8.** Place a test call to any of your DIDWW DID numbers. Once a  webhook request is found, call data will appear in *Zapier Test trigger* form (Fig. 8).

DIDWW Voice IN Call Events sends three requests (incoming-call-start-event, incoming-call-connect-event, incoming-call-end-event). In the dropdown request selection menu you may choose ‘incoming-call-end-event’ which contains most of the data. Full details and all possible values of DIDWW Voice IN Call Events can be found `here <https://doc.didww.com/call-events/index.html>`__.

If trigger testing is successful, click *Continue*.

.. figure:: https://doc.didww.com/_images/8.png
  :figclass: align-center

  **Fig. 8.** Trigger test form.

**Step 9.** To execute action only at certain conditions, for example for calls to a specific DID after the call already ended, choose *Filter* in Zapier built-in actions list (Fig. 9).

.. figure:: https://doc.didww.com/_images/9.png
  :figclass: align-center

  **Fig. 9.** Selecting *Filter* action.

**Step 10.** As an example we will define that action will continue only if the call has ended and if the call came to a specified DID number (Fig. 10).

* In the first dropdown select: **Type**
* In the second dropdown select: **(Text) Exactly matches**
* In the third box enter text: **incoming-call-end-event**

Click **And** button to add a second condition.

* In the first dropdown select: **Attributes DID number**
* In the second dropdown select: **(Text) Exactly matches,**
* In the third box enter your existing DIDWW **DID number** (in full format with country code and without any other additional symbols).

.. figure:: https://doc.didww.com/_images/10.png
  :figclass: align-center

  **Fig. 10.** Action filter configuration.

**Step 11.** In the above example a call to your DID number will execute an action which will add a row in Google Sheets, therefore it is necessary to prepare a  Google Sheet with the following columns: Time, Duration, Source, DID, id (Fig. 11).

.. figure:: https://doc.didww.com/_images/11.png
  :figclass: align-center

  **Fig. 11.** Google Sheet with necessary columns.

**Step 12.** Select *Google Sheets* in the *Action* tab (Fig. 12).

.. figure:: https://doc.didww.com/_images/12.png
  :figclass: align-center

  **Fig. 12.** Selecting *Google Sheets* in the *Action* tab.

**Step 13.** Select *Create Spreadsheet Row* from the event selection dropdown list (Fig. 13) and click *Continue*.

.. figure:: https://doc.didww.com/_images/13.png
  :figclass: align-center

  **Fig. 13.** Selecting *Create Spreadsheet Row* event.

**Step 14.** Select the previously added Google Sheets account or add a new one and click *Continue* (Fig. 14).

.. figure:: https://doc.didww.com/_images/14.png
  :figclass: align-center

  **Fig. 14.** Selecting *Google Sheets* account.

**Step 15.** Select the following in the *Set up Actions* menu (Fig. 15):

* Drive – Google Drive location of the created spreadsheet
* Spreadsheet – spreadsheet which was created in step 10
* Worksheet – sheet of the spreadsheet
* Column Time – Attributes Time Start placeholder
* Column Duration – Attributes Duration placeholder
* Column Source - Attributes Src number placeholder
* Column DID - Attributes DID Number placeholder
* Column id – ID placeholder

Click *Continue* (Fig. 15).

.. figure:: https://doc.didww.com/_images/16.png
  :figclass: align-center

  **Fig. 15.** Setting up action for Google Spreadsheet Row creation.

**Step 16.** Click *Test & continue* (Fig. 16), after successful testing of spreadsheet row creation, publish your Zap.

.. figure:: https://doc.didww.com/_images/16.png
  :figclass: align-center

  **Fig. 16.** Testing the action.

**Step 17.** When your Zap is successfully published, at the end of each incoming call to your DIDWW DID number, Google Sheet will be updated with a new row containing call details (Fig. 17).

.. figure:: https://doc.didww.com/_images/17.png
  :figclass: align-center

  **Fig. 17.** Call details successfully added to Google Sheet.

DIDWW Voice OUT Call Events and Zapier Webhook
----------------------------------------------

DIDWW Voice OUT Call Events allows to receive events when outgoing calls are made via DIDWW outbound SIP trunk. Together with Zapier Webhook configuration it can be used with Apps available in Zapier platform, enabling other applications to receive events about started, connected, or ended calls.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/>`_.
* `At least one DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`_.
* `An active DIDWW outbound SIP trunk <https://doc.didww.com/voice/outbound-trunks/how-to-guides/create-outbound-trunk.html>`_.

**Configuring DIDWW Voice OUT Call Events and Zapier Webhook**

As a use case example, we will configure DIDWW Voice OUT Call Events for a DID number. After ending the outbound call, details of it will be stored in a Google Sheet. You may choose any other available Zapier App for your idea/automation/task/project as an action for DIDWW Voice OUT Call Events. As an example, outgoing voice calls can create events or tasks in your favorite CRM or task management software.

**Step 1.** Create Zap in your Zapier account (Fig. 1).

.. figure:: https://doc.didww.com/_images/1.png
  :figclass: align-center

  **Fig. 1.** Creating a new Zap.

**Step 2.** Select *Webhooks by Zapier* as your trigger for the App event. (Fig. 2).

.. figure:: https://doc.didww.com/_images/2.png
  :figclass: align-center

  **Fig. 2.** Trigger App *Webhook by Zapier* selection.

**Step 3.** Select *Catch Hook* in the event dropdown menu (Fig. 3).

.. figure:: https://doc.didww.com/_images/3.png
  :figclass: align-center

  **Fig. 3.** Selecting event type.

**Step 4.** Leave the *Child Key* field empty and click *Continue* (Fig. 4).

.. figure:: https://doc.didww.com/_images/4.png
  :figclass: align-center

  **Fig. 4.** *Child key* is left empty.

**Step 5.** A *webhook URL* will be generated for testing your trigger. Copy ir for the next step (Fig. 5) and click the *Test trigger* button.

.. figure:: https://doc.didww.com/_images/5.png
  :figclass: align-center

  **Fig. 5.** Copy Zapier webhook URL.

**Step 6.** In your DIDWW account navigate to menu section *APIs* -> *Call Events API* -> *Call Events* and then click *Configure* for Voice OUT service (Fig. 6).

.. figure:: https://doc.didww.com/_images/6.png
  :figclass: align-center

  **Fig. 6.** Enabling and configuring DIDWW Voice OUT Call Events.

Proceed with the following configuration (Fig. 7). Add Zapier Webhook URL address which was generated in step 5. Disable GZIP compression and click *Submit* to save the configuration.

.. figure:: https://doc.didww.com/_images/7.png
  :figclass: align-center

  **Fig. 7.** Add Zapier URL address and disable GZIP compression.

**Step 7.** Make a test call via your DIDWW outbound SIP trunk. You should see the webhook request and call data appear in Zapier *“Test trigger”* form (Fig. 8).

DIDWW Voice OUT Call Events sends three requests (*outbound-call-start-event*, *outbound-call-connect-event*, *outbound-call-end-event*). By selecting request A, B or C in the dropdown list you can choose the corresponding call data of start, connect, or call end events. Full details and all possible values of DIDWW Voice OUT Call Events can be found `here <https://doc.didww.com/call-events/termination-call-events.html>`_.

If trigger testing is successful, click *Continue*.

.. figure:: https://doc.didww.com/_images/8.png
  :figclass: align-center

  **Fig. 8.** Trigger test form.

**Step 8.** To execute actions only at certain conditions, i.e. for calls made with specific DID and after ending the call, choose *Filter* from the Zapier built-in actions list (Fig. 9).

.. figure:: https://doc.didww.com/_images/9.png
  :figclass: align-center

  **Fig. 9.** Selecting *Filter*.

**Step 9.** We will define that action will be executed only after the call has ended and if the call was made with a specified DID number (Fig. 10).

* In the first dropdown menu select: **Type**
* In the second dropdown menu: **(Text) Exactly matches**
* In the third text box enter: **outbound-call-end-event**

Click **And** button to add a second condition.

* In the first dropdown menu select: **Attributes Src number**
* In the second dropdown menu select: **(Text) Exactly matches,**
* In the third text box enter your existing DIDWW phone number: **DID number** (in full format with a country code and without any additional symbols).

.. figure:: https://doc.didww.com/_images/10.png
  :figclass: align-center

  **Fig. 10.** Action filter configuration.

**Step 10.** Prepare a Google Sheet with the following columns: *Time*, *Duration*, *Source*, *Destination*, *Trunk*, *Rate* (Fig. 11). The configured call event will add a row in the sheet each time it is executed.

.. figure:: https://doc.didww.com/_images/11.png
  :figclass: align-center

  **Fig. 11.** Google Sheet with the necessary columns.

**Step 11.** In the *Action* tab select *Google Sheets* (Fig. 12).

.. figure:: https://doc.didww.com/_images/12.png
  :figclass: align-center

  **Fig. 12.** Selecting *Google Sheets* in the Action tab.

**Step 12.** Select *Create Spreadsheet Row* from the event selection dropdown list (Fig. 13) and click *Continue*.

.. figure:: https://doc.didww.com/_images/13.png
  :figclass: align-center

  **Fig. 13.** Selecting action event.

**Step 13.** Select the previously added Google Sheets account or add a new one and click *Continue* (Fig. 14).

.. figure:: https://doc.didww.com/_images/14.png
  :figclass: align-center

  **Fig. 14.** Selecting *Google Sheets* account.

**Step 14.** Select the following in the *Set up action* fields:

* Drive – Google Drive location of the created spreadsheet
* Spreadsheet – spreadsheet which was created in step 10
* Worksheet – sheet of the spreadsheet
* Column Time start – Attributes Time Start placeholder
* Column Duration – Attributes Duration placeholder
* Column Source - Attributes Src Number placeholder
* Column Destination - Attributes Dst Number placeholder
* Column Trunk – Attributes Trunk Name placeholder
* Column Rate – Attributes Rate placeholder

Click *Continue* (Fig. 15).

.. figure:: https://doc.didww.com/_images/15.png
  :figclass: align-center

  **Fig. 15.** Setting up action for Google Spreadsheet Row creation.

**Step 15.** Click *Test & continue* (Fig. 16), after successful testing of spreadsheet row creation, publish your Zap.

.. figure:: https://doc.didww.com/_images/16.png
  :figclass: align-center

  **Fig. 16.** Testing and publishing Zap.

**Step 16.**  At the end of each outgoing call via your DIDWW outbound sip trunk with specified DID number, Google Sheet will be updated with a new row containing call details (Fig. 17).

.. figure:: https://doc.didww.com/_images/17.png
  :figclass: align-center

  **Fig. 17.** Call details successfully added to Google Sheet.

Templates
---------

Here you can find templates that might help you with starting your integration:

.. raw:: html

  <script type="module" src="https://cdn.zapier.com/packages/partner-sdk/v0/zapier-elements/zapier-elements.esm.js"></script>
  <link rel="stylesheet" href="https://cdn.zapier.com/packages/partner-sdk/v0/zapier-elements/zapier-elements.css"/>

  <zapier-zap-templates
  apps="didww-sms-out,-twilio"
  create-without-template="hide"
  limit="2"
  use-this-zap="hide"
  theme="light"
  <br>
  </zapier-zap-templates>
  <br>


.. _pabbly:

Pabbly
======

Introduction
------------

Pabbly allows to interact between popular applications and empowers you to automate your tasks across many different apps. 
Creates automated workflows and tasks to use different web applications together. It is often described as a translator between web APIs,
helping to increase worker productivity by saving time through automation of recurring tasks, and business processes such as lead management.
Through an interface in which users can set up workflow rules to determine how its automations function, it orchestrates flow of data between
tools and online services that wouldn't otherwise communicate with one another

DIDWW SMS OUT App enabled by Pabbly
-----------------------------------

DIDWW SMS OUT App allows you to send SMS messages from your existing DIDWW SMS-enabled DID number to any other SMS enabled destination number. It can be used with apps from Pabbly platform, enabling non-sms capable applications to send SMS messages. For example, an SMS message notification may be triggered by a certain action on your CRM or other task management software. Please `read more <https://doc.didww.com/services/outgoing-sms/index.html>`__ about SMS OUT service at DIDWW

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`__.
* `At least one SMS enabled DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`__.
* `An SMS HTTP OUT Trunk at DIDWW (credentials of which will be used later in this guide) <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-out.html>`__.

**Configuring DIDWW SMS OUT App**

As a use case example, we will connect Google form to send SMS messages upon form submission. Answers submitted to Google form will be sent via SMS message to the configured phone number.

.. _1_note:

**Step 1.** Create a Google form with two short answer type questions:  *SMS Destination Number, and SMS Text* (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig_1.png
  :figclass: align-center

  **Fig. 1.** Google form.

**Step 2.** Create a “Workflow” in your Pabbly account (Fig. 2)

.. figure:: https://doc.didww.com/_images/fig_2.png
  :figclass: align-center

  **Fig. 2.** Creating a new Workflow.

**Step 3.** Enter any friendly name for your Workflow, such as “Google Forms and DIDWW SMS Out” and click “Create”. (Fig. 3)

.. figure:: https://doc.didww.com/_images/fig_3.png
  :figclass: align-center

  **Fig. 3.** Setting a Name of your Workflow

**Step 4.** Under the “Choose App” field search for “Google Forms” and select it. (Fig. 4).

.. figure:: https://doc.didww.com/_images/fig_4.png
  :figclass: align-center

  **Fig. 4.** Selecting Google Forms App

**Step 5.** Select “New Response Received” as your Trigger Event (Fig. 5).

.. figure:: https://doc.didww.com/_images/fig_5.png
  :figclass: align-center

  **Fig. 5.** Selecting the Trigger Event
  
.. _6_note:

**Step 6.** Copy the “Webhook URL” which is automatically generated by Pabbly. (Fig. 7) The URL will be used during Google Form configuration setup in :ref:`Step 13<13_note>`     .

If you are aware of the Google Form setup process feel free to continue from :ref:`Step 15<15_note>` .

.. figure:: https://doc.didww.com/_images/fig_6.png
  :figclass: align-center

  **Fig. 6.** Pablly Webhook URL for Google Forms
  
.. _7_note:

**Step 7.**  Go to the Google Form created on :ref:`Step 1<1_note>` . and set both fields as “Required” for the trigger to function properly. (Fig. 7).

.. figure:: https://doc.didww.com/_images/fig_7.png
  :figclass: align-center

  **Fig. 7.** Setting Google Form answers as “Required”

**Step 8.** Switch to the “Responses Tab” and  click on the “Link to Sheets” icon, or click “View in Sheets” if you already have an assigned sheet for the Google Form (Fig. 8).

.. figure:: https://doc.didww.com/_images/fig_8.png
  :figclass: align-center

  **Fig. 8.** Assigning sheets in the Google Form 

**Step 9.** On the assigned sheet navigate to “Extensions” > “Add-ons” > “Get add-ons” (Fig. 9).

.. figure:: https://doc.didww.com/_images/fig_9.png
  :figclass: align-center

  **Fig. 9.** Google Form accessing Add-ons.

**Step 10.** In the "Google Workspace Marketplace," search for "Pabbly Connect Webhooks." (Fig. 10).

.. figure:: https://doc.didww.com/_images/fig_10.png
  :figclass: align-center

  **Fig. 10.** Pabbly Connect Webhook addon

**Step 11.** Click “Pabbly Connect Webhooks”, select  “Install > Continue” & “Allow all permissions” for the app  (Fig. 11).

.. figure:: https://doc.didww.com/_images/fig_11.png
  :figclass: align-center

  **Fig. 11.** Pabbly Connect Webhook app installation

**Step 12.** Refresh the sheet, Navigate to “Add-ons” > “Pabbly Connect Webhooks” dropdown menu, click “Initial setup” (Fig. 12).

.. figure:: https://doc.didww.com/_images/fig_12.png
  :figclass: align-center

  **Fig. 12.** Google Form Pabbly Connect initial setup.
  
.. _13_note:

**Step 13.** Paste the Pabbly Webhook URL copied from :ref:`Step 6<6_note>` to the “Webhook URL” field and enter your trigger column's last letter (example B) (e.g “SMS text” from :ref:`Step 7<7_note>`) under the “Trigger Column” field (Fig. 13).

.. figure:: https://doc.didww.com/_images/fig_13.png
  :figclass: align-center

  **Fig. 13.** Google Form Webhook Trigger.

**Step 14.** On the Google sheet navigate to “Extensions” > “Pabbly Connect Webhooks” and enable “Send on Event” to send the data (Fig. 14).

.. figure:: https://doc.didww.com/_images/fig_14.png
  :figclass: align-center

  **Fig. 14.** Enabling “Send On Event” in Google sheets
  
  .. _15_note:
  
**Step 15.** Click “Add Action Step” to add the next application for the Workflow process (Fig. 15).

.. figure:: https://doc.didww.com/_images/fig_15.png
  :figclass: align-center

  **Fig. 15.** Add Action Step
  
**Step 16.** Search for “DIDWW SMS OUT” app and select it (Fig. 16).

.. figure:: https://doc.didww.com/_images/fig_16.png
  :figclass: align-center

  **Fig. 16.** Selecting the DIDWW SMS OUT app
  
**Step 17.** Search for “Send SMS Out” under the “Action Event” dropdown menu and click “Connect” (Fig. 17)

.. figure:: https://doc.didww.com/_images/fig_17.png
  :figclass: align-center

  **Fig. 17.** Selecting the “Send SMS Out”  action event

**Step 18.** Select “Add New connection”and enter any friendly name in the “New Connection Name” field.  Your Username and Password fields must contain the credentials from the `DIDWW SMS OUT Trunk <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-out.html>`__ on your DIDWW account.(Fig. 18). Click Save.

.. figure:: https://doc.didww.com/_images/fig_18.png
  :figclass: align-center

  **Fig. 18.** Connecting the DIDWW SMS OUT trunk to Pabbly App.

**Step 19.** In the configuration menu (Fig. 19) you can add static values or use placeholders of previously created Google Form (Fig. 1). 

* For the “Source Number” add a static phone number. This should be an `SMS enabled DID number <https://www.didww.com/coverage-and-prices/coverage>`__ existing on your DIDWW account and added to the “SMS HTTP OUT trunk” `source addresses list <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-out.html#source-address-settings>`__. The accepted number formats are: E.164 or +E.164 (Country Code + Area Code + Number).
* For the “Destination Number” select the “SMS Destination Number” the dropdown menu. The accepted number formats are: E.164 or +E.164 (Country Code + Area Code + Number).
* For the “SMS Content Text” select the “SMS Text” from the dropdown menu.

After all fields have been selected click “Save” to save changes or alternatively click “Save & Send Test Request” to check request response on site.

.. figure:: https://doc.didww.com/_images/fig_19.png
  :figclass: align-center

  **Fig. 19.** Configuring action values

.. Attention::

 For fields “SMS destination number” and “SMS Content text” to appear from drop down menu list, in Google sheets, trigger option “Send all data” from Pabbly extensions settings (Extensions → Pabbly Connect Webhooks → Send all data) (Fig. 19.1.)

.. figure:: https://doc.didww.com/_images/fig_19_1.png
  :figclass: align-center

  **Fig. 19.1.** Populating drop down menu.
  
**Step 20.** In case “Save & Send Test Request” is selected during Step 11. Pabbly platform will show the received request response (Fig. 20)

.. figure:: https://doc.didww.com/_images/fig_20.png
  :figclass: align-center

  **Fig. 20.** Test Request response data
  
**Step 21.** Open your previously created Google Form, enter “SMS Destination Number”, “SMS Text” and click “Submit” (Fig. 21). An SMS message should be sent to the specified destination number with the entered text in it. If something went wrong and the SMS did not reach the destination number, you can check the `Outbound SMS Log <https://doc.didww.com/logs-analytics/sms-logs/outbound-logs.html>`__ on your DIDWW account or in the Pabbly History logs.

.. figure:: https://doc.didww.com/_images/fig_21.png
  :figclass: align-center

  **Fig. 21.** Submitting Google Form
  

DIDWW SMS HTTP IN and Pabbly Webhook
------------------------------------

DIDWW SMS IN service allows you to receive SMS messages to your existing DIDWW SMS enabled DID numbers. Pabbly Webhook allows DIDWW SMS IN service to be used with Apps available on Pabbly platform, enabling non-sms capable applications to receive SMS messages. For example, an incoming SMS message can create an event or task in your CRM or other task management software. Please read more about :ref:`DIDWW SMS IN service <userpanel_sms>`.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`__.
* `At least one SMS enabled DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`__.
* `An SMS HTTP IN Trunk at DIDWW <https://doc.didww.com/sms/sms-trunks/create-sms-http-trunk-in.html>`__.
* `SMS HTTP IN Trunk assigned to your SMS enabled DID <https://doc.didww.com/sms/sms-trunks/assigning-an-sms-trunk.html>`__.

**Configuring DIDWW SMS HTTP IN and Pabbly Webhook**

As a use case example, we will connect a DIDWW SMS-enabled DID number so that  incoming messages will be stored in Google Sheets. You may choose any other available Pabbly App required for your idea/automation/task/project as a *Trigger* for incoming DIDWW SMS messages.

**Step 1.** Create a “Workflow” in your Pabbly account (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig_1.png
  :figclass: align-center

  **Fig. 1.** Creating a new Workflow.

**Step 2.** Enter any friendly name for your Workflow, such as “DIDWW SMS IN And Google Sheets” and click “Create”. (Fig. 2)

.. figure:: https://doc.didww.com/_images/fig_2.png
  :figclass: align-center

  **Fig. 2.** Setting a name for your Workflow

**Step 3** Under the “Choose App” field search for *“DIDWW”* and select it. (Fig. 3)

.. figure:: https://doc.didww.com/_images/fig_3.png
  :figclass: align-center

  **Fig. 3.** Selecting “DIDWW” app

**Step 4** Select *“Receive SMS IN”* as your Trigger Event (Fig.4).

.. figure:: https://doc.didww.com/_images/fig_4.png
  :figclass: align-center

  **Fig. 4.** Selecting “Receive SMS IN” Trigger Event

**Step 5** Copy the “Webhook URL” which is automatically generated by Pabbly. (Fig. 5) The URL will be used during DIDWW SMS IN trunk configuration setup in STEP 6.

.. figure:: https://doc.didww.com/_images/fig_5.png
  :figclass: align-center

  **Fig. 5.** Copying Pabbly Webhook URL

**Step 6** On your DIDWW account create or edit the previously created *SMS HTTP IN* trunk (Fig. 6). Make the following trunk configurations:

* Friendly name - any friendly name to identify your trunk.
* HTTP method – select POST.
* Request URL – paste Webhook URL which was copied in **Step 5**.
* Body type - select JSON.
* Request body – add the preferred placeholders. Example:

     ::

        {
        "Date Time" : "{SMS_TIME}",
        "Source Number" : "{SMS_SRC_ADDR}",
        "DID number" : "{SMS_DST_ADDR}",
        "Text" : "{SMS_TEXT}",
        "Text Encoded" : "{SMS_TEXT_BASE64_ENCODED}"
        }

* *Submit* to save changes made to the HTTP IN trunk.

.. figure:: https://doc.didww.com/_images/fig_6.png
  :figclass: align-center

  **Fig. 6.** Configure DIDWW SMS HTTP IN trunk

**Step 7** Send a test SMS message from your mobile device to the DIDWW number for which the SMS trunk has been previously configured. If everything was done correctly you should see the values configured on the DIDWW SMS trunk appear (Fig. 7). Click *“Continue”*.

.. figure:: https://doc.didww.com/_images/fig_7.png
  :figclass: align-center

  **Fig. 7.** Testing Pabbly webhook trigger

**Step 8** Next, we will  configure an Action event after a successful trigger. This guide uses Google Sheets as an example. Under the “Choose App” field search for *“Google Sheets”* and select it (Fig.8).

.. figure:: https://doc.didww.com/_images/fig_8.png
  :figclass: align-center

  **Fig. 8.** Selecting *Google Sheets* App

**Step 9** Select *“Add New Row”* from the action event selection dropdown list (Fig. 9).

.. figure:: https://doc.didww.com/_images/fig_9.png
  :figclass: align-center

  **Fig. 9.** Selecting *“Add New Row”* action event

**Step 10** Click “Connect”, choose “Add New Connection” or “Select Existing connection” and continue to ”Sign in with Google” (Fig 10.)

.. figure:: https://doc.didww.com/_images/fig_10.png
  :figclass: align-center

  **Fig. 10.** Creating a *“Google Sheets”* connection

**Step 11** Prepare a spreadsheet in Google Sheets with any relevant information. For our example we will be using Google Sheet file named “My Received Inbound SMS”, sheet named “Sheet1”
and column names as “Datetime”, “Source number”, “Destination number”, “Text and Encoded Text” (Fig. 11).

.. figure:: https://doc.didww.com/_images/fig_11.png
  :figclass: align-center

  **Fig. 11.** Example of a “Google Spreadsheet”

**Step 12** Once the “Google Sheets” file is ready, select the  appropriate fields on Pabbly:

* **Select Spreadsheet**: Choose the Google Sheets file where you wish to store the received SMS messages. For this example, the file is named "My Received Inbound SMS."

* **Select Sheet**: Pick the specific sheet within the Google Sheets file to record the data. In this instance, opt for "Sheet1."

* **DateTime**: In this field, set the column that will capture the date and time of each inbound SMS. From the "1. DIDWW SMS IN: Receive SMS in" dropdown list, select "Date Time."

* **Source Number**: Specify the column that will store the source phone numbers of the received messages. Select "Source Number" from the "1. DIDWW SMS IN: Receive SMS in" dropdown list.

* **Destination Number**: Designate the column that will keep track of the destination numbers for each SMS. Choose "DID Number" from the "1. DIDWW SMS IN: Receive SMS in" dropdown list.

* **Text**: Identify the column that will record the content of each received SMS. From the "1. DIDWW SMS IN: Receive SMS in" dropdown list, opt for "Text."

* **Encoded Text**: Define the column where the encoded version of each SMS text will be stored. Select "Text Encoded" from the "1. DIDWW SMS IN: Receive SMS in" dropdown list.

.. figure:: https://doc.didww.com/_images/fig_12.png
  :figclass: align-center

  **Fig. 12.** Assigning fields on “Google Sheets” app from “DIDWW SMS IN” app

**Step 13** Click "Save & Send Test Request" (Fig. 13) to review the data being transferred from Pabbly to the Google Sheets file and to check for any errors (Fig. 14). During this Test Request, the Google Sheets file will receive and store the data (Fig. 15). Alternatively, you can simply click "Save" if you prefer to bypass the testing request.

.. figure:: https://doc.didww.com/_images/fig_13.png
  :figclass: align-center

  **Fig. 13.** Testing setup by clicking “Save & Send Test Request”

.. figure:: https://doc.didww.com/_images/fig_14.png
  :figclass: align-center

  **Fig. 14.** Data passed from Pabbly to Google Spreadsheet

.. figure:: https://doc.didww.com/_images/fig_15.png
  :figclass: align-center

  **Fig. 15.** Data passed and stored from Pabbly to Google Spreadsheet file

DIDWW Voice IN Call Events and Pabbly Webhook
---------------------------------------------

The DIDWW Voice IN Call Events enable you to receive event notifications for incoming calls to your existing DIDWW DID numbers. Used in conjunction with Pabbly Webhook, this feature allows you to integrate other applications to receive information about calls that are initiated, connected, or terminated to a specific DID number. For instance, you can set it up so that incoming voice calls trigger an event or task within your preferred CRM or task management software. To learn more, `read  <https://doc.didww.com/call-events/did-call-events.html>`__ about DIDWW Voice IN Call Events.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`__.
* `At least one SMS enabled DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`__.

**Configuring DIDWW Voice IN Call Events and Pabbly Webhook**

In this use case example, we will set up DIDWW Voice IN Call Events for a specific DID number. When a call is made to that number, the details will be forwarded to HubSpot CRM, where a ticket will be automatically created with the relevant data. While we are using HubSpot CRM for this example, you have the flexibility to choose any other Pabbly App that suits your specific needs, idea, automation task, or project as an Action for DIDWW Voice IN Call Events.

**Step 1** Create a “Workflow” in your Pabbly account (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig_1.png
  :figclass: align-center

  **Fig. 1.** Creating a new Workflow

**Step 2** Enter any friendly name for your Workflow, such as “DIDWW VOICE IN Call Events And HubSpot CRM” and click “Create”. (Fig. 2)

.. figure:: https://doc.didww.com/_images/fig_2.png
  :figclass: align-center

  **Fig. 2.** Setting a Name of your Workflow

**Step 3** Under the “Choose App” field search for “DIDWW” and select it. (Fig. 3)

.. figure:: https://doc.didww.com/_images/fig_3.png
  :figclass: align-center

  **Fig. 3.** Selecting “DIDWW” app

**Step 4** Select “Receive Voice IN Call Event” as your Trigger Event (Fig. 4).

.. figure:: https://doc.didww.com/_images/fig_4.png
  :figclass: align-center

  **Fig. 4.** Selecting “Receive Voice IN Call Event” Trigger Event

**Step 5** Copy the "Webhook URL" that is automatically generated by Pabbly (see Fig. 5). This URL will be utilized in STEP 6 for setting up DIDWW Voice IN Call Events configuration.

.. figure:: https://doc.didww.com/_images/fig_5.png
  :figclass: align-center

  **Fig. 5.** Copy Pabbly Webhook URL

**Step 6** `Log in to your DIDWW account <https://my.didww.com/#/users/sign_in>`__ and navigate to section *APIs* -> *Call Events API* -> *Call Events* and then click *Configure* for Voice IN service (Fig. 6).

.. figure:: https://doc.didww.com/_images/fig_6.png
  :figclass: align-center

  **Fig. 6.** Enabling and configuring DIDWW Voice IN Call Events.

**Step 7** On the Voice IN Call Events configuration page (Fig. 7), input the Pabbly Webhook URL address that you generated in step 5. Make sure to disable GZIP compression, and then click "Submit" to save your settings.

.. figure:: https://doc.didww.com/_images/fig_7.png
  :figclass: align-center

  **Fig. 7.** Add Pabbly URL address and disable GZIP compression.

**Step 8** Place a test call to any of your DIDWW DID numbers. Once a webhook request is detected, the call data will be displayed in the Pabbly *Test Trigger* form (Fig. 8).

.. figure:: https://doc.didww.com/_images/fig_8.png
  :figclass: align-center

  **Fig. 8.** Captured test Webhook response

**Step 9** DIDWW Voice IN Call Events send three requests (incoming-call-start-event, incoming-call-connect-event, incoming-call-end-event). Full details and all possible values of DIDWW Voice IN Call Events can be found `here <https://doc.didww.com/call-events/did-call-events.html>`__. For our specific scenario we will focus on creating HubSpot Tickets using the “incoming-call-start-event”.

Click the “Add Action Step” button, search for “Filter” and select it (Fig. 9).

.. figure:: https://doc.didww.com/_images/fig_9.png
  :figclass: align-center

  **Fig. 9.** Selecting “Filter” as Action Step

**Step 10** Use Case: "Create HubSpot Ticket for All Calls (Our Scenario)"

* In the first dropdown labeled "Select Label," choose **"Type"**
* In the second dropdown labeled "Filter Type," choose **"Equal to"**
* In the third box labeled "Value," enter the text **"incoming-call-start-event"**

Click the **“Save & Send Test Request”** button to Save configuration and review the received response (Fig. 10).

.. figure:: https://doc.didww.com/_images/fig_10.png
  :figclass: align-center

  **Fig. 10.** Use case: “Create HubSpot Ticket for all calls (our scenario)” action “Filter” configuration

Use Case: "Create HubSpot Ticket for Only Answered Calls"

In the first dropdown labeled "Select Label," choose **"Type"**
In the second dropdown labeled "Filter Type," choose **"Equal to"**
In the third box labeled "Value," enter the text **"incoming-call-connect-event"**

Click the **“Save & Send Test Request”** button to Save configuration and review the received response (Fig. 11).

.. figure:: https://doc.didww.com/_images/fig_11.png
  :figclass: align-center

  **Fig. 11.** Use case: “Create HubSpot Ticket for only answered calls” action “Filter” configuration

Use Case: "Create HubSpot Ticket for Only Not Answered/Missed Calls"

In the first dropdown labeled "Select Label," choose **"Type"**
In the second dropdown labeled "Filter Type," choose **"Equal to"**
In the third box labeled "Value," enter the text **"incoming-call-end-event"**

Click the “+” (plus) sign to add additional filtering condition:

In the first dropdown labeled "Select Label," choose **"Type"**
In the second dropdown labeled "Filter Type," choose **"Equal to"**
In the third box labeled "Value," enter the text **"0"**

Click the **“Save & Send Test Request”** button to Save configuration and review the received response (Fig. 12).

Click the “Add Action Step” button, search for “HubSpot” and select it (Fig. 13).

.. figure:: https://doc.didww.com/_images/fig_12.png
  :figclass: align-center

  **Fig. 11.** Use case: “Create HubSpot Ticket for only answered calls” action “Filter” configuration

**Step 10** Click the “Add Action Step” button, search for “HubSpot” and select it (Fig. 13).

.. figure:: https://doc.didww.com/_images/fig_13.png
  :figclass: align-center

  **Fig. 13.** Selecting “HubSpot CRM” app.

**Step 12** Expand the “Action Event” dropdown list and select “Create a Ticket” event (Fig. 14). Click “Connect”.

.. figure:: https://doc.didww.com/_images/fig_14.png
  :figclass: align-center

  **Fig. 14.**  Selecting “Create a Ticket” action event

**Step 13** Select “Add New Connection”, enter New connection name, for example “HubSpot CRM #1” and click “Connect With HubSpot CRM” button (Fig. 15).

.. figure:: https://doc.didww.com/_images/fig_15.png
  :figclass: align-center

  **Fig. 15.** Creating a “HubSpot CRM” connection

**Step 14** *Please note: Your company's HubSpot CRM internal setup and workflow configuration may differ from the scenario we have used in this example.*

To create tickets on Hubspot CRM enter the following data (Fig. 16 and Fig. 17):

* Close Date: <empty>;
* Create Date: Select it, then expand "1. DIDWW: Receive Voice IN Call Event" and choose "1. Attributes Time Start";
* Business Units: <empty>;
* File Upload: <empty>;
* Pipeline: 0 (In the HubSpot CRM used for this scenario, this stands for "Support Pipeline");
* Ticket Status: 1 (In the HubSpot CRM used for this scenario, this stands for "New");
* Resolution: None;
* Category: "General Inquiry";
* Priority: "Medium";
* Ticket Name: "Call From <expand '1. DIDWW: Receive Voice IN Call Event' and select '1. Attributes SRC Number'> At <expand '1. DIDWW: Receive Voice IN Call Event' and select '1. Attributes Time Start'>";
* Ticket Description: "This ticket is automatically created for an incoming voice call.
* Received at: <expand '1. DIDWW: Receive Voice IN Call Event and select '1. Attributes Time Start'>
* From source number: <expand '1.DIDWW: Receive Voice IN Call Event' and select '1. Attributes Src Number'>
* To destination number: <expand '1. DIDWW: Receive Voice IN Call Event’ and select '1. Attributes Did Number'>"
* Source: "Phone";
* Ticket Owner: <empty>;

Click  *“Save”* to save changes or alternatively click *“Save & Send Test Request”* to check request response on site.

.. figure:: https://doc.didww.com/_images/fig_16.png
  :figclass: align-center

  **Fig. 16.** Configure Hubspot CRM app “Create a Ticket”  fields Part 1

.. figure:: https://doc.didww.com/_images/fig_17.png
  :figclass: align-center

  **Fig. 17.** Configure Hubspot CRM create Ticket fields Part 2

**Step 15** Place a test call to your DIDWW DID number. In your HubSpot CRM, a new ticket will be automatically generated, capturing the details of the incoming voice call (Fig. 18).

.. figure:: https://doc.didww.com/_images/fig_18.png
  :figclass: align-center

  **Fig. 18.** HubSpot Ticket created for Voice IN DIDWW DID call event via Pabbly

DIDWW Voice OUT Call Events and Pabbly Webhook
----------------------------------------------

DIDWW Voice OUT Call Events allow you to receive notifications when outgoing calls are made via a DIDWW outbound SIP trunk. When configured with a Pabbly Webhook, this feature can integrate with apps available on the Pabbly platform, enabling other applications to receive real-time updates about call statuses, including when calls are started, connected, or ended.

**Getting started**

What you need to get started:

* `An account at DIDWW <https://my.didww.com/users/sign_up>`__.
* `At least one DID number in your DIDWW account <https://doc.didww.com/phone-numbers/buy-numbers/index.html>`__.
* `An active DIDWW outbound SIP trunk <https://doc.didww.com/voice/outbound-trunks/how-to-guides/create-outbound-trunk.html>`__.

**Configuring DIDWW Voice OUT Call Events and Pabbly Webhook**

As a use case example, we will set up DIDWW Voice OUT Call Events for a specific DID number. After each outbound call is completed, its details will be automatically recorded in a Google Sheet. While we are using Google Sheets in this example, you have the flexibility to choose any other app available on the Pabbly platform to suit your specific idea, automation, task, or project. For instance, outgoing voice calls could automatically trigger events or tasks in your preferred CRM or task management software.

**Step 1** Create a “Workflow” in your Pabbly account (Fig. 1).

.. figure:: https://doc.didww.com/_images/fig_1.png
  :figclass: align-center

  **Fig. 1.** Creating a new Workflow

**Step 2** Enter any friendly name for your Workflow, such as “DIDWW VOICE OUT Call Events And Google Sheets” and click “Create”. (Fig. 2)

.. figure:: https://doc.didww.com/_images/fig_2.png
  :figclass: align-center

  **Fig. 2.** Setting a Name of your Workflow

**Step 3** Under the “Choose App” field search for *“DIDWW”* and select it. (Fig. 3)

.. figure:: https://doc.didww.com/_images/fig_3.png
  :figclass: align-center

  **Fig. 3.** Selecting “DIDWW” app

**Step 4** Select “Voice Out  Call Events” as your Trigger Event (Fig. 4).

.. figure:: https://doc.didww.com/_images/fig_4.png
  :figclass: align-center

  **Fig. 4.** Selecting “Receive Voice Out Event” Trigger Event

**Step 5** Copy the "Webhook URL" that is automatically generated by Pabbly (Fig. 5). This URL will be used in STEP 6 for configuring DIDWW Voice OUT Call Events.

.. figure:: https://doc.didww.com/_images/fig_5.png
  :figclass: align-center

  **Fig. 5.** Copy Pabbly webhook URL

**Step 6** In your DIDWW account navigate to menu section *APIs* -> *Call Events API* -> *Call Events* and then click *Configure* for Voice OUT service (Fig. 6).

.. figure:: https://doc.didww.com/_images/fig_6.png
  :figclass: align-center

  **Fig. 6.** Enabling and configuring “DIDWW Voice OUT Call Events”

**Step 7** On the Voice OUT Call Events configuration page (Fig. 7), enter the Pabbly Webhook URL that was generated in Step 5. Make sure to disable GZIP compression, and then click "Submit" to save your settings.

.. figure:: https://doc.didww.com/_images/fig_7.png
  :figclass: align-center

  **Fig. 7.** Add Pabbly URL address and disable GZIP compression

**Step 8** Make a test call using your DIDWW outbound SIP trunk. The webhook request and associated call data should then appear in the Pabbly "Test Trigger" form (Fig. 8).

.. figure:: https://doc.didww.com/_images/fig_8.png
  :figclass: align-center

  **Fig. 8.** Captured test Webhook response

**Step 8.** Make a test call using your DIDWW outbound SIP trunk. The webhook request and associated call data should then appear in the Pabbly "Test Trigger" form (Fig. 8).

.. figure:: https://doc.didww.com/_images/fig_8.png
  :figclass: align-center

  **Fig. 8.** Captured test Webhook response

**Step 9** DIDWW Voice OUT Call Events sends three requests (outbound-call-start-event, outbound-call-connect-event, outbound-call-end-event). Full details and all possible values of DIDWW Voice OUT Call Events can be found `here <https://doc.didww.com/call-events/termination-call-events.html>`__. For our scenario we will focus on adding a new row to Google Sheet using “outbound-call-end-event”.

Click the “Add Action Step” button, search for “Filter” and select it (Fig. 9).

.. figure:: https://doc.didww.com/_images/fig_9.png
  :figclass: align-center

  **Fig. 9.** Selecting “Filter” as Action Step

**Step 9** Use case: “Create Google Sheet record for calls longer than 100 seconds OR calls that are charged at a rate higher than 0.10 (our scenario)”.

* In the first dropdown labeled “Select Label” select: **Type**
* In the second dropdown labeled “Filter Type” select: **Equal to**
* In the third box labeled “Value” enter text: **outbound-call-end-event**

Click “+” (plus) sign to add an additional filtering condition:

* In the first dropdown labeled “Select Label” select: **Attribute Duration**
* In the second dropdown labeled “Filter Type” select: **Greater than**
* In the third box labeled “Value” enter text: **100**

Click “ + OR Condition” button:

* In the first dropdown labeled “Select Label” select: **Type**
* In the second dropdown labeled “Filter Type” select: **Equal to**
* In the third box labeled “Value” enter text: **outbound-call-end-event**

Click “+” (plus) sign to add an additional filtering condition:

* In the first dropdown labeled “Select Label” select: **Attribute Rate**
* In the second dropdown labeled “Filter Type” select: **Greater than**
* In the third box labeled “Value” enter text: **0.1**

Click the **“Save & Send Test Request”** button to Save the configuration and review the received response (Fig. 10).

.. figure:: https://doc.didww.com/_images/fig_10.png
  :figclass: align-center

  **Fig. 10.** Use case: “Create Google Sheet record for calls longer than 100 seconds OR calls that are charged at a rate higher than 0.10 (our scenario)” action “Filter” configuration

Use case: "Create a Google Sheet record for only unanswered/missed calls:

* In the first dropdown, labeled "Select Label," choose: **Type**
* In the second dropdown, labeled "Filter Type," select: **Equal to**
* In the third box, labeled "Value," enter the text: **outbound-call-end-event**

Click the "+" (plus) sign to add an additional filtering condition:

* In the first dropdown, labeled "Select Label," **choose: Type**
* In the second dropdown, labeled "Filter Type," select: **Equal to**
* In the third box, labeled "Value," enter the text: **0**.

Click the **“Save & Send Test Request”** button to Save the configuration and review the received response (Fig. 11).

.. figure:: https://doc.didww.com/_images/fig_11.png
  :figclass: align-center

  **Fig. 11.** Use case: “Create Google Sheet record for only  unanswered/missed calls” action “Filter” configuration

**Step 11.** Click the “Add Action Step” button, search for “Google Sheets” and select it (Fig. 12).

.. figure:: https://doc.didww.com/_images/fig_12.png
  :figclass: align-center

  **Fig. 12.** Selecting “Google Sheets” app

**Step 12.** Select “Add New Row” from the action event dropdown menu (Fig. 13).

.. figure:: https://doc.didww.com/_images/fig_13.png
  :figclass: align-center

  **Fig. 12.** Selecting “Add New Row” action event

**Step 13.** Click “Connect”, choose “Add New Connection” or “Select Existing connection” and click ”Sign in with Google” (Fig 14.)

.. figure:: https://doc.didww.com/_images/fig_14.png
  :figclass: align-center

  **Fig. 14.** Creating a “Google Sheets” connection

**Step 14.** Prepare a spreadsheet in Google Sheets with all relevant information. For our example we will be using a Google Sheet file named “Voice OUT Events CDRs”, sheet named “Sheet1”
with  column names: “DateTime”, “Source number”, “Destination number”, “Duration”, “Rate”  (Fig. 15).

.. figure:: https://doc.didww.com/_images/fig_15.png
  :figclass: align-center

  **Fig. 15.** Example of a “Google Spreadsheet”

**Step 15.** Once your "Google Sheets" file is set up with all the required fields from Step 14, configure the corresponding fields on the Pabbly side to match your Google Sheets as follows:

* **Select Spreadsheet:** Choose the Google Sheets file to use; in our case, it's "Voice OUT Events CDRs”;
* **Select Sheet:** Choose the specific sheet within the Google Sheets file to use; in our case, it's "Sheet1.";
* **DateTime:** This field is used to store the date and time of the made outbound call. In our example, we choose "Attribute Time Start" from the "1. DIDWW: Receive Voice OUT Call Event" dropdown list.
* **Source Number:** This field captures the source number of the outbound call. In our example, we choose "Attribute Src Number" from the "1. DIDWW: Receive Voice OUT Call Event" dropdown list;
* **Destination Number:** This field captures the destination number of the outbound call. In our example, we choose "Attribute Dst Number" from the "1. DIDWW: Receive Voice OUT Call Event" dropdown list;
* **Duration:** This field captures the duration of the outbound call. In our example, we choose "Attribute Duration" from the "1. DIDWW: Receive Voice OUT Call Event" dropdown list;
* **Rate:** This field is used to store the rate associated with the outbound call. In our example, we choose "Attribute Rate" from the "1. DIDWW: Receive Voice OUT Call Event" dropdown list;

.. figure:: https://doc.didww.com/_images/fig_16.png
  :figclass: align-center

  **Fig. 16.** Assigning fields on “Google Sheets app” from “DIDWW Voice Out” app

**Step 16** Click the 'Save & Send Test Request' button ( Fig. 17) to review the data transferred from Pabbly to the Google Sheets file and to ensure that no errors are received (Fig. 18). During this test request, the Google Sheets file will receive and store the data. Alternatively, you can simply click 'Save' without sending a test request.

.. figure:: https://doc.didww.com/_images/fig_17.png
  :figclass: align-center

  **Fig. 17.** Testing setup by clicking “Save & Send Test Request”

.. figure:: https://doc.didww.com/_images/fig_18.png
  :figclass: align-center

  **Fig. 18.** Data passed from Pabbly to Google Spreadsheet

**Step 17** At the end of each outgoing call via your DIDWW outbound SIP trunk with specified DID number, Google Sheet will be updated with a new row containing call details (Fig. 19).

.. figure:: https://doc.didww.com/_images/fig_19.png
  :figclass: align-center

  **Fig. 19.** Data passed and stored from Pabbly to Google Spreadsheet file



.. |br| raw:: html

   <br>

.. _genesys:

================
Genesys Cloud CX
================

Use **Genesys Cloud CX** with **DIDWW SIP Trunking** to deliver inbound and outbound voice services.
DIDWW SIP trunks integrate with Genesys Cloud CX to bring calls from your DID numbers into the platform, apply Genesys routing and call handling, and deliver outbound calls through DIDWW termination.

.. grid:: 1 1 1 2
   :gutter: 4
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Forward inbound calls from your DIDWW DIDs into Genesys Cloud CX.
      - Route calls to queues, IVRs, and agents using Genesys Cloud CX.
      - Apply Genesys routing and call controls.

   .. grid-item::
      :class: left-align-block

      - Use DIDWW outbound SIP trunks for agent and customer calls.
      - Present DIDWW DIDs as Caller ID.
      - Combine DIDWW connectivity with Genesys Number Plans and Sites.

----

.. raw:: html

    <br>

.. _genesys_inbound_trunk:

1. Create Inbound SIP Trunk
===========================

To connect DIDWW with **Genesys Cloud CX**, first create an **Inbound SIP Trunk** in the DIDWW User Panel.
This trunk defines where DIDWW should send incoming calls.

.. raw:: html

    <br>

Before You Begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- At least one active **DID number** with capacity to receive incoming calls is required. `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_.

.. raw:: html

    <br>

Step 1: Create New SIP Trunk
----------------------------

1. In the `DIDWW User Panel <https://my.didww.com/#/trunks>`_, go to **Voice > Inbound Trunks**.
2. Click **Create New > SIP Trunk**.

.. figure:: https://doc.didww.com/_images/didww_inbound1.png
   :figclass: align-center
   :alt: Creating a new inbound SIP trunk

   Fig. 1. Creating a new inbound SIP trunk.

.. raw:: html

    <br>

Step 2: Configure SIP Trunk Settings
------------------------------------

1. In the **General** tab, enter a descriptive **Name** (e.g., ``Genesys Cloud CX``).
2. Select **Static Endpoint**.
3. Enter the Genesys inbound FQDN in the **Host** field (e.g., ``didww.byoc.euw1.pure.cloud``).
4. In **Transport**, select **UDP**, **TCP**, or **TLS**.
5. In **Port**, enter the port that corresponds to the selected transport:

    - ``5060`` for **UDP** or **TCP**
    - ``5061`` for **TLS**
6. Click **Create**.

.. note::
   - The Genesys inbound FQDN is created once you define the **Termination Identifier** in your Genesys External Trunk configuration.
   - If you have not created the Genesys External Trunk yet, enter a **placeholder** (e.g., ``placeholder.domain``) and update it later during the :ref:`Genesys External Trunk Configuration <genesys_config_trunk>` step.

.. figure:: https://doc.didww.com/_images/didww_inbound2.png
   :figclass: align-center
   :alt: Configuring the Inbound SIP Trunk for Genesys Cloud CX

   Fig. 2. Configuring the Inbound SIP Trunk for Genesys Cloud CX

.. raw:: html

    <br>

Step 3: Assign DIDs to the Trunk
--------------------------------

1. Go to **Phone Numbers > My Numbers**.
2. Select the DID numbers you wish to assign.
3. Click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/didww_inbound3.png
   :figclass: align-center
   :alt: Assigning DIDs to trunk

   Fig. 3. Assigning DIDs to the trunk.

4. Select the **Genesys Cloud CX** trunk and click **Confirm**.

.. figure:: https://doc.didww.com/_images/didww_inbound4.png
   :figclass: align-center
   :alt: Updating trunk assignment

   Fig. 4. Selecting the Genesys trunk.

----

.. raw:: html

    <br>

.. _genesys_outbound_trunk:

2. Create Outbound SIP Trunk
============================

To enable outbound calling from Genesys Cloud CX, create an **Outbound SIP Trunk** in DIDWW.

.. raw:: html

    <br>

Before You Begin
----------------

Access to **DIDWW Outbound Trunks** is required for outbound calling. See :ref:`Get Access to DIDWW Outbound Termination <user_panel_voice_out_get_access>`.

.. raw:: html

    <br>

Step 1: Create New Outbound Trunk
---------------------------------

1. In the DIDWW User Panel, go to **Voice > Outbound Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/didww_outbound1.png
   :figclass: align-center
   :alt: Creating outbound trunk

   Fig. 5. Creating a new outbound trunk.

.. raw:: html

    <br>

Step 2: Configure Trunk Settings
--------------------------------

1. Enter a **Friendly Name** (e.g., ``Genesys Outbound``).
2. In **Allowed SIP IP addresses**, add the Genesys BYOC Cloud IPs for your region.
3. Click **Create**.

.. note::
   - Identify your region code from your Genesys login URL (e.g., ``.ie`` indicates **euw1**) and whitelist the **IP Addresses** listed in the table for that region in the `Genesys BYOC Cloud IP list <https://help.mypurecloud.com/articles/byoc-cloud-public-sip-ip-addresses/>`_.
   - Alternatively, entering ``0.0.0.0/0`` removes IP restrictions but is not recommended for production.

.. figure:: https://doc.didww.com/_images/didww_outbound2.png
   :figclass: align-center
   :alt: Configuring outbound trunk

   Fig. 6. Outbound trunk configuration.

.. raw:: html

    <br>

.. _genesys_outbound_trunk_creds:

Step 3: Retrieve Credentials
----------------------------

1. Go to **Voice > Outbound Trunks**.
2. Click the **key icon** in the **Credentials** column.

.. figure:: https://doc.didww.com/_images/didww_outbound3.png
   :figclass: align-center
   :alt: Revealing credentials

   Fig. 7. Revealing the credentials.

3. **Copy and save** the **Username** and **Password** (click the **eye icon** to reveal the password) for use in the later :ref:`Configure Genesys Cloud CX <genesys_configuration>` steps.

.. warning:: If the credentials become exposed to unauthorized parties, :ref:`rotate them immediately in the DIDWW User Panel <view_outbound_trunk_credentials>`.

.. figure:: https://doc.didww.com/_images/didww_outbound4.png
   :figclass: align-center
   :alt: Viewing outbound credentials

   Fig. 8. Retrieving outbound credentials.

----

.. raw:: html

    <br>

.. _genesys_configuration:

3. Configure Genesys Cloud CX
=============================

This section covers the Genesys Cloud CX configuration:

1. Create a **Site**
2. Create an **External Trunk**
3. Configure **DID Ranges & Assignments**

.. raw:: html

    <br>

Before You Begin
----------------

- Genesys Cloud CX admin access and `BYOC Cloud Addon <https://help.mypurecloud.com/articles/add-byoc-cloud-or-genesys-cloud-voice-to-your-subscription/>`_ are required.
- A `Location <https://help.mypurecloud.com/articles/create-a-location/>`_ must exist before creating a Site.

.. raw:: html

    <br>

.. _genesys_config_site:

Step 1: Site Configuration
--------------------------

A **Site** in Genesys Cloud CX defines the telephony properties and routing rules for a location. You must create a Site before assigning Trunks to it.

Create a New Site
^^^^^^^^^^^^^^^^^

1. Navigate to **Digital and Telephony > Telephony > Sites**.
2. Click **Add**.

.. figure:: https://doc.didww.com/_images/sites1.png
   :figclass: align-center
   :alt: Create site

   Fig. 9. Adding a new Site.

3. Enter:

    - A descriptive **Site Name** (e.g., ``Headquarters``).
    - Your physical **Location**.
    - ``Cloud`` as the **Media Model**.
    - Your preferred **Time Zone**.
4. Click **Create**.

.. note::
   The **Media Model** cannot be changed after creating the site.

.. figure:: https://doc.didww.com/_images/sites2.png
   :figclass: align-center
   :alt: Site creation form

   Fig. 10. Creating a new Site.

Set as Default Site
^^^^^^^^^^^^^^^^^^^

1. Open the **General** tab.
2. Click **Make this site the default site**.
3. Confirm by clicking **Yes, Make Default**.

.. figure:: https://doc.didww.com/_images/sites3.png
   :figclass: align-center
   :alt: Default site setting

   Fig. 11. Setting the default site.

----

.. raw:: html

    <br>

.. _genesys_config_trunk:

Step 2: External Trunk Configuration
------------------------------------

In this step, you will configure the SIP connection between Genesys Cloud CX and DIDWW.

Create the External Trunk
^^^^^^^^^^^^^^^^^^^^^^^^^

1. Go to **Digital and Telephony > Telephony > Trunks**.
2. Click **Create New**.

.. figure:: https://doc.didww.com/_images/trunks1.png
   :figclass: align-center
   :alt: Create external trunk

   Fig. 12. Creating a new External Trunk.

3. Enter:

    - A descriptive **External Trunk Name** (e.g., ``DIDWW``).
    - ``BYOC Carrier`` as the **Type**.
    - ``Generic BYOC Carrier`` as the **Subtype**.
4. Select the **Protocol** (UDP, TCP, or TLS).

.. figure:: https://doc.didww.com/_images/trunks2.png
   :figclass: align-center
   :alt: Basic trunk settings

   Fig. 13. Basic External Trunk settings.

Configure Inbound SIP Routing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the **Inbound** section, enter a unique **Termination Identifier** (e.g., ``didww``).
2. Scroll down to **Number Plan** and select your previously created Site in the **From site** field.

.. important::
   The **Termination Identifier** generates your unique **FQDN** (e.g., ``didww.byoc.euw1.pure.cloud``). If you used a **placeholder** earlier, copy this FQDN and update the **Host** field in your :ref:`DIDWW Inbound Trunk <genesys_inbound_trunk>` settings.

.. figure:: https://doc.didww.com/_images/trunks3.png
   :figclass: align-center
   :alt: Inbound routing config

   Fig. 14. Inbound SIP routing configuration.

Configure Outbound SIP Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Scroll to the **Outbound** section.
2. In the **Outbound SIP Termination FQDN** field, enter the DIDWW FQDN (e.g., ``fra.eu.out.didww.com``).
3. Under **SIP Servers or Proxies**, enter the same FQDN (e.g., ``fra.eu.out.didww.com``) and the Port (``5060`` for UDP/TCP, ``5061`` for TLS), then click the **+ (Plus)** button to add it.
4. Enable **Digest Authentication**.
5. In the **Realm** field, enter ``out.didww.com``.
6. Enter the **User Name** and **Password** obtained from the DIDWW Outbound Trunk in :ref:`Step 3: Retrieve Credentials <genesys_outbound_trunk_creds>`.

.. note::
    - It is recommended to configure the DIDWW FQDN closest to your location. See :ref:`Outbound DIDWW Signaling Endpoints <voice-out-signaling-endpoints>`.

.. figure:: https://doc.didww.com/_images/trunks4.png
   :figclass: align-center
   :alt: Outbound SIP settings

   Fig. 15. Configuring outbound SIP settings.

Configure SIP Access Control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Scroll to **SIP Access Control**.
2. Add the required DIDWW IP ranges:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Description
     - Allowed IP / CIDR
   * - **DIDWW Global Range**
     - ``46.19.208.0/21``
   * - **Amsterdam Range**
     - ``185.238.173.0/24``

3. Click **Save External Trunk**.

.. figure:: https://doc.didww.com/_images/trunks5.png
   :figclass: align-center
   :alt: SIP Access Control

   Fig. 16. Adding DIDWW IP ranges.

Add Trunk to Outbound Route
^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Go to **Telephony > Sites** and click on your Site's name.
2. Open the **Outbound Routes** tab.
3. Click on the **Default Outbound Route** name to open its settings.
4. Ensure the **State** toggle at the top is **Enabled**.
5. Select the **DIDWW** trunk under **External Trunks**.
6. Click **Save Outbound Routes**.

.. figure:: https://doc.didww.com/_images/trunks6.png
   :figclass: align-center
   :alt: Adding the DIDWW External Trunk to the Outbound Route

   Fig. 17. Adding an External Trunk to the Outbound Route.

Simulate a Call
^^^^^^^^^^^^^^^

1. While you remain in your **Site's** settings, open the **Simulate Call** tab.
2. Enter a destination number.
3. Click **Simulate Call**.
4. Confirm that the simulation is **Successful**.

.. figure:: https://doc.didww.com/_images/trunks7.png
   :figclass: align-center
   :alt: Simulate a call

   Fig. 18. Simulating a call.

----

.. raw:: html

    <br>

.. _genesys_config_did:

Step 3: DID Number Configuration
--------------------------------

Create and assign DID ranges so Genesys Cloud CX can route incoming calls.

Create DID Range
^^^^^^^^^^^^^^^^

1. Navigate to **Digital and Telephony > Telephony > DID Numbers**.
2. Select the **DID Ranges** tab.
3. Click **Create Range**.
4. Enter:

    - **DID Start** and **DID End** numbers. The country flag selector appears automatically; enter the number in E.164 format (e.g., ``18489005419``).
    - Enter ``DIDWW`` as the **Service Provider**.
    - Add an optional **Comment** (e.g., ``My DIDWW DID Number``).
5. Click **Save**.

.. note::
   For a single DID, enter the same value in **DID Start** and **DID End**.

.. figure:: https://doc.didww.com/_images/number1.png
   :figclass: align-center
   :alt: Creating DID range

   Fig. 19. Creating a DID range.

Assign DID Numbers
^^^^^^^^^^^^^^^^^^

1. Open the **DID Assignments** tab.
2. Click **Assign**.
3. Configure:

    - Select the **Assignee Type** (e.g., ``Person``, ``Queue``, ``IVR``).
    - Choose the **Assignee**.
    - Select **Save Number As** (e.g., ``Work Phone``).
    - Select the DIDWW **DID Number**.
4. Click **Save**.

.. note::
   Only DID numbers added in the **DID Ranges** tab appear in the **DID Number** dropdown.

.. figure:: https://doc.didww.com/_images/number2.png
   :figclass: align-center
   :alt: Assign DID number

   Fig. 20. Assigning a DIDWW number.


FreePBX
=======

DIDWW SIP Trunks can be used with FreePBX for Inbound and Outbound calls. The following guide will explain the steps necessary to configure the FreePBX.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`arrow-down` **Inbound Setup**
      :link: inbound
      :link-type: doc
      :text-align: left

      Configure inbound DIDWW SIP trunks in FreePBX for receiving calls.

   .. grid-item-card:: :octicon:`arrow-up` **Outbound Setup**
      :link: outbound
      :link-type: doc
      :text-align: left

      Set up outbound SIP trunks in FreePBX for placing calls.

   .. grid-item-card:: :octicon:`person` **Extensions**
      :link: extensions
      :link-type: doc
      :text-align: left

      Configure SIP extensions in FreePBX.

.. toctree::
   :maxdepth: 1
   :hidden:

   inbound.rst
   outbound.rst
   extensions.rst


Inbound
=======

DIDWW SIP Trunks can be used with FreePBX for Inbound calls. The following guide will explain the steps necessary to configure the FreePBX.

.. note:: This guide has been created with FreePBX Version 16.0.21.9.

Getting Started
---------------

What you need to get started:

    * Access to `DIDWW self-service portal <https://my.didww.com/#/users/sign_in>`_ to create :ref:`DIDWW Inbound SIP Trunk  <user_panel_sipin_trunk>` trunk and :ref:`assign <user_panel_assign_trunk>` it to the preferred DID number.
    * Access to FreePBX Administration UI.

Configuring Asterisk SIP Settings
---------------------------------

**Step 1.** Click **Settings** on the top section, then select **Asterisk SIP Settings** from the dropdown menu.

**Step 2.** On the SIP Settings page, click on the **SIP Settings [chan_pjsip]** tab and enter the fields (Fig. 1):

    * **Port to Listen On:** your preferred port

.. figure:: https://doc.didww.com/_images/sip_fig1.jpg
  :figclass: align-center

  **Fig. 1.** SIP settings page, SIP Settings [chan_pjsip] tab.

**Step 3.** Complete configuration by clicking the **Submit** button on the bottom right side. Click on **Apply Config** located on the top right side.

Configuring the Inbound Trunk
-----------------------------

**Step 1.** On the top menu of the Admin interface click **Connectivity** and select **Trunks** from the dropdown menu.

**Step 2.** In the Trunks window, click on **Add Trunk**, and select **Add SIP (chan_pjsip) Trunk** from the dropdown menu (Fig. 1).

.. figure:: https://doc.didww.com/_images/in_fig1.jpg
  :figclass: align-center

  **Fig. 1.** Trunks page.

**Step 3.** Enter your preferred Trunk name in Add Trunk window, under the General tab (Fig. 2).

.. figure:: https://doc.didww.com/_images/in_fig2.jpg
  :figclass: align-center

  **Fig. 2.** Add Trunk page, General tab.

**Step 4.** Navigate to pjsip Settings, General Tab, and fill out these fields (Fig. 3):

    * **Authentication:** None (**Registration** field will change to None accordingly)
    * **SIP Server:** all :ref:`IP addresses <service_did_sip>` separated by comma
    * **SIP Server Port:** your preferred port
    * **Context:** from-pstn
    * **Transport:** 0.0.0.0-udp (instead of 0.0.0.0 FreePBX public IP can be displayed)

.. figure:: https://doc.didww.com/_images/in_fig3.jpg
  :figclass: align-center

  **Fig. 3.** Add Trunk page, pjsip Settings General tab.

.. note:: Optional trunk authorization can be configured by selecting **Inbound** in the FreePBX **Authentication** field and **Receive** in the **Registration** field. In the DIDWW inbound SIP trunk, open the **Authorization** tab, enable **Enable Authorization**, and enter the FreePBX trunk name as **Auth User** and the secret as **Auth Password**.

**Step 5.** Navigate to the Advanced tab of pjsip Settings and enter all :ref:`IP addresses <service_did_sip>` separated by a comma in Match (Permit) field (Fig. 4).

.. figure:: https://doc.didww.com/_images/in_fig4.jpg
  :figclass: align-center

  **Fig. 4.** Add Trunk page, pjsip Settings Advanced tab.

**Step 6.** Complete configuration by clicking the **Submit** button on the bottom right side.

Configuring the Inbound Route
-----------------------------

**Step 1.** Navigate to the **Connectivity** section in the top menu. Select the **Inbound Routes** from the dropdown menu and a new page will pop up. Select **Add Inbound Route** (Fig. 1).

.. figure:: https://doc.didww.com/_images/route_fig1.jpg
  :figclass: align-center

  **Fig. 1.** Inbound Routes page.

**Step 2.** On the **Add Incoming Route** page, enter your preferred Description, DID number (optional if you want to forward calls from a specific DID), and select Destination (Extension, Queues, Ring Groups, etc.) (Fig. 2).

.. note:: To set Extension, Queue or Ring Group as Destination, firstly it needs to be configured in their designated pages, which can be located under the **Applications** section.

.. figure:: https://doc.didww.com/_images/route_fig2.jpg
  :figclass: align-center

  **Fig. 2.** New Inbound Route creation page.

**Step 3.** Complete the configuration by clicking the **Submit** button on the bottom right side. Click on **Apply Config** located on the top right side.



Outbound
========

DIDWW SIP Trunks can be used with FreePBX for Outbound calls. The following guide will explain the steps necessary to configure the FreePBX.

.. note:: This guide has been created with FreePBX Version 16.0.21.9.

Getting Started
---------------

What you need to get started:

    * Access to `DIDWW self-service portal <https://my.didww.com/#/users/sign_in>`_ to create :ref:`DIDWW Outbound SIP Trunk <user_panel_voice_out>` trunk.
    * Access to FreePBX Administration UI.

Configuring the Outbound Trunk
------------------------------

**Step 1.** Click **Connectivity** on the top section and select **Trunks** from the dropdown menu. Then click on **Add Trunk** and select **Add SIP (chan_pjsip) Trunk** (Fig. 1).

.. figure:: https://doc.didww.com/_images/out_fig1.jpg
  :figclass: align-center

  **Fig. 1.** Trunks page.

**Step 2.** Enter your preferred Trunk name in Add Trunk window, under the General tab (Fig. 2).

.. figure:: https://doc.didww.com/_images/out_fig2.jpg
  :figclass: align-center

  **Fig. 2.** Add Trunk page.

**Step 3.** Navigate to pjsip Settings, General Tab, and fill out these fields (Fig. 3):

    * **Username:** SIP Outbound trunk username
    * **Auth username:** SIP Outbound trunk username
    * **Secret:** SIP Outbound trunk password
    * **Authentication:** Outbound
    * **Language code:** Default
    * **SIP Server:** out.didww.com or other :ref:`DNS records <services_voice_out>`
    * **SIP Server Port:** 5060
    * **Context:** from-pstn
    * **Transport:** 0.0.0.0-udp (instead of 0.0.0.0 FreePBX public IP can be displayed)

.. note:: If Outbound Trunk have credentials removed, leave the Username, Auth Username, and Password fields blank.

.. figure:: https://doc.didww.com/_images/out_fig3.jpg
  :figclass: align-center

  **Fig. 3.** SIP settings page, SIP Settings [chan_pjsip] tab.

**Step 4.** Complete configuration by clicking the **Submit** button on the bottom right side.

Configuring the Outbound Route
------------------------------

**Step 1.** Navigate to the **Outbound Routes**, located under the **Connectivity** section at the top menu.

**Step 2.** On the **Outbound Routes** page, select **Add Outbound Route**, and fill out these fields (Fig. 1):

    * **Route Name:** your preferred route name
    * **Trunk Sequence for Matched Routes:** select the created Outbound Trunk

.. note:: If you would like to use more than one Outbound Trunk as a failover option, you will be able to add another trunk once the last empty field is selected.

.. figure:: https://doc.didww.com/_images/out_route_fig1.jpg
  :figclass: align-center

  **Fig. 1.** Outbound Routes page, Route Settings tab.

**Step 3.** Switch to the **Dial Patterns** tab and fill out these fields (Fig. 2):

.. code-block:: ini

    [match patterns]
    XXXXXXXXX
    XXXXXXXXXX
    XXXXXXXXXXX
    XXXXXXXXXXXX
    XXXXXXXXXXXXX

.. figure:: img/out_route_fig2_alt.jpg
  :figclass: align-center

  **Fig. 2.** Outbound Routes page, Dial Patterns tab.

.. note:: There is a option to import :download:`Dial Patterns <didww_dial_patterns.csv>` in **Import/Export Patterns** tab, however, it will override previous Dial Patterns.

**Step 4.** Complete configuration by clicking the **Submit** button on the bottom right side. Click on **Apply Config** located on the top right side.


Extensions
==========

The following guide will explain the steps necessary to configure extensions of the FreePBX.

Configuring an extension in FreePBX
-----------------------------------

**Step 1.** Navigate to **Extensions**, located under the **Applications** section at the top menu.

**Step 2.** On the Extensions page, click **Add Extension** and select **Add new SIP (chan_pjsip) Extension** from the dropdown menu (Fig. 1).

.. figure:: https://doc.didww.com/_images/extensions_fig1.jpg
  :figclass: align-center

  **Fig. 1.** Extensions page.

**Step 3.** In Add PJSIP Extension window, fill out these fields (Fig 2.):

    * **User Extension:** your preferred number for Internal number and SIP account username (e.g. 1234)
    * **Display Name:** your preferred name
    * **Outbound CID:** caller ID for making outbound calls
    * **Secret:** generated or your chosen password to register extension

.. figure:: https://doc.didww.com/_images/extensions_fig2.jpg
  :figclass: align-center

  **Fig. 2** Add PJSIP Extension page.

**Step 4.** Complete configuration by clicking the **Submit** button on the bottom right side. Click on **Apply Config** located on the top right side.



.. |br| raw:: html

  <br>

.. _odoo_integration:

=====
Odoo
=====

Use `Odoo <https://www.odoo.com/>`_ with **DIDWW** and **phone.systems™** to place and receive business calls directly from the Odoo Phone app.
This integration routes DIDWW phone numbers through phone.systems™ and connects them to Odoo using secure WebSocket signaling for browser-based WebRTC calling.

.. grid:: 1 1 1 2
   :gutter: 0
   :class-container: compact-bullet-grid

   .. grid-item::
      :class: left-align-block

      - Route DIDWW phone numbers to the Odoo Phone app.
      - Place and receive calls directly in Odoo.
      - Use existing DIDWW numbers for browser-based calling.

   .. grid-item::
      :class: left-align-block

      - Link Odoo users to dedicated phone.systems™ SIP Accounts.
      - Deliver calls to individual users through phone.systems™.
      - Keep business calling inside the Odoo workspace.

----

.. _odoo_didww:

1. Route DIDWW Numbers to phone.systems™
========================================

Prepare your DIDWW account and route your DID numbers to **phone.systems™**.
This step is required because phone.systems™ acts as the calling layer between DIDWW and the Odoo Phone app.
After your DID numbers are assigned to the phone.systems™ trunk, phone.systems™ can forward incoming calls to the SIP Accounts that are later connected to Odoo users.

Before You Begin
----------------

- An active **DIDWW account** is required. `Sign in to DIDWW <https://my.didww.com/users/sign_in>`_ or `Create DIDWW account <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- At least one active **DID number** with **inbound calls** and **local CLI** features with sufficient :ref:`Capacity <flexible_capacity>` to receive incoming calls is required. See `Buy Numbers <https://my.didww.com/users/sign_up#/coverage>`_ and :ref:`Number Porting <user_panel_porting>`.

Step 1: Purchase phone.systems™ Seats
-------------------------------------

Before you configure the DID number routing, you will need at least one phone.systems™ seat to gain access to phone.systems™ trunks. If you do not have any seats yet:

1. In the DIDWW User Panel, open the `Cloud Phone System <https://my.didww.com/#/phone_systems>`_ menu.
2. Purchase the required amount of **phone.systems™** seats.

.. note::
   Purchase one **phone.systems™** seat for each Odoo user who will make or receive calls.

.. figure:: https://doc.didww.com/_images/purchase_seats.png
   :figclass: align-center
   :alt: Purchasing phone.systems™ seats in the DIDWW User Panel

   Fig. 1. Purchasing phone.systems™ seats in DIDWW

Step 2: Assign phone.systems™ Trunk to Your DID Numbers
-------------------------------------------------------

After purchasing the required phone.systems™ service, assign the phone.systems™ trunk to the DID number(s) that will be used with Odoo.

1. In the DIDWW User Panel, go to **Phone Numbers > My Numbers**.
2. Select the DID number(s) you want to assign to the phone.systems™ trunk.
3. At the bottom of the page, click **Batch Actions > Update Trunks**.

.. figure:: https://doc.didww.com/_images/didww2.png
   :figclass: align-center
   :alt: Assigning the phone.systems™ trunk to DID numbers

   Fig. 2. Selecting **Update Trunks** from the Batch Actions menu

4. From the dropdown menu, choose the **phone.systems™** trunk.
5. Click **Confirm** to assign the trunk.

.. figure:: https://doc.didww.com/_images/didww3.png
   :figclass: align-center
   :alt: Assigning the phone.systems™ trunk to DID numbers

   Fig. 3. Assigning the phone.systems™ trunk to the selected DID(s)

Step 3: Launch phone.systems™
-----------------------------

1. In the DIDWW User Panel, go to `Cloud Phone System <https://my.didww.com/#/phone_systems>`_ menu.
2. Click **Launch admin UI**.

.. figure:: https://doc.didww.com/_images/didww4.png
   :figclass: align-center
   :alt: Launching the phone.systems™ admin UI from DIDWW

   Fig. 4. Launching the phone.systems™ admin UI

----

.. raw:: html

    <br>

.. _odoo_phone_systems:

2. Set Up phone.systems™ SIP Accounts for Odoo Users
====================================================

After assigning your DID number to phone.systems™, create the user and SIP Account that will be connected to an Odoo user.
This step is required because phone.systems™ provides the SIP credentials, inbound routing, outbound caller ID, WebSocket signaling, and secure media settings used by the Odoo Phone app.
Each Odoo user who makes or receives calls should have a dedicated phone.systems™ SIP Account.

Step 1: Create User
-------------------

1. In the **phone.systems™** admin UI, go to **Users**.
2. Click the **plus** sign and select **Create New** to create a new user.

.. figure:: https://doc.didww.com/_images/phonesystems1.png
   :figclass: align-center
   :alt: Creating a new user in phone.systems™

   Fig. 5. Creating a new user in phone.systems™

3. Enter the required user details, such as **First name**, and **Last name**.
4. Uncheck the **Configure application line in the next step** slider.
5. **Save** the user.

.. note::
   Create one **phone.systems™** user for each Odoo user who will use the Odoo Phone app.

.. figure:: https://doc.didww.com/_images/phonesystems2.png
   :figclass: align-center
   :alt: Entering user details and saving a new user in phone.systems™

   Fig. 6. Entering user details and saving the new user

Step 2: Create and Configure a SIP Account
------------------------------------------

1. Go to **Contact Methods > SIP Accounts**.
2. Click the **plus** sign to create a new **SIP Account**.

.. note::
   Create one **SIP Account** for each Odoo user. Each Odoo user should use their own dedicated phone.systems™ SIP credentials.

.. figure:: https://doc.didww.com/_images/phonesystems3.png
   :figclass: align-center
   :alt: Creating a SIP Account in phone.systems™

   Fig. 7. Creating a SIP Account

Configure User and Inbound Calls
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In the **General** section, select the user that you created in the previous step.
2. In the **Inbound calls** section, select the DID number you assigned to **phone.systems™** in DIDWW.

.. note::
   For additional inbound configuration options, such as internal numbers, voicemail, and unavailable behavior, see :ref:`SIP Account inbound calls <ps3_sip_accounts_inbound_calls>`.

.. figure:: https://doc.didww.com/_images/phonesystems4.png
   :figclass: align-center
   :alt: Configuring inbound calls in a SIP Account

   Fig. 8. Configuring inbound calls in the SIP Account

Configure Outbound Calls
^^^^^^^^^^^^^^^^^^^^^^^^

1. In the **Outbound calls** section, enable **Enable external outbound calls**.
2. In **Caller ID**, select the same DID number assigned for inbound calling.

.. note::
   For additional outbound configuration options, such as internal caller ID, announcements, and call recording, see :ref:`SIP Account outbound calls <ps3_sip_accounts_outbound_calls>`.

.. figure:: https://doc.didww.com/_images/phonesystems5.png
   :figclass: align-center
   :alt: Configuring outbound calls in a SIP Account

   Fig. 9. Configuring outbound calls in the SIP Account

Configure Advanced Settings and Save
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the **Advanced** section, configure the settings required for Odoo Phone.

1. Keep the default **Allowed Codecs** unless your deployment requires custom codec restrictions.
2. In **Allowed media types**, select ``SRTP-DTLS``.
3. In **Default media type**, select ``SRTP-DTLS``.
4. In **Transport protocol**, select ``WSS``.
5. **Save** the SIP Account.

.. figure:: https://doc.didww.com/_images/phonesystems6.png
   :figclass: align-center
   :alt: Configuring advanced SIP Account settings in phone.systems™

   Fig. 10. Configuring advanced settings in the SIP Account

Step 3: Copy SIP Account Credentials for Odoo
----------------------------------------------

1. Locate your SIP Account and click **Actions > Edit**.

.. figure:: https://doc.didww.com/_images/phonesystems7.png
   :figclass: align-center
   :alt: Opening the SIP Account edit view from the Actions menu in phone.systems™

   Fig. 11. Opening the SIP Account edit view

2. **Copy and save** the SIP Account credentials for later use in Odoo.

.. figure:: https://doc.didww.com/_images/phonesystems8.png
   :figclass: align-center
   :alt: Viewing SIP Account credentials in phone.systems™

   Fig. 12. Viewing SIP Account credentials

----

.. raw:: html

    <br>

.. _odoo_odoo:

3. Connect Odoo to DIDWW
========================

After DIDWW and phone.systems™ are configured, connect the phone.systems™ SIP Account to the Odoo Phone app.
This step allows Odoo to use DIDWW as the calling provider and use the SIP Account credentials for browser-based inbound and outbound calls.
Each Odoo user is linked to their own phone.systems™ SIP Account so calls are delivered to the correct user.

Step 1: Install Phone App
-------------------------

Before configuring the DIDWW provider, install the **Phone** app in Odoo.

1. In Odoo, open the **Apps** menu.
2. Search for the ``phone`` app and click **Install**.

.. figure:: https://doc.didww.com/_images/odoo1.png
   :figclass: align-center
   :alt: Installing the Phone app in Odoo

   Fig. 13. Installing the Phone app in Odoo

Step 2: Configure DIDWW Provider in Odoo
----------------------------------------

1. In Odoo, open the **Phone** app.
2. Go to **Configuration > Providers**.

.. figure:: https://doc.didww.com/_images/odoo2.png
   :figclass: align-center
   :alt: Opening the Providers page from the Odoo Phone app

   Fig. 14. Opening the Providers page in Odoo Phone

3. In the **DIDWW** provider row, set **VoIP Environment** to **Production** to enable real SIP connectivity.
4. Click **Save**.

.. figure:: https://doc.didww.com/_images/odoo3.png
   :figclass: align-center
   :alt: Setting the DIDWW VoIP Environment to Production in Odoo

   Fig. 15. Setting the DIDWW VoIP Environment to Production

Step 3: Configure User VoIP Credentials in Odoo
-----------------------------------------------

1. Open **Settings**.
2. In the **General Settings > Users** section, click **Manage Users**.

.. note::
   Repeat these credential steps for each Odoo user who will use the Phone app.

.. figure:: https://doc.didww.com/_images/odoo4.png
   :figclass: align-center
   :alt: Opening the Users page from Odoo Settings

   Fig. 16. Opening the Users page from Odoo Settings

3. Open the user who will use the Odoo **Phone** app.
4. Open the **VoIP** tab.
5. Configure **Credentials** settings:

   - Select **DIDWW** as the **Provider**.
   - Enter the user’s phone.systems™ SIP Account **Username**.
   - Enter the SIP Account's **Password** in the **Secret** field.

.. figure:: https://doc.didww.com/_images/odoo5.png
   :figclass: align-center
   :alt: Configuring DIDWW VoIP credentials for an Odoo user

   Fig. 17. Configuring VoIP credentials for an Odoo user

Step 4: Test Inbound and Outbound Calls
---------------------------------------

When the DIDWW provider and user credentials are configured, test the connection in Odoo.

1. Click the **Phone** icon in the top-right corner of Odoo to open the **softphone**.
2. Place a test **inbound call** to the DID number assigned to phone.systems™.
3. Place a test **outbound call** to any PSTN number in E.164 format (country code + area code + subscriber number, e.g., 15550100001).

Verify that calls connect successfully and that the user can both place and receive calls in Odoo.

.. note::

   You can review call activity and verify call status or error codes in the :ref:`phone.systems™ Call Analytics <ps3_call_analytics>`.

.. figure:: https://doc.didww.com/_images/odoo6.png
   :figclass: align-center
   :alt: Testing a call in the Odoo Phone softphone

   Fig. 18. Testing a call in the Odoo Phone softphone

----

Additional Resources
====================

.. card:: **Odoo Phone Documentation**
   :link: https://www.odoo.com/documentation/19.0/applications/productivity/phone.html
   :link-type: url

   Official Odoo documentation for the Phone app and its features.

.. card:: **Odoo DIDWW Documentation**
   :link: https://www.odoo.com/documentation/19.0/applications/productivity/phone/didww.html
   :link-type: url

   Official Odoo guide for using the Phone app with DIDWW.


.. _didww-prometheus-exporter:

=========================
DIDWW Prometheus Exporter
=========================

The DIDWW Prometheus exporter is a service that provides access to metrics and account information for monitoring and alerts. Once configured, it allows you to track various statistics related to your DIDWW account.

.. figure:: https://doc.didww.com/_images/prometheus_graph_and_metrics_list.png
    :figclass: align-center
    :alt: DIDWW Prometheus Exporter Graph Example And List of Metrics
    :width: 100%

    **Fig. 1.** DIDWW Prometheus Exporter Graph Example And List of Metrics

Supported Metrics
-----------------

The DIDWW Prometheus exporter provides several metrics to monitor your account's status and usage.

.. csv-table::
   :header: "Nr.", "Name", "Description"

   "1", "`didww_exporter_up <#didww_exporter_up>`__", "Indicates whether the DIDWW exporter is operational (1 if up, 0 if down)."
   "2", "`didww_collector_up <#didww_collector_up>`__", "Indicates whether the collector is operational (1 if up, 0 if down)."
   "3", "`didww_balance <#didww_balance>`__", "Shows the current balance of the account."
   "4", "`didww_voice_out_active_calls <#didww_voice_out_active_calls>`__", "Number of concurrent outbound calls on the account, measured every minute."
   "5", "`didww_voice_out_active_calls_price <#didww_voice_out_active_calls_price>`__", "Cost of active outbound calls on the account, updated every minute."
   "6", "`didww_voice_out_trunk_active_calls_count <#didww_voice_out_trunk_active_calls_count>`__", "Number of concurrent outbound calls via the trunk, measured every minute."
   "7", "`didww_voice_out_trunk_active_calls_price <#didww_voice_out_trunk_active_calls_price>`__", "Cost of active outbound calls via the trunk, updated every minute."
   "8", "`didww_voice_out_trunk_last24h_price <#didww_voice_out_trunk_last24h_price>`__", "Total cost of outbound calls completed via the trunk in the last 24 hours."
   "9", "`didww_event_api_queue_size <#didww_event_api_queue_size>`__", "Current size of the event API queue."
   "10", "`didww_event_api_sent <#didww_event_api_sent>`__", "Total number of events sent via the event API."
   "11", "`didww_event_api_responses <#didww_event_api_responses>`__", "Count of received responses for each HTTP status code."

.. raw:: html

   <br>

Metric Details & Usage Example
------------------------------

.. raw:: html

   <a id="didww_exporter_up"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>1. didww_exporter_up</b></p>

Indicates the operational status of the DIDWW exporter. A value of ``1`` signifies that the exporter is up and running, while ``0`` indicates it is down.

 - Sample Output:

                 .. code-block::

                  didww_exporter_up 1

 - Usage Example: Monitor this metric to ensure the exporter is functioning correctly. Configure an alert to notify if the value drops to ``0``, indicating a potential issue with the exporter.

.. raw:: html

   <a id="didww_collector_up"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>2. didww_collector_up</b></p>

Reflects the status of individual collectors within the exporter. Each collector gathers specific data; a value of ``1`` means the collector is operational, while ``0`` indicates it is not.

 - Sample Output:

                  .. code-block::

                     didww_collector_up{collector="event_api"} 1
                     didww_collector_up{collector="voice_out"} 1

 - Usage Example: Use this metric to verify that all collectors are active. If a collector’s value is ``0``, it may require investigation to restore functionality.

.. raw:: html

   <a id="didww_balance"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>3. didww_balance</b></p>

Displays the current balance of your DIDWW account in USD currency.

 - Sample Output:

                 .. code-block::

                     didww_balance 150.75

 - Usage Example: Track this metric to monitor your account balance. Set up alerts to notify when the balance falls below a specified threshold to ensure uninterrupted service.

.. raw:: html

   <a id="didww_voice_out_active_calls"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>4. didww_voice_out_active_calls</b></p>

Indicates the number of concurrent outbound calls from your account, measured every minute.

 - Sample Output:

                .. code-block::

                    didww_voice_out_active_calls 5

 - Usage Example: Monitor this metric to track your outbound call volume. It helps in capacity planning and identifying unusual spikes in call activity.

.. raw:: html

   <a id="didww_voice_out_active_calls_price"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>5. didww_voice_out_active_calls_price</b></p>

Shows the total cost of active outbound calls from your account, measured every minute.

 - Sample Output:

                 .. code-block::

                     didww_voice_out_active_calls_price 12.50

 - Usage Example: Track this metric to monitor real-time spending on outbound calls. It aids in budgeting and cost management.

.. raw:: html

   <a id="didww_voice_out_trunk_active_calls_count"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>6. didww_voice_out_trunk_active_calls_count</b></p>

Represents the number of concurrent outbound calls through a specific trunk, measured every minute.

 - Sample Output:

                 .. code-block::

                     didww_voice_out_trunk_active_calls_count{trunk="voice_out_trunk_name_1"} 3
                     didww_voice_out_trunk_active_calls_count{trunk="voice_out_trunk_name_2"} 2

 - Usage Example: Use this metric to assess the load on individual trunks. It assists in balancing traffic and optimizing trunk usage.

.. raw:: html

   <a id="didww_voice_out_trunk_active_calls_price"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>7. didww_voice_out_trunk_active_calls_price</b></p>

Displays the total cost of active outbound calls through a specific trunk, measured every minute.

 - Sample Output:

                 .. code-block::

                     didww_voice_out_trunk_active_calls_price{trunk="voice_out_trunk_name_1"} 7.50
                     didww_voice_out_trunk_active_calls_price{trunk="voice_out_trunk_name_2"} 5.00

 - Usage Example: Monitor this metric to understand the cost distribution across different trunks. It helps in financial analysis and cost optimization.

.. raw:: html

   <a id="didww_voice_out_trunk_last24h_price"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>8. didww_voice_out_trunk_last24h_price</b></p>

Shows the total cost of all outbound calls completed through a specific trunk in the last 24 hours.

 - Sample Output:

                 .. code-block::

                     didww_voice_out_trunk_last24h_price{trunk="voice_out_trunk_name_1"} 100.00
                     didww_voice_out_trunk_last24h_price{trunk="voice_out_trunk_name_2"} 80.00

 - Usage Example: Use this metric for daily cost assessments per trunk. It aids in identifying trends and making informed decisions regarding trunk usage.

.. raw:: html

   <a id="didww_event_api_queue_size"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>9. didww_event_api_queue_size</b></p>

Indicates the current size of the event API queue.

   - Sample Output:

     .. code-block::

         didww_event_api_queue_size 42

   - Usage Example: This metric is useful for monitoring the event processing backlog. A growing queue size can indicate processing delays or issues with event handling.

.. raw:: html

   <a id="didww_event_api_sent"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>10. didww_event_api_sent</b></p>

Shows the total number of events successfully sent.

    - Sample Output:

      .. code-block::

          didww_event_api_sent 10500

    - Usage Example: This metric is helpful for tracking the volume of events sent over time, allowing you to gauge system activity and throughput.

.. raw:: html

   <a id="didww_event_api_responses"></a>
   <p style="font-size: 1.2em; font-weight: bold;"><b>11. didww_event_api_responses</b></p>

Displays the number of responses received, categorized by HTTP status code.

    - Sample Output:

      .. code-block::

          didww_event_api_responses{status_code="200"} 9800
          didww_event_api_responses{status_code="404"} 15
          didww_event_api_responses{status_code="500"} 5

    - Usage Example: Use this metric to monitor event API response success and error rates. It helps in identifying response trends, such as frequent errors, that may require further investigation.

.. raw:: html

   <br>

Visualizing Metrics
-------------------

To visualize metrics, you can use Prometheus's built-in expression browser by selecting **Graph** from the top menu, entering an expression, and clicking **Execute** to display results as a graph or table. Alternatively, you can integrate Prometheus with a visualization tool such as Grafana. For additional guidance on setting up visualizations, refer to the `Prometheus Visualization documentation <https://prometheus.io/docs/visualization/browser/>`_.

.. figure:: https://doc.didww.com/_images/visualizing_in_prometheus.png
    :figclass: align-center
    :alt: Visualizing Graphs in Prometheus
    :width: 100%

    **Fig. 3.** Visualizing Graphs in Prometheus

----

.. raw:: html

   <br>

Setup and Configuration
-----------------------

To start using the DIDWW Prometheus exporter, follow these steps:

1. Install the Prometheus Server
""""""""""""""""""""""""""""""""

Ensure that the Prometheus server is installed and operational. Installation instructions are available on the `Prometheus website <https://prometheus.io/docs/prometheus/latest/getting_started/>`_.

2. Get an API Security Key
""""""""""""""""""""""""""

Generate a dedicated API security key for your Prometheus server in your DIDWW account. For enhanced security, it is highly recommended to set the Access IPs field to your Prometheus server's IP address. See the `API section <https://doc.didww.com/api3/configuration.html#user-panel-api>`_ for instructions on obtaining an API key.

To verify connectivity between your Prometheus server and the DIDWW Prometheus exporter, use the following `curl` command (replacing ``<API_KEY>`` with your actual API key):

   .. code-block:: bash

      curl -m 10 -sSv -H 'Authorization: Bearer <API_KEY>' https://metrics.didww.com/metrics

3. Configure the Prometheus Server
""""""""""""""""""""""""""""""""""

Add the following job configuration to your ``prometheus.yml`` file:

   .. code-block:: yaml

      - job_name: didww-metrics
        scrape_interval: 30s
        scrape_timeout: 10s
        # honor_timestamps must not be "false"
        honor_timestamps: true
        scheme: https
        authorization:
           credentials: "<API_KEY>"
        static_configs:
          - targets:
              - metrics.didww.com:443

.. note::

 Replace ``<API_KEY>`` with the API key obtained from your DIDWW account.

4. Save the Settings and Restart Prometheus
"""""""""""""""""""""""""""""""""""""""""""

After configuring Prometheus, save the configuration file and restart the Prometheus service using the appropriate command. For example, if you’re using Homebrew services, restart Prometheus with:

   .. code-block:: bash

      brew services restart prometheus

Once Prometheus is running, open the web interface by navigating to, for example, `http://<yourhostnameaddress>:9090` in your web browser. You should see this target available on the **Status -> Targets** page. If the connection is successful, the **State** will display as **Up**.

.. note::
   If any issues arise, check the Prometheus log file for debugging. Common log file locations include:

   - `/var/log/prometheus/prometheus.log` on Linux systems
   - `/usr/local/var/log/prometheus.log` on macOS
   - A custom path specified in your Prometheus configuration file

.. figure:: https://doc.didww.com/_images/didww_exported_prometheus_connected.png
    :figclass: align-center
    :alt: DIDWW Prometheus Exporter Target Connected
    :width: 100%

    **Fig. 2.** DIDWW Prometheus Exporter Target Connected

----

.. raw:: html

   <br>

:html_theme.sidebar_secondary.remove: true

=========
DIDWW MCP
=========

Connect a supported MCP client to your DIDWW account and use natural-language
requests to work with supported DIDWW services.

Basics & reference
==================

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: Overview
      :link: overview
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Understand what DIDWW MCP is, how it works, and when to use it.

   .. grid-item-card:: Getting started
      :link: getting-started
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Connect your MCP client and verify access to your DIDWW account.

   .. grid-item-card:: Connection details
      :link: connection-details
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Find the MCP server address and authorization requirements.

   .. grid-item-card:: Available tools
      :link: available-tools
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Review available tools, access types, and confirmation behavior.

Connect an MCP client
=====================

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: Connect Claude
      :link: how-to-guides/claude
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Connect Claude to your DIDWW account.

   .. grid-item-card:: Connect ChatGPT
      :link: how-to-guides/chatgpt
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Connect ChatGPT to your DIDWW account.

   .. grid-item-card:: Connect Perplexity
      :link: how-to-guides/perplexity
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Connect Perplexity to your DIDWW account.

Services & features
====================

Choose a service area to review available actions, example requests,
confirmation requirements, and current limitations.

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: Phone numbers
      :link: work-with-didww-mcp/phone-numbers
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Find, purchase, review, and manage DID numbers.

   .. grid-item-card:: Inbound routing
      :link: work-with-didww-mcp/inbound-routing
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Manage inbound trunks, groups, number assignments, and number lists.

   .. grid-item-card:: Messaging
      :link: work-with-didww-mcp/messaging
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Manage SMS trunks, groups, routing, and DID assignments.

   .. grid-item-card:: Capacity
      :link: work-with-didww-mcp/voice-capacity
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Review capacity, purchase channels, and manage assignments.

   .. grid-item-card:: Billing and payments
      :link: work-with-didww-mcp/billing-and-payments
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Review balances, invoices, orders, payments, refunds, and saved payment
      methods.

   .. grid-item-card:: Exports
      :link: work-with-didww-mcp/data-exports
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Prepare and download call, SMS, DID, order, and payment exports.

   .. grid-item-card:: Compliance and verification
      :link: work-with-didww-mcp/compliance-and-verification
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Manage identities, addresses, documents, and registration verifications.

   .. grid-item-card:: Emergency calling
      :link: work-with-didww-mcp/emergency-calling
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Review requirements, create supported services, and submit or resubmit
      emergency verifications.

   .. grid-item-card:: Users and invitations
      :link: work-with-didww-mcp/users-and-invitations
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Review account users and manage supported user invitations.

Security & support
====================

.. grid:: 1 1 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: Privacy and data handling
      :link: privacy-and-data-handling
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Understand how account information, credentials, documents, and exports
      are handled.

   .. grid-item-card:: Troubleshooting
      :link: troubleshooting
      :link-type: doc
      :text-align: left
      :class-card: sd-card-single sd-card-mcp

      Resolve common connection, authorization, account, and request issues.

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Basics & reference

   overview
   Getting started <getting-started>
   Connection details <connection-details>
   Available tools <available-tools>

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Connect an MCP client

   Connect Claude <how-to-guides/claude>
   Connect ChatGPT <how-to-guides/chatgpt>
   Connect Perplexity <how-to-guides/perplexity>

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Services & features

   Phone numbers <work-with-didww-mcp/phone-numbers>
   Inbound routing <work-with-didww-mcp/inbound-routing>
   Messaging <work-with-didww-mcp/messaging>
   Capacity <work-with-didww-mcp/voice-capacity>
   Billing and payments <work-with-didww-mcp/billing-and-payments>
   Exports <work-with-didww-mcp/data-exports>
   Compliance and verification <work-with-didww-mcp/compliance-and-verification>
   Emergency calling <work-with-didww-mcp/emergency-calling>
   Users and invitations <work-with-didww-mcp/users-and-invitations>

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Security & support

   Privacy and data handling <privacy-and-data-handling>
   Troubleshooting <troubleshooting>


==================
Overview
==================

DIDWW MCP connects compatible MCP clients to your DIDWW account. It lets
you use natural-language requests to review account information and complete
supported DIDWW tasks while retaining your existing account permissions and
confirmation requirements.

What is DIDWW MCP?
==================

`Model Context Protocol (MCP)
<https://modelcontextprotocol.io/docs/getting-started/intro>`_ is an open
standard that allows an MCP client to request information or actions from a
connected service. DIDWW MCP provides this connection for supported areas of
your DIDWW account.

You can ask the MCP client for an outcome instead of navigating each
account area manually. For example, you can ask it to find an available number,
review routing information, check your balance, or prepare an export. The MCP
client interprets your request and uses only the DIDWW actions available
to the connected user.

.. note::

    DIDWW MCP is intended for customer account use. It does not replace the DIDWW
    API for building custom software integrations.

How the connection works
========================

The connection uses OAuth authorization. After you add or select DIDWW in a
compatible MCP client, your browser opens the DIDWW authorization page. Sign in
to the DIDWW User Panel and review the connection request.

After you approve the connection:

- the MCP client acts as the DIDWW user who approved it
- your User Panel roles determine which information and actions are available
- the connection can access only accounts available to that user
- you can switch between accessible accounts
- the connection appears under **Account Settings** > **MCP Clients**

Your DIDWW password, API key, and two-factor authentication code are not
entered in the MCP client conversation.

See :doc:`Connection details <connection-details>` for the connection type,
server address, and authorization requirements.

What you can do
===============

DIDWW MCP supports the following service areas. Available actions depend on
the active account, assigned roles, enabled services, and service availability.

See :doc:`Available tools <available-tools>` for exact tool names, access
types, and DIDWW confirmation requirements.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Service area
     - Available actions
   * - :ref:`Accounts <mcp-multiple-accounts>`
     - List accessible DIDWW accounts, review the active account, and switch the
       active account.
   * - :doc:`Phone numbers <work-with-didww-mcp/phone-numbers>`
     - Search coverage, review pricing, purchase DID numbers, manage supported
       settings and renewals, terminate numbers, and restore terminated
       numbers.
   * - :doc:`Inbound routing <work-with-didww-mcp/inbound-routing>`
     - Create and manage SIP, PSTN, and phone.systems™ trunks, assign DID
       numbers, configure number lists, and use trunk groups for failover or
       load balancing.
   * - :doc:`Messaging <work-with-didww-mcp/messaging>`
     - Create and manage inbound SMS trunks and groups, assign supported DID
       numbers, and configure incoming SMS routing to an HTTP endpoint or email
       address.
   * - :doc:`Capacity <work-with-didww-mcp/voice-capacity>`
     - Review supported capacity, purchase channels, assign channels, and
       manage capacity groups.
   * - :doc:`Billing and payments
       <work-with-didww-mcp/billing-and-payments>`
     - Review balances, invoices, orders, payments, refunds, and masked
       saved-card information. Billing information is read-only.
   * - :doc:`Exports <work-with-didww-mcp/data-exports>`
     - Prepare and download supported call-record, SMS-log, DID-number, order,
       and payment exports.
   * - :doc:`Compliance and verification
       <work-with-didww-mcp/compliance-and-verification>`
     - Review registration requirements, manage identities and addresses,
       upload documents securely, and review or submit supported verifications.
   * - :doc:`Emergency calling <work-with-didww-mcp/emergency-calling>`
     - Review requirements and pricing, create supported services, and submit
       or resubmit emergency verifications.
   * - :doc:`Users and invitations
       <work-with-didww-mcp/users-and-invitations>`
     - Review users, roles, and pending invitations, create invitations, and
       cancel pending invitations.

.. note::

   Use the DIDWW User Panel when an action is not available through MCP. See
   :ref:`Troubleshooting <mcp-troubleshooting>` for help resolving access and
   availability problems.

Permissions and account access
==============================

DIDWW MCP uses the roles and permissions assigned to your DIDWW user.
Connecting an MCP client does not grant additional access or bypass
existing account controls.

If you have access to multiple DIDWW accounts, the connection uses one active
account at a time. Changing the active account also changes the records and
actions available to the MCP client.

An action may be unavailable when:

- your user role does not include the required permission
- the service or product is not enabled for the active account
- the requested record belongs to another account
- an account limit or service requirement prevents the action

.. note::

   Account owners and administrators can review user roles and manage account
   access in the DIDWW User Panel. See :doc:`Users and roles
   <../account-settings/adding-new-roles>`.

.. _mcp-money-confirmations-and-safety:

Money, confirmations, and safety
================================

DIDWW MCP distinguishes between immediate purchases, usage-based services, and
account changes that do not create a charge. Protected actions use a two-step
confirmation process so that you can review the result before DIDWW applies it.

Actions that purchase a service
-------------------------------

The following actions purchase DIDWW telecommunications services using funds
already available in the active account's prepaid balance. Funds must be added
separately through the DIDWW User Panel.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Action
     - Purchase preview
   * - Purchase phone numbers
     - Shows the selected phone numbers or requested quantity, availability,
       one-time setup charges, recurring charges, and included capacity. It
       also identifies numbers that will be supplied later when they are not
       immediately available.
   * - Purchase additional flat-rate channels
     - Shows the selected capacity pool, number of channels, applicable price,
       renewal information, and active DIDWW account.

Review the purchase preview carefully. DIDWW completes the purchase from the
prepaid balance only after you confirm it.

.. note::

   DIDWW MCP cannot charge a saved payment card, add funds to the account, or
   manage saved payment methods. If the balance is insufficient, add funds in
   the DIDWW User Panel and request a new purchase preview.

Usage-based PSTN trunks
-----------------------

A PSTN trunk forwards incoming calls from a DID number to a telephone number.
Creating the trunk does not charge your account.

Before creating a PSTN trunk, DIDWW shows the per-minute forwarding rate or
rate range for the selected destination. You must confirm this rate before
DIDWW creates the trunk. Confirming the rate does not generate a charge.

Usage charges begin only when an incoming call is forwarded through the PSTN
trunk. If the trunk does not forward a call, no per-minute forwarding charge
is generated.

Changing the PSTN destination also requires confirmation of the rate for the
new destination. If DIDWW cannot determine a rate, the trunk is not created or
updated.

Capacity assignments
--------------------

Assigning purchased flat-rate channels as dedicated or shared capacity does not
purchase more channels. Creating a capacity group also does not purchase
capacity.

Metered channels provide pay-per-minute capacity through a capacity group.
Usage charges apply only when an incoming call uses a metered channel.

See :doc:`Capacity <work-with-didww-mcp/voice-capacity>` for capacity
types, assignments, priority, and example requests.

Protected actions
-----------------

DIDWW uses two-step confirmation for supported purchases, usage-rate
acceptance, destructive actions, user invitations, and other significant
account changes.

The first request presents a preview and does not change the account. Review
the active account, affected resources, prices, recurring charges, usage
rates, and consequences before confirming.

See :doc:`Available tools <available-tools>` for the complete list of actions
and their DIDWW confirmation requirements.

How two-step confirmation works
-------------------------------

A protected action follows this sequence:

#. You explicitly request the action.
#. DIDWW prepares a preview of what will be purchased, created, changed,
   restored, terminated, or removed. Nothing has changed yet.
#. The MCP client presents the preview and waits for your decision.
#. You review the active account, affected resources, prices, recurring
   charges, usage rates, and consequences.
#. You confirm or reject the action.
#. After confirmation, DIDWW completes the action and returns the result.

A confirmation applies only to the action described in its preview. If a
protected value changes, such as the selected resource, quantity, destination,
price, or rate, DIDWW requires a new preview and confirmation.

A confirmation can be applied only once. Reusing the same confirmation does
not repeat the purchase, deletion, or other protected action.

If the connection is interrupted after confirmation, DIDWW returns the stored
result when the same confirmation is received again. Before starting a new
request, ask the MCP client to check the relevant account records to
confirm whether the action completed.

If a confirmation expires, the MCP client checks the relevant phone
numbers, orders, payments, services, or other records before preparing another
preview.

.. note::

   An MCP client can display its own tool-approval request before contacting
   DIDWW. The MCP client approval is separate from the DIDWW preview and
   confirmation.

Read-only requests
------------------

DIDWW MCP uses read-only actions when you ask only for information. It does not
purchase, create, update, assign, restore, terminate, or delete a resource
unless you explicitly request that action in the current conversation.

For example:

- finding phone numbers does not purchase them
- reviewing capacity does not purchase channels
- reviewing a PSTN rate does not create a trunk
- reviewing an identity or address does not submit a verification
- reviewing a resource does not delete it

When another account change is required to complete a request, the MCP client
explains the required change and waits for your instruction.

DIDWW MCP does not schedule actions, create timers, or perform recurring
account changes later.

.. warning::

   MCP clients can make mistakes. Before confirming an action, verify the
   active DIDWW account, phone numbers, quantities, destinations, prices, usage
   rates, recurring charges, and affected resources.

Privacy and data handling
=========================

Learn what DIDWW account information can be shared through an MCP client, how
protected information and documents are handled, and how to review or revoke
connected clients.

See :doc:`Privacy and data handling <privacy-and-data-handling>`.

Request and account limits
==========================

- Requests are measured separately for each connected client. When the request
  rate is exceeded, DIDWW returns the number of seconds to wait.
- Access tokens expire after two hours. The MCP client refreshes them
  automatically while the connection remains valid.
- An MCP client can cache available actions for up to one hour.
- List requests are paginated. The default and maximum page size depend on the
  requested information, and every list response reports the page size that was
  applied.
- One bulk phone-number assignment can include up to 100 numbers.
- DIDWW account quotas continue to apply to trunks, groups, messaging
  resources, capacity groups, and other account resources.

.. note::

    Use filters or supported data exports for large datasets. When an account quota
    is reached, remove an unused resource or contact DIDWW Customer Support.

Supported MCP clients
=====================

DIDWW provides connection guides for Claude, ChatGPT, and Perplexity. Other
compatible remote MCP clients may also connect.

See :doc:`Connection details <connection-details>` for supported clients,
platforms, and connection requirements.

Troubleshooting
===============

Resolve common connection, authorization, account, upload, export, and
request-limit issues.

See :doc:`Troubleshooting DIDWW MCP <troubleshooting>`.


.. _mcp-available-tools:

===============
Available tools
===============

DIDWW MCP currently exposes 81 purpose-built tools. The MCP client chooses the
appropriate tool from a natural-language request, so the tool names do not
normally need to be included in a conversation.

This reference lists the exact tool names, their customer-facing purpose, the
type of access they require, and whether DIDWW uses an additional confirmation
before applying the action.

Access and confirmation
=======================

The **Access** column uses the following values:

- **Read-only** retrieves information without changing the DIDWW account.
- **Session** changes only the active account used by the current MCP session.
- **Write** creates, updates, assigns, submits, or cancels account data.
- **Write, purchase** purchases a DIDWW service from the active account's
  prepaid balance.
- **Write, destructive** terminates or deletes a resource.
- **Write, external action** sends an invitation email to another person.

The **DIDWW confirmation** column describes DIDWW's server-side confirmation.
This is separate from any tool approval displayed by the MCP client.

- **Yes** means the first request returns a preview and changes nothing. The
  action is applied only after the preview is confirmed.
- **Conditional** means confirmation is required only when the requested
  change has the effect described in the tool's purpose.
- **No** means DIDWW does not present a separate server-side preview. The
  action may be applied when the MCP client calls the tool.

.. note::

   Tool availability is evaluated for the active DIDWW account. The account's
   roles, enabled services, record ownership, and the requested arguments can
   prevent a tool from completing an action. Account tools identify actions
   that the active account cannot use.

Account selection
=================

See :ref:`Multiple accounts <mcp-multiple-accounts>` for account selection and
permission behavior.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_accounts``
     - **List available accounts.** Lists every DIDWW account available to the
       signed-in user, including the roles held on each account, unavailable
       tools, and whether the account is currently active.
     - Read-only
     - No
   * - ``current_account``
     - **Show the active account.** Returns the DIDWW account currently used by
       the MCP session, including its roles and unavailable tools.
     - Read-only
     - No
   * - ``switch_account``
     - **Switch the active account.** Changes the DIDWW account used for later
       requests and returns the selected account's roles and unavailable tools.
     - Session
     - No

.. _mcp-available-tools-dids:

Phone number coverage and DIDs
==============================

See :doc:`Phone numbers <work-with-didww-mcp/phone-numbers>` for customer
workflows and limitations.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``search_coverage``
     - **Search DID coverage.** Finds DID groups and SKUs by country, city,
       region, prefix, number type, or supported feature. Returns pricing,
       included channels, registration requirements, availability, and
       back-ordering information.
     - Read-only
     - No
   * - ``list_dids``
     - **List DIDs.** Lists the active account's phone numbers and supports
       filters for number, country, DID group, and status.
     - Read-only
     - No
   * - ``get_did``
     - **Get a DID.** Returns routing, capacity, verification, billing, and
       other supported details for one phone number.
     - Read-only
     - No
   * - ``get_did_history``
     - **Get DID history.** Returns purchase, renewal, cancellation,
       restoration, stock-removal, and renewal-setting events from the last
       90 days for one phone number.
     - Read-only
     - No
   * - ``buy_did``
     - **Buy DID.** Purchases one or more phone numbers from the active
       account's prepaid balance after showing availability, charges, service
       restrictions, and any delayed provisioning. Back-ordering is allowed
       by default unless explicitly disabled.
     - Write, purchase
     - Yes
   * - ``update_did``
     - **Update DID renewal or emergency assignment.** Continues automatic
       monthly renewal, limits renewal to a specified number of additional
       cycles, or stops renewal at the current expiration date. A stopped
       renewal can be resumed before expiration. The tool can also remove the
       DID from its emergency calling service, stopping that number's charge
       from the next renewal. A service with no remaining numbers is
       automatically canceled within a few hours, and DIDWW notifies the
       customer. Returns the resulting expiration date and renewal setting.
     - Write
     - No
   * - ``delete_did``
     - **Terminate a DID.** Immediately stops incoming calls and SMS and
       removes the number from active service. Stopping renewal with
       ``update_did`` is the preferred reversible alternative when the
       customer only wants to stop future payments. A terminated number can
       generally be restored for approximately 35 days before it returns to
       public stock. A number on a pending order is canceled with a refund
       instead. Bulk Order numbers cannot be terminated through this action.
     - Write, destructive
     - Yes
   * - ``restore_did``
     - **Restore a terminated DID.** Restores a recently terminated phone
       number. An expired number requires a paid renewal and confirmation
       before it can be restored.
     - Write
     - Conditional

Inbound voice routing
=====================

See :doc:`Inbound routing <work-with-didww-mcp/inbound-routing>` for trunk,
group, assignment, and number-list behavior.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_trunks``
     - **List inbound trunks.** Lists SIP, PSTN, phone.systems™, and trunk-group
       routing destinations, including supported filters and DID-assignment
       counts.
     - Read-only
     - No
   * - ``get_trunk``
     - **Get an inbound trunk.** Returns the supported configuration and DID
       assignments for one trunk. Password values are never returned.
     - Read-only
     - No
   * - ``create_sip_trunk``
     - **Create a SIP inbound trunk.** Creates an inbound SIP destination
       using a fixed host or SIP-registration mode. Registration credentials
       are generated by DIDWW and returned with the password masked.
     - Write
     - No
   * - ``update_sip_trunk``
     - **Update a SIP inbound trunk.** Changes only the supplied SIP and
       routing settings. Changes can affect live incoming calls immediately,
       and returned passwords are masked.
     - Write
     - No
   * - ``create_pstn_trunk``
     - **Create a PSTN inbound trunk.** Creates a destination that forwards
       incoming calls to a telephone number. DIDWW shows the applicable
       per-minute rate before confirmation. The trunk cannot be created when
       no rate is available for the destination.
     - Write
     - Yes
   * - ``update_pstn_trunk``
     - **Update a PSTN inbound trunk.** Changes only the supplied settings.
       Changing the destination requires confirmation of its new per-minute
       rate. Other changes apply without a DIDWW confirmation.
     - Write
     - Conditional
   * - ``create_phone_systems_trunk``
     - **Create a phone.systems™ inbound trunk.** Creates an inbound route to
       the account's phone.systems™ cloud PBX. The phone.systems™ feature must
       be enabled for the active account.
     - Write
     - No
   * - ``update_phone_systems_trunk``
     - **Update a phone.systems™ inbound trunk.** Changes only the supplied
       settings of an existing phone.systems™ trunk.
     - Write
     - No
   * - ``assign_did_to_trunk``
     - **Assign DIDs to an inbound trunk.** Assigns, reassigns, or unassigns up
       to 100 phone numbers in one all-or-nothing operation. The destination
       can be a SIP, PSTN, phone.systems™, or trunk-group route.
     - Write
     - No
   * - ``delete_trunk``
     - **Delete an inbound trunk.** Permanently deletes an inbound trunk. A
       trunk assigned to a DID cannot be deleted.
     - Write, destructive
     - Yes
   * - ``list_trunk_groups``
     - **List inbound trunk groups.** Lists failover and load-balancing groups,
       their assigned-DID counts, and member trunks in routing order.
     - Read-only
     - No
   * - ``create_trunk_group``
     - **Create an inbound trunk group.** Creates a failover or load-balancing
       group containing up to 10 existing inbound trunks. Routing uses member
       priority and weight.
     - Write
     - No
   * - ``update_trunk_group``
     - **Update an inbound trunk group.** Changes supported group settings. A
       supplied member list replaces the complete existing list. Removed
       members are detached from the group but are not deleted.
     - Write
     - No
   * - ``delete_trunk_group``
     - **Delete an inbound trunk group.** Permanently deletes a group that has
       no assigned DIDs. Member trunks are detached and retained by default, or
       eligible members can also be permanently deleted.
     - Write, destructive
     - Yes
   * - ``list_voice_in_number_lists``
     - **List inbound number lists.** Lists caller-number filters, their
       matching modes, entry counts, and attached trunks. List entries are
       retrieved separately.
     - Read-only
     - No
   * - ``get_voice_in_number_list``
     - **Get an inbound number list.** Returns one caller-number filter and its
       stored entries. Entries are paginated and retain their exact stored
       values.
     - Read-only
     - No
   * - ``create_voice_in_number_list``
     - **Create an inbound number list.** Creates an allow or reject filter for
       full caller numbers or prefixes. The list does not affect calls until it
       is attached to a SIP or PSTN trunk.
     - Write
     - No
   * - ``update_voice_in_number_list``
     - **Update an inbound number list.** Changes list settings or atomically
       adds and removes entries. Removed entries must match their exact stored
       values. Changes immediately affect every attached trunk.
     - Write
     - No
   * - ``delete_voice_in_number_list``
     - **Delete an inbound number list.** Permanently deletes a number list and
       all its entries. A list attached to a trunk must be detached before it
       can be deleted.
     - Write, destructive
     - Yes

Messaging
=========

See :doc:`Messaging <work-with-didww-mcp/messaging>` for inbound SMS routing
workflows and limitations.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_sms_trunks``
     - **List SMS trunks.** Lists SMS trunks and SMS trunk groups, with
       supported filters for name and type.
     - Read-only
     - No
   * - ``get_sms_trunk``
     - **Get an SMS trunk.** Returns the supported configuration and DID
       assignments for one SMS trunk or group.
     - Read-only
     - No
   * - ``create_sms_trunk``
     - **Create an SMS trunk.** Creates an HTTP IN or SMS to Email destination
       for incoming messages.
     - Write
     - No
   * - ``update_sms_trunk``
     - **Update an SMS trunk.** Changes supported delivery settings for an
       existing SMS trunk.
     - Write
     - No
   * - ``delete_sms_trunk``
     - **Delete an SMS trunk.** Permanently deletes an eligible SMS trunk. A
       group deletion also deletes its member trunks.
     - Write, destructive
     - Yes
   * - ``assign_did_to_sms_trunk``
     - **Assign DIDs to an SMS trunk.** Assigns, reassigns, or unassigns up to
       100 SMS-enabled phone numbers in one all-or-nothing operation.
     - Write
     - No
   * - ``create_sms_trunk_group``
     - **Create an SMS trunk group.** Creates a group from existing inbound
       SMS trunks and their priorities.
     - Write
     - No
   * - ``update_sms_trunk_group``
     - **Update an SMS trunk group.** Changes the name or member trunks of an
       existing SMS trunk group.
     - Write
     - No

.. _mcp-available-tools-capacity:

Capacity
========

See :doc:`Capacity <work-with-didww-mcp/voice-capacity>` for capacity
types, assignments, and billing behavior.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_capacity_pools``
     - **List capacity pools.** Lists purchased channel pools, covered
       countries, renewal information, free channels, and metered rates.
     - Read-only
     - No
   * - ``buy_capacity_channels``
     - **Purchase capacity channels.** Purchases additional flat-rate channels
       for a capacity pool from the active account's prepaid balance.
     - Write, purchase
     - Yes
   * - ``list_capacity_groups``
     - **List capacity groups.** Lists shared capacity groups and the capacity
       pool used by each group.
     - Read-only
     - No
   * - ``create_capacity_group``
     - **Create a capacity group.** Creates a shared group using purchased
       channels and can enable metered, pay-per-use channels.
     - Write
     - Yes
   * - ``update_capacity_group``
     - **Update a capacity group.** Renames a group or changes its shared and
       metered channel limits. Increasing metered capacity requires a preview.
     - Write
     - Conditional
   * - ``delete_capacity_group``
     - **Delete a capacity group.** Deletes an empty group and returns its
       reserved shared channels to the capacity pool.
     - Write, destructive
     - Yes
   * - ``assign_did_to_capacity_group``
     - **Assign a DID to a capacity group.** Lets a phone number draw shared or
       metered channels from the group's capacity pool.
     - Write
     - No
   * - ``unassign_did_from_capacity_group``
     - **Unassign a DID from a capacity group.** Stops a phone number from
       drawing channels from its current shared capacity group.
     - Write
     - No
   * - ``assign_dedicated_channels_to_did``
     - **Manage dedicated channels.** Reserves purchased pool channels for one
       phone number or releases an existing reservation.
     - Write
     - No

Billing
=======

See :doc:`Billing and payments <work-with-didww-mcp/billing-and-payments>` for
available billing information and limitations.

All billing tools are read-only. DIDWW MCP cannot add funds, charge a saved
card, remove a saved card, or otherwise manage payment methods.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``get_balance``
     - **Get the balance.** Returns the active account's prepaid balance and
       supported billing-standing information.
     - Read-only
     - No
   * - ``get_dashboard``
     - **Get the account summary.** Returns a read-only summary of available
       account, service, and billing information.
     - Read-only
     - No
   * - ``list_invoices``
     - **List invoices.** Lists invoices and supports filtering by year and
       month.
     - Read-only
     - No
   * - ``get_invoice``
     - **Get an invoice.** Returns supported details for one invoice.
     - Read-only
     - No
   * - ``list_payments``
     - **List payments.** Lists completed and recorded payments for the active
       account.
     - Read-only
     - No
   * - ``list_orders``
     - **List orders.** Lists purchase orders, newest first.
     - Read-only
     - No
   * - ``list_refunds``
     - **List refunds.** Lists completed refunds that returned funds.
     - Read-only
     - No
   * - ``list_credit_cards``
     - **List saved cards.** Lists masked saved-card information without
       returning full card details.
     - Read-only
     - No

Compliance and verification
===========================

See :doc:`Compliance and verification
<work-with-didww-mcp/compliance-and-verification>` for the end-user
registration flow and secure document handling.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_requirements``
     - **List registration requirements.** Lists country and DID-type
       requirements, required fields, proof types, and whether each requirement
       applies to the active account.
     - Read-only
     - No
   * - ``list_identities``
     - **List identities.** Lists end-user identities and supported proof
       information.
     - Read-only
     - No
   * - ``create_identity``
     - **Create an identity.** Creates a personal or business identity for the
       actual end user, who may be the DIDWW customer's subscriber. Use the
       identity type and required fields from the registration requirement.
       Business identities require a company name and authorized representative.
       Provide verified information only. The identity can be validated before
       proof documents are uploaded securely and its address is created.
     - Write
     - No
   * - ``update_identity``
     - **Update an identity.** Changes supported identity fields needed by a
       registration or emergency requirement.
     - Write
     - No
   * - ``delete_identity``
     - **Delete an identity.** Permanently deletes an eligible identity with all
       its addresses and stored documents. Deletion is blocked for a system
       identity, one linked to a phone number, one with a new or pending address
       verification, or one used by an unfinished emergency calling service or
       SMS campaign. Permanent supporting documents require compliance
       permission. The response identifies the applicable blocker.
     - Write, destructive
     - Yes
   * - ``list_addresses``
     - **List addresses.** Lists end-user addresses and supported proof
       information.
     - Read-only
     - No
   * - ``create_address``
     - **Create an address.** Creates an address under an existing end-user
       identity.
     - Write
     - No
   * - ``update_address``
     - **Update an address.** Changes supported address fields.
     - Write
     - No
   * - ``delete_address``
     - **Delete an address.** Permanently deletes an eligible address and its
       stored proof documents.
     - Write, destructive
     - Yes
   * - ``validate_address``
     - **Validate an address.** Checks an address and its identity against a
       registration or emergency requirement without changing account data.
     - Read-only
     - No
   * - ``create_regulation_upload_link``
     - **Create a requirement-based upload link.** Creates a one-time browser
       link for missing documents and can submit the related verification after
       upload.
     - Write
     - No
   * - ``create_proof_upload_link``
     - **Create a proof upload link.** Creates a one-time browser link for
       explicitly selected identity or address proof types.
     - Write
     - No
   * - ``check_upload_status``
     - **Check upload status.** Shows whether a secure upload is pending,
       completed, or expired and identifies records created on completion.
     - Read-only
     - No
   * - ``delete_proof``
     - **Delete a proof document.** Permanently removes an eligible stored
       proof document.
     - Write, destructive
     - Yes
   * - ``create_address_verification``
     - **Submit an address verification.** Submits eligible phone numbers for
       registration review when all required documents already exist.
     - Write
     - No
   * - ``list_address_verifications``
     - **List address verifications.** Lists verification statuses and
       available rejection information.
     - Read-only
     - No

Emergency calling
=================

See :doc:`Emergency calling <work-with-didww-mcp/emergency-calling>` for the
currently documented customer workflow.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_emergency_requirements``
     - **List emergency requirements.** Returns identity and address
       requirements and available pricing for emergency calling.
     - Read-only
     - No
   * - ``list_emergency_calling_services``
     - **List emergency services.** Lists existing emergency calling services,
       assigned phone numbers, prices, and verification statuses.
     - Read-only
     - No
   * - ``create_emergency_verification``
     - **Submit an emergency verification.** Submits a new service for staff
       review or resubmits an existing service. New-service mode requires a
       cost preview and confirmation, but billing begins only after staff
       activates the service. Resubmission adds no charge and is not
       confirmation-gated.
     - Write
     - Conditional

Exports
========

See :doc:`Exports <work-with-didww-mcp/data-exports>` for supported export
types, date limits, and download behavior.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``create_export``
     - **Create an export.** Starts an asynchronous CSV export for supported
       call records, SMS logs, DIDs, orders, or payments.
     - Write
     - No
   * - ``get_export``
     - **Get an export.** Returns the status of one export and its download
       link after completion.
     - Read-only
     - No
   * - ``list_exports``
     - **List exports.** Lists recent exports and supports filtering by type or
       status.
     - Read-only
     - No

Users and invitations
=====================

See :doc:`Users and invitations
<work-with-didww-mcp/users-and-invitations>` for permissions, privacy
considerations, and limitations.

.. list-table::
   :header-rows: 1
   :widths: 25 50 13 12

   * - Tool
     - Purpose
     - Access
     - DIDWW confirmation
   * - ``list_user_accesses``
     - **List account users.** Lists users who can access the active DIDWW
       account and their assigned roles.
     - Read-only
     - No
   * - ``list_invite_requests``
     - **List pending invitations.** Lists invitations that have not yet been
       accepted or canceled.
     - Read-only
     - No
   * - ``create_invite_request``
     - **Invite a user.** Creates a pending invitation and sends an email after
       the email address and assigned roles are confirmed.
     - Write, external action
     - Yes
   * - ``cancel_invite_request``
     - **Cancel a pending invitation.** Invalidates an unanswered invitation
       so that it can no longer be accepted.
     - Write
     - No



DIDWW MCP connection details
============================

Use the following details to connect an MCP client to DIDWW.

Connection information
----------------------

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Setting
     - Value
   * - Connection name
     - **DIDWW**
   * - MCP server address
     - ``https://api.didww.com/mcp``
   * - Connection type
     - **Streamable HTTP with OAuth**
   * - Authorization
     - Sign in and approve the connection through the DIDWW authorization page.
   * - API key
     - Not required.
   * - Client credentials
     - Not required.

The MCP client registers automatically during the first connection. A client ID
and client secret are not required.

.. note::

   Only use an MCP server address published by DIDWW.

Supported MCP clients
---------------------

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Client
     - Availability
   * - :doc:`Claude <how-to-guides/claude>`
     - Supported in the Claude web application (``claude.ai``) and Claude
       Desktop.
   * - :doc:`ChatGPT <how-to-guides/chatgpt>`
     - Supported.
   * - :doc:`Perplexity <how-to-guides/perplexity>`
     - Supported on plans that allow custom connectors. A custom connector can
       be added only in the Perplexity web application.
   * - Other remote MCP clients
     - May connect when they support Streamable HTTP with OAuth. Enter the
       DIDWW MCP server address and complete authorization in the browser.

Availability may depend on the MCP client, plan, platform, and support for
remote OAuth-protected MCP servers. A client that cannot connect directly to a
remote MCP server requires a local MCP bridge.

Authorization
-------------

After the MCP client connects to the server address, the DIDWW authorization
page opens in a browser. Sign in with the DIDWW User Panel credentials,
complete two-factor authentication when required, and approve the connection.

.. warning::

   Enter your DIDWW password only on a DIDWW sign-in page. Do not provide your
   password, API key, or two-factor authentication code in an MCP client
   conversation.

Account access
--------------

The connection is associated with the DIDWW user who authorizes it. The MCP
client can access only:

- DIDWW accounts available to that user
- information permitted by the user's existing access
- actions permitted by the user's existing roles

The active account determines which information, services, and actions are
available to the MCP client.

.. _mcp-multiple-accounts:

Multiple accounts
-----------------

If your DIDWW login can access more than one account, the following account
actions are always available regardless of your role:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - Purpose
   * - List accounts
     - Shows the DIDWW accounts available to your login.
   * - Review the active account
     - Shows which DIDWW account the MCP client is currently using.
   * - Switch accounts
     - Selects another accessible account for subsequent DIDWW requests in the
       current conversation.

Permissions are evaluated separately for each DIDWW account. Switching
accounts can therefore change the information and actions available to the MCP
client.

Switching accounts does not grant new roles or permissions. The connection
uses the roles assigned to your user for the selected account.

To select the required account, you can ask the MCP client to:

#. Show the DIDWW accounts available to your user.
#. Switch to the account you want to use.
#. Confirm the active account before reviewing information or making changes.

For example:

.. code-block:: text

   Show the DIDWW accounts available to me.
   Do not switch accounts yet.

After selecting the required account:

.. code-block:: text

   Switch to the DIDWW account named Example Account.
   Confirm the active account before making any other changes.

.. _mcp-manage-connection:

Manage the connection
---------------------

To review connected MCP clients in the DIDWW User Panel:

#. Open the account switcher in the upper-right corner.
#. Select **Account Settings**.
#. Select the **MCP Clients** tab.

To disconnect an MCP client, select **Revoke** for the relevant client, or
select **Revoke all** to disconnect every listed client.

A connection that remains unused for 30 days requires DIDWW authorization
again the next time it is used. Follow the browser authorization process to
reconnect the MCP client.

.. note::

    A revoked connection cannot be restored. To use the MCP client again, select
    or add the DIDWW connection in the client and complete the DIDWW authorization
    process again.

Privacy and security
--------------------

Information returned through DIDWW MCP is also processed by the connected AI
provider under its terms and privacy policy.

See :doc:`Privacy and data handling <privacy-and-data-handling>` for details.
For information about how DIDWW processes personal data, see the `DIDWW
Privacy Notice <https://www.didww.com/privacy-notice>`_.



Getting started
===============

Connect a supported MCP client to DIDWW and complete a first account request.

Before you begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `create a DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- A supported MCP client that can connect to remote MCP servers using
  Streamable HTTP with OAuth is required.
- Your DIDWW user must have permission to perform the account tasks you intend
  to request.
- Access to your two-factor authentication method is required when two-factor
  authentication is enabled for your DIDWW user.

See :doc:`DIDWW MCP connection details <connection-details>` for supported MCP
clients and connection requirements.

Connect DIDWW MCP
-----------------

Connection settings differ between MCP clients. For client-specific
instructions, see:

- :doc:`Connect Claude to DIDWW <how-to-guides/claude>`
- :doc:`Connect ChatGPT to DIDWW <how-to-guides/chatgpt>`
- :doc:`Connect Perplexity to DIDWW <how-to-guides/perplexity>`

Other MCP clients may connect when they support remote MCP connections using
Streamable HTTP with OAuth.

To connect DIDWW:

#. Open the integrations, connectors, or MCP settings in your MCP client.
#. Choose the option to add a remote MCP server, custom MCP server, or
   connector.
#. Enter **DIDWW** as the connection name.
#. Enter the server address from :doc:`DIDWW MCP connection details
   <connection-details>`.
#. Start the connection.

The MCP client opens the DIDWW authorization page in your browser.

Authorize the connection
------------------------

The authorization page uses the DIDWW account from your current User Panel
browser session. It does not provide an account picker.

#. Sign in to the DIDWW User Panel if you are not already signed in.
#. Complete two-factor authentication when required.
#. Confirm the name of the MCP client requesting access.
#. Review the DIDWW account, user, and assigned roles shown on the page.
#. Read the information under **Before you connect an AI assistant**.
#. Select **I understand and accept**.
#. Select **Authorize**.
#. After authorization is complete, return to the MCP client.

The **Authorize** button remains unavailable until you accept the connection
notice.

Verify the connection
---------------------

After returning to the MCP client, verify that it uses the expected DIDWW
account.

Make a read-only request:

.. code-block:: text

   Which DIDWW account is currently active?

If prompted, review and approve the MCP client's request to access DIDWW.
Confirm that the response identifies the expected account.

.. note::

   An approval displayed by the MCP client is separate from a DIDWW
   confirmation required for a purchase, deletion, or another protected action.

.. dropdown:: Use another DIDWW account

   If the DIDWW user can access multiple accounts, ask:

   .. code-block:: text

      List the DIDWW accounts I can access.
      Do not switch accounts.

   To select another account, ask:

   .. code-block:: text

      Switch to the DIDWW account named Example Company.
      Confirm the active account before making any changes.

   Permissions are evaluated separately for each account. Switching accounts
   can change the information and actions available to the MCP client.

.. dropdown:: Try another read-only request

   Review the account balance:

   .. code-block:: text

      Show my DIDWW account balance.
      Do not make any changes.

   Or search for phone numbers:

   .. code-block:: text

      Find available geographic phone numbers in Ireland.
      Do not purchase anything.

Understand confirmations
------------------------

.. important::

   DIDWW presents a preview and requires confirmation before an action charges
   the account, creates a recurring charge, purchases a service, deletes or
   terminates a resource, or makes another significant account change.

   Review the preview before confirming. Requesting information does not
   authorize a purchase or account change.

See :ref:`Money, confirmations, and safety
<mcp-money-confirmations-and-safety>` for protected actions, purchase previews,
usage rates, and the two-step confirmation process.

Manage the connection
---------------------

To review or disconnect MCP clients:

#. Sign in to the DIDWW User Panel.
#. Open the account switcher in the upper-right corner.
#. Select **Account Settings**.
#. Select the **MCP Clients** tab.

Select **Revoke** to disconnect a specific MCP client. Select **Revoke all** to
disconnect every listed MCP client.

.. note::

   A revoked connection cannot be restored. To use the MCP client again,
   reconnect DIDWW and complete the browser authorization process.

Related resources
-----------------

- :doc:`Privacy and data handling <privacy-and-data-handling>`
- :doc:`Troubleshooting DIDWW MCP <troubleshooting>`




Connect ChatGPT to DIDWW
========================

Connect ChatGPT to your DIDWW account to review account information and request
supported DIDWW actions from a conversation. You authorize the connection using your existing DIDWW User Panel access.

The same connection steps apply to personal and managed ChatGPT accounts when
Developer mode and custom MCP servers are available.

For current ChatGPT instructions, see the `official OpenAI guide for connecting
an MCP server <https://developers.openai.com/plugins/deploy/connect-chatgpt>`_.

.. important::

   The ChatGPT Free plan does not support completing DIDWW purchases with
   ``buy_did`` or ``buy_capacity_channels``.

   This limitation applies only to these two purchase actions. Other supported
   DIDWW actions remain available on ChatGPT Free plan. To purchase phone numbers or
   capacity channels, use an eligible paid ChatGPT plan or complete the
   purchase in the DIDWW User Panel.

   For action details, see :ref:`Phone number coverage and DIDs
   <mcp-available-tools-dids>` and :ref:`Capacity
   <mcp-available-tools-capacity>`.

Before you begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `create a DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- Access to a ChatGPT account or workspace that supports custom MCP servers is
  required.
- The DIDWW MCP server address is required. See :doc:`DIDWW MCP connection
  details <../connection-details>`.
- Access to your DIDWW two-factor authentication method is required when
  two-factor authentication is enabled.

.. note::

   Developer mode and custom MCP server availability depend on your ChatGPT
   account and workspace policy. If the required options are unavailable in a
   managed workspace, contact your workspace administrator.

   If DIDWW is already available under **Plugins**, skip Steps 1 and 2 and
   continue with Step 3.

Step 1. Enable Developer mode
-----------------------------

#. Sign in to `ChatGPT <https://chatgpt.com>`_.
#. Open your profile menu.
#. Select **Settings**.
#. Select **Security and login**.
#. Enable **Developer mode**.

Enabling Developer mode makes the option for adding a custom MCP server
available in ChatGPT.

Step 2. Add the DIDWW MCP server
--------------------------------

#. Open `ChatGPT Plugins <https://chatgpt.com/plugins>`_.
#. Select the **+** button.
#. Enter the server address ``https://api.didww.com/mcp``. See :doc:`DIDWW MCP connection details <../connection-details>`.
#. Review the warning about custom MCP servers.
#. Select **I understand and want to continue**.
#. Select **Create**.

ChatGPT displays the **Add DIDWW to ChatGPT** window.

.. important::

   Connect only to an MCP server address published by DIDWW. Do not use an
   address received in an AI conversation or from an unverified source.

Step 3. Connect DIDWW
---------------------

If you added the MCP server in Step 2:

#. Review the information in the **Add DIDWW to ChatGPT** window.
#. Select **Sign in with DIDWW**.

If DIDWW was already made available in your ChatGPT workspace:

#. Open **Settings**.
#. Select **Plugins**.
#. Find **DIDWW**.
#. Select **Connect** or **Sign in with DIDWW**.

Each user must authorize the connection using their own DIDWW User Panel
access.

Step 4. Authorize access to DIDWW
---------------------------------

ChatGPT opens the DIDWW authorization page in your browser.

#. Sign in to the DIDWW User Panel if you are not already signed in.
#. Complete two-factor authentication when required.
#. Confirm that the requesting application is **ChatGPT**.
#. Review the DIDWW account, user, and roles shown on the page.
#. Read the information under **Before you connect an AI assistant**.
#. Select **I understand and accept**.
#. Select **Authorize**.
#. After authorization is complete, return to ChatGPT.

.. note::

   Authorizing the connection does not grant ChatGPT additional DIDWW
   permissions. ChatGPT can access only the accounts, information, and actions
   available to the DIDWW user who authorized the connection.

Step 5. Review the connection
-----------------------------

#. Open **Settings**.
#. Select **Plugins**.
#. Select **DIDWW**.
#. Confirm that:

   - the connection is shown as **DIDWW**
   - the server URL matches the address published by DIDWW
   - authorization is shown as **OAuth**

.. note::

   In a managed workspace, administrators may separately control plugin
   availability, member access, and permitted actions.

Step 6. Verify the connection
-----------------------------

#. Open a new ChatGPT conversation.
#. Open the tools or plugins menu.
#. Select **DIDWW** if it is not already enabled.
#. Ask the following read-only question:

   .. code-block:: text

      Which DIDWW account is currently active?
      Do not make any changes.

#. Review any plugin-use request displayed by ChatGPT.
#. Approve the read-only request.
#. Confirm that ChatGPT returns the expected DIDWW account.

.. note::

   ChatGPT may request permission before using the plugin. This ChatGPT
   approval is separate from a DIDWW confirmation required for purchases,
   payments, deletions, and other significant account changes.




Connect Claude to DIDWW
=======================

Connect Claude to your DIDWW account to review account information and request
supported DIDWW actions from a conversation. You authorize the connection in
your browser using your existing DIDWW User Panel access.

.. note::

   For current Claude instructions, see the `official Anthropic guide for
   adding custom connectors
   <https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp>`_.

Before you begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `create a DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- Access to a Claude account that supports custom connectors is required.
- The DIDWW MCP server address is required. See :doc:`DIDWW MCP connection
  details <../connection-details>`.
- Access to your DIDWW two-factor authentication method is required when
  two-factor authentication is enabled.
- For a Team or Enterprise organization, an Owner or Primary Owner must add
  DIDWW before organization members can connect it.

Step 1. Add the DIDWW connector
-------------------------------

Add DIDWW as a custom connector using the instructions for your Claude account
type.

.. tab-set::
   :class: my-tabs

   .. tab-item:: Individual account
      :sync: personal

      #. Sign in to `Claude <https://claude.ai>`_.
      #. Open **Customize**.
      #. Select **Connectors**.
      #. Select the **+** button next to **Connectors**.
      #. Select **Add custom connector**.
      #. Enter **DIDWW** as the connector name.
      #. Enter the server address ``https://api.didww.com/mcp``. See :doc:`DIDWW MCP connection details <../connection-details>`.
      #. Leave the optional OAuth client ID and client secret fields empty.
      #. Select **Add**.
      #. If prompted, select **Connect**.

      Claude opens the DIDWW authorization page in your browser.

   .. tab-item:: Team or Enterprise organization
      :sync: organization

      An Owner or Primary Owner must first add DIDWW to the organization.

      **Organization owner**

      #. Open **Organization settings** in Claude.
      #. Select **Connectors**.
      #. Select **Add**.
      #. Hover over **Custom**, and then select **Web**.
      #. Enter **DIDWW** as the connector name.
      #. Enter the server address from :doc:`DIDWW MCP connection details
         <../connection-details>`.
      #. Leave **Advanced settings** unchanged. DIDWW does not require an OAuth client ID or client secret.
      #. Select **Add**.

      After DIDWW is added, each organization member must connect it.

      **Organization member**

      #. Open **Customize**.
      #. Select **Connectors**.
      #. Find **DIDWW** in the connector list. It may have a **Custom** label.
      #. Select **Connect**.

      Claude opens the DIDWW authorization page in the member's browser.

.. important::

   Connect only to an MCP server address published by DIDWW. Do not use an
   address received in a Claude conversation or from an unverified source.

Step 2. Authorize access to DIDWW
---------------------------------

After you connect DIDWW, your browser opens the DIDWW authorization page.

#. Sign in to the DIDWW User Panel if you are not already signed in.
#. Complete two-factor authentication when required.
#. Confirm that the application requesting access is **Claude**.
#. Review the DIDWW account, user, and roles shown on the page.
#. Read the information under **Before you connect an AI assistant**.
#. Select **I understand and accept**.
#. Select **Authorize**.
#. After authorization is complete, return to Claude.

Claude should show DIDWW as connected.

.. note::

   Authorizing the connection does not grant Claude additional DIDWW
   permissions. Claude can access only the accounts, information, and actions
   available to the DIDWW user who authorized the connection.

   In a Team or Enterprise organization, each member authorizes DIDWW using
   their own DIDWW User Panel access.

Step 3. Enable DIDWW in a conversation
--------------------------------------

#. Open a new or existing Claude conversation.
#. Select **+** next to the message field.
#. Select **Connectors**.
#. Enable **DIDWW** for the conversation.

Step 4. Verify the connection
-----------------------------

#. Ask Claude the following read-only question:

   .. code-block:: text

      Which DIDWW account is currently active?

#. Review and approve the tool-use request displayed by Claude.
#. Confirm that Claude returns the expected DIDWW account.

.. note::

   The available tool-approval options may depend on your Claude plan and
   organization settings.

   Claude's tool approval and DIDWW's action confirmation are separate
   controls. Claude's approval determines whether Claude can send a request to
   DIDWW. DIDWW may then require another confirmation for a purchase, usage
   rate, deletion, termination, or another protected account change. Approving
   a Claude tool request does not confirm the DIDWW action.

Remove DIDWW from Claude
------------------------

To remove a manually added DIDWW connector from Claude:

#. Open **Customize**.
#. Select **Connectors**.
#. Find **DIDWW**.
#. Select **Remove**, or open the three-dot menu and select **Remove**.
#. Follow the prompts to remove the connector.

To view connections and revoke Claude's authorization from the DIDWW side, see
:ref:`Manage the connection <mcp-manage-connection>`.




Connect Perplexity to DIDWW
===========================

Connect Perplexity to your DIDWW account to review account information and
request supported DIDWW actions from a conversation. You authorize the
connection in your browser using your existing DIDWW User Panel access.

.. note::

   For current Perplexity instructions, see the `official Perplexity guide for
   adding custom remote connectors
   <https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors>`_.

Before you begin
----------------

- An active DIDWW account is required. `Sign in to DIDWW
  <https://my.didww.com/users/sign_in>`_ or `create a DIDWW account
  <https://my.didww.com/users/sign_up#/users/sign_up>`_.
- A Perplexity plan that supports custom connectors is required. Custom
  connectors are available on the Pro, Max, and Enterprise plans.
- The DIDWW MCP server address is required. See :doc:`DIDWW MCP connection
  details <../connection-details>`.
- Access to your DIDWW two-factor authentication method is required when
  two-factor authentication is enabled.

.. important::

   A custom connector can be added only in the Perplexity web application. Add
   and authorize DIDWW at `perplexity.ai <https://www.perplexity.ai>`_ before
   you use it elsewhere.

Adding DIDWW to Perplexity takes three separate actions: create the custom
connector, connect and authorize it, and then enable it in each conversation.

Step 1. Create the DIDWW custom connector
-----------------------------------------

#. Sign in to `Perplexity <https://www.perplexity.ai>`_ in a web browser.
#. Open **Settings**.
#. Select **Connectors**.
#. Select **+ Custom connector**, and then select **Remote**.
#. Enter **DIDWW** as the connector name.
#. Leave **Description** empty, or enter your own description.
#. Enter the server address ``https://api.didww.com/mcp``. See :doc:`DIDWW MCP connection details <../connection-details>`.
#. Leave **Advanced** unchanged. DIDWW uses OAuth over Streamable HTTP and does
   not require a client ID or client secret.
#. Select **I understand custom connectors can introduce risks**.
#. Select **Add**.

Perplexity creates the connector and opens its card. The card is empty at this
point because DIDWW is not connected yet.

.. important::

   Connect only to an MCP server address published by DIDWW. Do not use an
   address received in a Perplexity conversation or from an unverified source.

Step 2. Connect DIDWW
---------------------

#. Open the **DIDWW** connector card in **Connectors**.
#. Select **+ Add connector**.

Perplexity opens the DIDWW authorization page in your browser.

Step 3. Authorize access to DIDWW
---------------------------------

#. Sign in to the DIDWW User Panel if you are not already signed in.
#. Complete two-factor authentication when required.
#. Confirm that the application requesting access is **Perplexity**.
#. Review the DIDWW account, user, and roles shown on the page.
#. Read the information under **Before you connect an AI assistant**.
#. Select **I understand and accept**.
#. Select **Authorize**.
#. Select **Open Perplexity** to return to Perplexity.

.. note::

   Authorizing the connection does not grant Perplexity additional DIDWW
   permissions. Perplexity can access only the accounts, information, and
   actions available to the DIDWW user who authorized the connection.

Step 4. Review the connection
-----------------------------

#. Open **Settings**.
#. Select **Connectors**.
#. Confirm that **DIDWW** is shown as **Connected**.

Step 5. Enable DIDWW in a conversation
--------------------------------------

DIDWW is not used automatically after it is connected. Enable it in each
conversation where you want to use it.

#. Open a new Perplexity conversation.
#. Select **+** next to the message field.
#. Select **Connectors**.
#. Select **DIDWW**.

Step 6. Verify the connection
-----------------------------

#. Ask Perplexity the following read-only question:

   .. code-block:: text

      Which DIDWW account is currently active?
      Do not make any changes.

#. Review any connector-use request displayed by Perplexity.
#. Confirm that Perplexity returns the expected DIDWW account.

.. note::

   Perplexity's connector approval and DIDWW's action confirmation are separate
   controls. DIDWW may require another confirmation for a purchase, usage rate,
   deletion, termination, or another protected account change.

To view connections and revoke Perplexity's authorization from the DIDWW side,
see :ref:`Manage the connection <mcp-manage-connection>`.


.. _mcp-privacy-and-data-handling:

Privacy and data handling
=========================

DIDWW MCP shares account information with a connected MCP client only when it
is needed to respond to a request. Information received by the MCP client is
also processed by its AI provider under that provider's terms and privacy
policy.

Account information
-------------------

Depending on the request and the permissions assigned to the DIDWW user for the
active account, information sent through DIDWW MCP can include:

- phone numbers and supported service configurations
- account balances, invoices, orders, payments, refunds, and masked saved-card
  information
- export parameters, processing status, and download links for inbound and
  outbound call records and SMS logs
- identities, addresses, verification information, required document types,
  missing document requirements, and secure-upload request status
- account users, assigned roles, and pending invitations
- the active DIDWW account and other accounts available to the user

The MCP client receives only the information required to complete the requested
action and permitted by the DIDWW user's access to the active account.

Roles and account permissions
-----------------------------

DIDWW uses the roles assigned to the user for the active account to determine
which actions are permitted. Available roles include **Admin**, **Porting**,
**Technical**, **Commercial**, **Billing**, and **Compliance**. MCP responses
return the Admin role under its internal name, ``SuperAdmin``.

An MCP client may display an action that the user's role does not permit. If
the action is requested, DIDWW refuses it and identifies the active account,
the required roles, and the roles currently assigned to the user.

Permissions are evaluated separately for each DIDWW account. Switching the
active account can therefore change the information and actions available to
the MCP client.

If another accessible account has the required permissions, ask the MCP client
to switch to that account. Otherwise, ask an account owner to assign
the required role in the DIDWW User Panel.

Protected information
---------------------

DIDWW masks protected values such as payment-card details and service
credentials. DIDWW MCP does not return complete payment-card numbers,
passwords, API keys, or two-factor authentication codes.

Do not enter any of the following information in an MCP client conversation:

- your DIDWW password
- API keys
- complete payment-card information
- two-factor authentication codes
- identity or address documents

Operational records
-------------------

DIDWW records MCP connection and request activity for security, service
operation, abuse prevention, and troubleshooting. Depending on the activity,
these records can identify:

- the DIDWW user and active account
- the connected MCP client
- the date and time of the activity
- the source IP address and user agent
- the requested account area or action
- whether the request completed or returned an error

Operational records do not contain your DIDWW password or two-factor
authentication code.

Secure document uploads
-----------------------

Documents are not sent through the MCP client conversation. When documents
are required, DIDWW provides a secure, one-time browser link that identifies:

- the purpose of the upload
- the related identity, address, phone numbers, or verification
- the link expiration time

Files are encrypted in the browser before upload. The link works once and
stops working after the displayed expiration period. If the link expires,
request a new secure upload link.

Do not paste documents into the conversation or send them as conversation
attachments.

Data exports
------------

Export contents are not returned in the MCP client conversation. When an
export is ready, the MCP client provides a download link. DIDWW returns a
direct link that opens the file without a User Panel sign-in, and a User Panel
link that requires a signed-in DIDWW user.

.. warning::

   The direct link grants access to the export file to anyone who has it. It
   remains valid until the file is deleted. Treat it as confidential, do not
   forward it, and do not post it outside the conversation.

Completed export files remain available for one month. If a file is no longer
available, create a new export.

Connected MCP clients
---------------------

Each connected MCP client appears in the DIDWW User Panel with its recent
activity, last IP address, user agent, and available actions.

To review connected clients:

#. Open the account switcher in the upper-right corner.
#. Select **Account Settings**.
#. Select the **MCP Clients** tab.

Select **Revoke** to disconnect one MCP client or **Revoke all** to disconnect
every listed client. A revoked connection cannot be restored. To use the
client again, add or select the DIDWW connection and complete authorization
again.

Privacy, security, and support
------------------------------

- For information about how DIDWW processes personal data, see the `DIDWW
  Privacy Notice <https://www.didww.com/privacy-notice>`_.
- To protect your DIDWW account with two-factor authentication, see
  :doc:`Account security <../account-settings/two-factor-auth>`.
- For information about DIDWW security certifications, see
  :doc:`Certifications and memberships <../certifications-and-memberships>`.
- For assistance, contact `DIDWW Customer Support <mailto:support@didww.com>`_ or use
  the `DIDWW contact page <https://www.didww.com/contacts>`_.


.. _mcp-troubleshooting:

Troubleshooting DIDWW MCP
=========================

Use the following guidance to resolve common DIDWW MCP connection,
authorization, account, upload, export, and request issues.

Connection and authorization
----------------------------

.. dropdown:: The DIDWW authorization page does not open

   #. Keep the MCP client open.
   #. Check whether the browser opened the authorization page in another tab or
      window.
   #. Return to the MCP client and start the connection again.
   #. Confirm that the MCP client uses the server address published in
      :doc:`Connection details <connection-details>`.

   If the page still does not open, follow the connection guide for your MCP
   client or contact DIDWW Customer Support.

.. dropdown:: The Authorize button is unavailable

   Review the authorization notice and select the acknowledgment checkbox. The
   **Authorize** button becomes available after you accept the notice.

.. dropdown:: Two-factor authentication fails

   #. Sign in to the DIDWW User Panel in your browser.
   #. Complete two-factor authentication using a method enabled for your
      DIDWW user.
   #. Return to the MCP client.
   #. Start the connection again.

   If you cannot complete two-factor authentication in the User Panel, resolve
   the account-access problem before reconnecting the MCP client.

.. dropdown:: DIDWW appears disconnected

   Reconnect DIDWW from the MCP client's connection or connector settings. If
   the problem continues:

   #. Open the account switcher in the DIDWW User Panel.
   #. Select **Account Settings**.
   #. Select the **MCP Clients** tab.
   #. Revoke the affected connection when it is still listed.
   #. Add or select DIDWW in the MCP client and complete authorization again.

.. dropdown:: The connection was revoked

   A revoked connection cannot be restored. Add or select the DIDWW connection
   in the MCP client and complete the browser authorization process again.

.. dropdown:: Authorization expired after inactivity

   A connection that remains unused for 30 days requires DIDWW authorization
   again. Reconnect DIDWW in the MCP client and complete the browser
   authorization process.

Accounts, permissions, and limits
---------------------------------

.. dropdown:: The wrong DIDWW account is active

   Ask the MCP client:

   .. code-block:: text

      Which DIDWW account is currently active?

   If you can access multiple accounts, ask it to list them and switch to the
   required account. Confirm the active account before retrying the request.

.. dropdown:: An action is not permitted

   The MCP client uses the roles and permissions of the DIDWW user who
   authorized the connection. Check:

   - the active DIDWW account
   - your role for that account
   - whether the record belongs to the active account
   - whether the required service is enabled

   Connecting an MCP client does not grant additional roles or permissions.

.. dropdown:: A service or account limit was reached

   The requested action cannot be completed because a limit applies to the
   active account or service. Review the response to identify the affected
   limit and any available next steps.

   Contact DIDWW Customer Support if the limit needs to be reviewed or changed.

.. dropdown:: The account balance is insufficient

   DIDWW does not complete a purchase when the active account has insufficient
   funds.

   #. Add funds using a payment method in the DIDWW User Panel.
   #. Return to the MCP client.
   #. Review the updated balance.
   #. Request a new purchase preview.

.. dropdown:: Too many requests were sent

   DIDWW returns a waiting period when the connected MCP client exceeds its
   request rate. Wait for the number of seconds identified by the MCP client or
   the ``Retry-After`` value before sending another request.

Uploads and exports
-------------------

.. dropdown:: A secure upload link expired

   A secure upload link cannot be used after it expires or after an upload is
   completed. Ask the MCP client to create a new secure upload link.

   Do not send documents in the MCP client conversation.

.. dropdown:: An export is still processing

   Ask the MCP client to check the export status. Do not create another export
   unless the original request failed.

.. dropdown:: An export link does not open the file

   An export offers two links. The direct link opens the file without a DIDWW
   User Panel sign-in. The User Panel link requires a signed-in DIDWW user that
   can access the account associated with the export.

   If the direct link does not open, ask the MCP client for the link again.
   Chat clients sometimes append punctuation to a link and break it.

   Completed export files remain available for one month, and both links stop
   working when the file is deleted. Create a new export when the previous file
   is no longer available.

Requests and actions
--------------------

.. dropdown:: A confirmed action has an unclear result

   Do not immediately repeat a purchase, termination, restoration, invitation,
   or deletion.

   Ask the MCP client to check the relevant phone numbers, capacity, orders,
   trunks, groups, identities, addresses, or invitations. Start another
   request only when the account records show that the original action did not
   complete.

.. dropdown:: A newly released action is missing

   An MCP client can cache the available DIDWW actions for up to one hour.
   Reconnect the client when a newly released action is missing or a previously
   valid setting is no longer recognized.

.. dropdown:: An action is not available through MCP

   Use the DIDWW User Panel when an action is not supported through MCP.
   Current examples include:

   - number porting
   - A2P SMS campaigns
   - CNAM configuration
   - outbound trunks (Voice OUT)
   - shopping-cart actions
   - phone.systems™ subscription management
   - company details

Reconnect DIDWW MCP
-------------------

#. Open the connection or connector settings in the MCP client.
#. Select or add DIDWW.
#. Complete the DIDWW browser authorization process.
#. Ask the MCP client to identify the active DIDWW account.

Contact support
---------------

If the problem continues, contact `DIDWW Customer Support
<mailto:support@didww.com>`_ by email. To speak with a 24/7 live support agent, open
the `DIDWW contact page <https://www.didww.com/contacts>`_ and use the live-chat
widget.

Include the affected DIDWW account, MCP client name, approximate time of the
problem, and the error message.

.. note::

    Do not include passwords, API keys, two-factor authentication codes, or documents.


Billing and payments with DIDWW MCP
===================================

Use DIDWW MCP to review supported billing and payment information for the
active DIDWW account. All actions described on this page are read-only.

DIDWW MCP cannot make payments, add funds, issue refunds, or manage payment
methods or billing details.

What you can review
-------------------

Describe the information you need in plain language. When possible, identify
the relevant DIDWW account, date range, amount, invoice, order, or payment
reference.

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Information
     - What you can request
   * - Current account balance
     - Review the prepaid balance and currency of the active DIDWW account.
   * - Invoices
     - List invoices, find a specific invoice, and review supported invoice
       details. Invoice lists can be filtered by year and month.
   * - Order history
     - Review purchase orders recorded for the active DIDWW account, including
       available dates, references, amounts, currencies, and statuses.
   * - Payment history
     - Review recorded payments, including available dates, methods,
       references, amounts, currencies, and statuses.
   * - Completed refunds
     - Review completed refunds and their available references, dates, amounts,
       currencies, and related-record information.
   * - Saved-card summaries
     - Review masked information for saved cards, such as the card type, last
       four digits, and expiration date.

Billing records
---------------

An order records a purchase, a payment records funds received by DIDWW, an
invoice records billed charges, and a completed refund records funds returned.
These records are related but are not interchangeable.

When reviewing account activity, ask the MCP client to compare the available
dates, amounts, currencies, statuses, and references. DIDWW MCP does not change
any of these records.

Resolve an insufficient balance
-------------------------------

DIDWW does not complete a purchase when the active account has insufficient
funds. Add funds through `Payment Methods in the DIDWW User Panel
<https://my.didww.com/#/payment_methods>`_, then return to the MCP client and
review the updated balance.

DIDWW MCP cannot charge a saved payment card or add funds to the account. A
payment completed in the User Panel does not automatically retry a previous
purchase. Request a new purchase preview after the balance is updated.

Permissions and approvals
-------------------------

The available billing information depends on the active DIDWW account, the
user's assigned permissions, and the records available for that account.
Connecting an MCP client does not grant additional billing permissions.

Read-only billing requests do not require DIDWW confirmation. The MCP client
may display its own tool-use approval before requesting information. This
client approval does not authorize a payment, purchase, refund, or other billing
change.

Limitations
-----------

DIDWW MCP cannot:

- charge a saved payment card
- add funds to the account
- add, edit, or remove a saved payment card
- issue, approve, or cancel a refund
- change billing details
- reveal complete payment-card numbers or card security codes
- download invoice PDF files
- show pending or canceled refunds

Only completed refunds and masked saved-card information are available.
Complete payments, manage payment methods, update billing details, and request
refund-related changes through the DIDWW User Panel or the appropriate DIDWW
support channel.

See :doc:`Exports with DIDWW MCP <data-exports>` to prepare supported
order and payment exports.

Example requests
----------------

.. dropdown:: Review the account balance

   .. code-block:: text

      Show the current balance and currency for the active DIDWW account.

.. dropdown:: Find an invoice

   .. code-block:: text

      Show my invoices from July 2026.
      Include their dates, references, amounts, currencies, and statuses.

.. dropdown:: Review order history

   .. code-block:: text

      Show the orders recorded during the last 30 days.
      Include the available dates, references, amounts, currencies,
      and statuses.

.. dropdown:: Review payment history

   .. code-block:: text

      Show the payments recorded during the last 30 days.
      Include the available dates, methods, references, amounts,
      currencies, and statuses.

.. dropdown:: Review completed refunds

   .. code-block:: text

      Show the completed refunds from the last 30 days.
      Include their available references, dates, amounts, currencies,
      and related records.

.. dropdown:: Review saved cards

   .. code-block:: text

      Show the saved-card summaries for the active DIDWW account.

.. dropdown:: Resolve an insufficient balance

   .. code-block:: text

      Show the current balance and explain whether it is sufficient for the
      proposed purchase. If it is insufficient, provide the DIDWW User Panel
      link for adding funds. Do not retry the purchase.



Compliance and verification with DIDWW MCP
==========================================

Use DIDWW MCP to review number-registration requirements, manage supported
identities and addresses, upload required documents securely, and submit or
review address verifications through a connected MCP client.

.. important::

   The identity and address must represent the actual end user of the phone
   numbers. The MCP client can explain requirements and validate available
   information, but it must not decide which person or business should be
   registered as the end user.

What you can do
---------------

Describe the required result in plain language. When possible, identify the
active DIDWW account, country, phone-number type, phone numbers, identity, and
address.

Review requirements and records
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review registration requirements
     - Review the identity type, mandatory fields, address requirements, proof
       types, document quantities, and other conditions for a supported country
       and phone-number type.
   * - Review identities
     - List the personal or business identities available in the active DIDWW
       account and review their available details and document summary. When a
       country and phone number type are provided, identify which records are
       eligible for the applicable requirement and explain any blocking issue.
   * - Review addresses
     - List addresses associated with the account's identities and review their
       verification information. When a country and phone number type are
       provided, identify which records are eligible for the applicable
       requirement and explain how an ineligible record can be corrected when
       remediation is available.
   * - Validate an identity and address
     - Check whether a selected identity and address satisfy the applicable
       registration requirement before submitting a verification.
   * - Review address verifications
     - Review verification statuses and available rejection comments or reasons
       for submitted address verifications.

Manage identities and addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Create an identity
     - Create a personal or business identity for the actual end user using the
       fields required by the applicable registration requirement. Check it
       against the requirement before uploading documents.
   * - Update an identity
     - Update supported identity fields when information is incomplete or does
       not satisfy a requirement.
   * - Delete an identity
     - Permanently delete an eligible identity together with all its addresses,
       uploaded proof documents, and permanent supporting documents after
       reviewing the effect and confirming the action.
   * - Create an address
     - Create an address for an existing identity.
   * - Update an address
     - Update supported address, postal-code, area, or description information.
   * - Delete an address
     - Delete an eligible address after reviewing the phone numbers,
       verifications, and services that may be affected.

Manage supporting documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Prepare a required-document upload
     - Create a one-time DIDWW upload link containing the document sections
       missing from a selected registration requirement.
   * - Upload or replace a specific proof
     - Create a one-time upload link for selected identity or address proof
       types, including a replacement for an existing proof.
   * - Check upload status
     - Check whether a secure upload is pending, completed, or expired.
   * - Delete a stored proof
     - Delete an eligible proof after reviewing and confirming the effect on
       related verifications or services.

Submit and review address verifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Submit an address verification
     - Submit a verification directly when the selected identity, address, and
       required proofs are already complete.
   * - Upload documents and submit
     - Prepare a secure upload that submits the address verification after all
       required documents have been uploaded successfully.
   * - Review verification status
     - Review submitted verifications and identify whether they are awaiting
       review, approved, rejected, or require another action.
   * - Resolve a rejected verification
     - Review the available rejection information, correct the identity,
       address, or documents, and prepare a new verification when permitted.

How the verification flow works
-------------------------------

Some phone numbers require end-user verification before they can be activated.
Before purchasing a number, ask the MCP client whether registration is
required.

When registration is required, the process normally follows this sequence:

#. Review the requirements for the phone number's country and type.
#. Select or create the correct identity and address.
#. Validate the identity and address against the requirement.
#. Correct any missing or incompatible information.
#. Use the secure DIDWW upload page when documents are required.
#. Submit the address verification.
#. Review its status and resolve any reported problem.

Requirements depend on the country, phone-number type, end-user type, and
selected phone numbers.

A purchased number may remain pending until DIDWW approves the required
information. Purchasing the number does not bypass the verification process.

See :doc:`End-user verification
<../../phone-numbers/buy-numbers/end-user-verification>` for more information
about registration requirements and their effect on number activation.

Choose the correct end user
---------------------------

#. Identify the person or business that will actually use the phone numbers.
#. Ask the MCP client which identity and address records are eligible for the
   applicable country and phone number type.
#. Review why any other record is not eligible and whether it can be corrected.
#. Select the correct end user yourself.
#. Ask the MCP client to validate the selected records against the
   registration requirement.

If no suitable record exists, create the correct identity or address rather
than using an unrelated record.

.. note::

   An eligible record can still require proof documents. Eligibility means that
   no blocking identity or address mismatch was found for the selected
   requirement. It does not mean that the document requirements are complete.

Create an identity
------------------

An identity represents the person or business that will use the regulated
phone numbers. For a carrier or reseller, this may be the customer's own
subscriber or end customer rather than the DIDWW account holder.

Before creating an identity:

#. Review the applicable registration requirement.
#. Select the required personal or business identity type.
#. Provide the mandatory identity information returned by the requirement.
#. Ask the MCP client to check the new identity against the requirement.

A business identity requires a company name. Its first and last name identify
the authorized representative of record, not necessarily the person making the
request through the MCP client.

Provide only real, verified information. Do not ask the MCP client to invent
missing values. When a phone number is included in the identity, enter digits
only.

Checking the identity against the requirement during creation can identify
missing or incompatible information before the document-upload stage. After
creating the identity, provide its required proofs through the secure DIDWW
upload page and create the associated address.

Delete an identity
------------------

Deleting an identity permanently removes:

- the identity
- all addresses belonging to it
- all uploaded proof documents
- all permanent supporting documents

This action cannot be undone and requires DIDWW confirmation.

An identity cannot be deleted when it:

- is the account's system identity
- is assigned to a phone number as its main or porting identity
- has a new or pending address verification
- is used by an unfinished emergency calling service
- is used by an unfinished SMS campaign

When deletion is unavailable, the response identifies the applicable blocker.
Resolve the blocker before requesting deletion again.

A user whose access is limited to porting cannot delete an identity that has
permanent supporting documents. The appropriate compliance permission is
required, as in the DIDWW User Panel.

Upload documents securely
--------------------------

.. important::

    Do not send identity documents, address proofs, or other supporting files in
    the AI conversation.

When documents are required, DIDWW provides a separate one-time browser link.
The upload page identifies:

- the purpose of the upload
- the relevant identity and address
- the relevant phone numbers, when applicable
- the documents that must be provided

The link can also be opened on another device using the provided QR option when
the MCP client supports it.

Review the information on the DIDWW page before uploading anything. The link is
time-limited and cannot be reused after it is completed or expires.

After uploading, return to the MCP client and ask it to check the upload
status.

See :doc:`Privacy and data handling <../privacy-and-data-handling>` for
information about protected data, AI-provider processing, and secure document
handling.

Before submitting a verification
--------------------------------

Make sure that:

- the correct DIDWW account is active
- the correct end user has been selected
- the identity type matches the requirement
- mandatory identity and address fields are complete
- the address is appropriate for the selected phone numbers
- all required proofs and supporting documents are available
- your DIDWW user has the required compliance permission

A verified identity or address does not automatically satisfy every
registration requirement. Requirements can differ by country and phone-number
type.

Permissions and confirmations
-----------------------------

The MCP client uses the permissions of the DIDWW user who authorized the
connection.

DIDWW requires confirmation before destructive actions such as:

- deleting an identity
- deleting an address
- deleting a stored proof

The confirmation preview identifies affected records and known blockers when
available.

An identity may not be deleted while it is the account's system identity,
linked to a phone number, used by a new or pending verification, or required by
an unfinished emergency calling service or SMS campaign. An address may also
be protected by an active verification or service.

Your MCP client may display its own approval request before calling a
DIDWW action. This application approval is separate from a DIDWW
destructive-action confirmation.

Product requirements
--------------------

A compliance request may be unavailable because of:

- insufficient DIDWW user permissions
- an incompatible identity or address
- missing mandatory information
- missing or incompatible proofs
- an expired secure upload link
- a country or phone-number requirement that is not satisfied
- a pending verification or linked service that prevents deletion
- phone numbers that require different addresses or requirements

When possible, the response identifies the missing information and the next
available action.

Current limitations
-------------------

DIDWW MCP does not currently support:

- selecting the legal end user on the customer's behalf
- receiving identity or address documents directly in the AI conversation
- reusing a completed or expired secure upload link
- completing number porting document workflows through this compliance flow

Example requests
----------------

.. dropdown:: Review a registration requirement

   .. code-block:: text

      Show the number-registration requirements for a personal end user with
      a geographic phone number in Germany.
      Include mandatory fields and required documents.
      Do not create or change anything.

.. dropdown:: Check registration before purchasing

   .. code-block:: text

      Check whether end-user registration is required for a geographic phone
      number in Berlin, Germany.
      Show the applicable identity, address, and document requirements.
      Do not purchase anything.

.. dropdown:: Review available identities and addresses

   .. code-block:: text

      Show the identities and addresses that are eligible for registering a
      geographic phone number in Germany.
      For each ineligible record, explain the blocking reason and any available
      correction. Do not choose the legal end user or make any changes.

.. dropdown:: Validate an identity and address

   .. code-block:: text

      Check whether the selected identity and address satisfy the registration
      requirement for +49XXXXXXXX.
      Show missing fields, documents, or compatibility problems.
      Do not submit a verification.

.. dropdown:: Prepare a new identity and address

   .. code-block:: text

      Explain which identity and address fields are required for the actual
      end user of +49XXXXXXXX.
      Prepare the records using the information I provide.
      Wait for my approval before creating them.

.. dropdown:: Delete an identity

   .. code-block:: text

      Show the addresses, proof documents, verifications, phone numbers, and
      services associated with the selected identity.
      Explain anything that prevents deletion and everything that will be
      permanently removed.
      Do not delete the identity until I confirm the action.

.. dropdown:: Prepare a required-document upload

   .. code-block:: text

      Check which documents are missing for registering +49XXXXXXXX.
      If documents are required, provide the DIDWW secure upload link.
      Do not ask me to send documents in this conversation.

.. dropdown:: Replace a supporting document

   .. code-block:: text

      Show the acceptable proof types for the selected identity.
      Prepare a secure upload link to replace its current identity proof.
      Do not delete any other document.

.. dropdown:: Submit an address verification

   .. code-block:: text

      Validate the selected identity and address for +49XXXXXXXX.
      If all required information and documents already exist, show the
      proposed address verification.
      Wait for my approval before submitting it.

.. dropdown:: Review address-verification status

   .. code-block:: text

      Show the latest address verification for +49XXXXXXXX.
      Include its status and any available rejection information.
      Do not make any changes.

.. dropdown:: Review a pending number

   .. code-block:: text

      Explain why +49XXXXXXXX is still pending.
      Show whether end-user verification is required and the current
      verification status.
      Do not make any changes.

.. dropdown:: Review an address before deletion

   .. code-block:: text

      Show the phone numbers, verifications, and services associated with the
      selected address.
      Explain the effect of deleting it.
      Wait for my confirmation before deleting the address.


Exports with DIDWW MCP
======================

Use DIDWW MCP to prepare supported account-data exports through a connected MCP
client. You can request an export, monitor its progress, and obtain a
download link when the file is ready.

.. note::

    Exports are created asynchronously. The MCP client does not need to remain
    open while DIDWW prepares the file.

Supported export types
----------------------

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Export
     - Information included
     - Available filters
   * - Inbound call records
     - Records for incoming calls available to the active DIDWW account.
     - A date range is required. A phone-number filter can be provided when
       applicable.
   * - Outbound call records
     - Records for outgoing calls available to the active DIDWW account.
     - A date range is required. A phone-number filter can be provided when
       applicable.
   * - Inbound SMS logs
     - Records for incoming SMS messages.
     - A date range is required. A phone-number filter can be provided when
       applicable.
   * - Outbound SMS logs
     - Records for outgoing SMS messages.
     - A date range is required. A phone-number filter can be provided when
       applicable.
   * - Phone numbers
     - Phone-number records available to the active DIDWW account.
     - A date range is not accepted. A phone-number export always covers the
       current records.
   * - Orders
     - Order records available to the active DIDWW account.
     - A date range is optional.
   * - Payments
     - Payment records available to the active DIDWW account.
     - A date range is optional.

What you can do
---------------

Describe the export you need in plain language. Identify the relevant account,
record type, date range, and phone number when applicable.

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Create an export
     - Request a supported export using the applicable date and phone-number
       filters.
   * - Review prepared exports
     - List exports created for the active DIDWW account and review their type,
       filters, and current status.
   * - Check export status
     - Check whether a requested export is pending, processing, or completed.
   * - Download a completed export
     - Obtain a download link after the export is completed. DIDWW returns a
       direct link that opens without a User Panel sign-in, and a User Panel
       link for signed-in access.

How exports work
----------------

The export workflow has four stages:

#. Ask the MCP client to prepare an export.
#. DIDWW validates the selected export type and filters.
#. DIDWW prepares the file in the background.
#. Ask the MCP client to check the status and provide the download link.

Preparing an export can take several minutes. Because the MCP connection does
not send a completion notification, ask the MCP client to check the export
status after waiting for the preparation period shown in the response.

Export statuses
---------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Status
     - Meaning
   * - Pending
     - DIDWW accepted the export request, but processing has not started.
   * - Processing
     - DIDWW is preparing the export file.
   * - Completed
     - The file is ready and a download link can be requested.

Date requirements
-----------------

Inbound and outbound call-record and SMS-log exports require a valid date
range.

The requested dates must:

- fall within the current month or the two previous calendar months
- include a start date that is earlier than the end date
- not include future dates

If a requested end date extends beyond the current time, DIDWW may adjust it to
the current time and identify the adjusted range in the response.

Order and payment exports can use an optional date range. A phone-number export
does not accept a date range, and DIDWW rejects the request when one is
supplied.

Download and retention
----------------------

When an export is completed, the MCP client can provide two download links:

- a **direct link** that opens the file without a DIDWW User Panel sign-in. It
  works in any browser and remains valid until the file is deleted.
- a **User Panel link** that requires a signed-in DIDWW user with permission to
  access the export.

The export file remains available for one month. Both links stop working when
the file is deleted.

.. warning::

   The direct link grants access to the export file to anyone who has it.
   Treat it as confidential and do not forward it.

Permissions
-----------

Export availability depends on the permissions assigned to the DIDWW user:

- call-record and SMS-log exports require access to the relevant logs
- phone-number exports require phone-number export permission
- order and payment exports require billing permission

An export created by another DIDWW account is not available through the active
account connection.

If your user can access multiple DIDWW accounts, ask the MCP client to show
the active account before creating the export.

Current limitations
-------------------

DIDWW MCP does not currently:

- return the complete export file inside the MCP client conversation
- send a notification when an export finishes
- prepare invoice PDF exports
- prepare export types other than those listed on this page

Example requests
----------------

.. dropdown:: Export phone number records

   .. code-block:: text

      Prepare an export of the phone numbers in the active DIDWW account.
      Tell me the export identifier and its current status.

.. dropdown:: Export inbound call records

   .. code-block:: text

      Prepare an inbound call-record export for +370XXXXXXXX.
      Include records from 2026-08-01 through the current time.
      Tell me when I should check the export status.

.. dropdown:: Export outbound call records

   .. code-block:: text

      Prepare an outbound call-record export for July 2026.
      Use the active DIDWW account.
      Tell me the export identifier and its current status.

.. dropdown:: Export inbound SMS logs

   .. code-block:: text

      Prepare an inbound SMS log export for +1202XXXXXXX.
      Include records from 2026-08-01 through the current time.
      Tell me when I should check the export status.

.. dropdown:: Export outbound SMS logs

   .. code-block:: text

      Prepare an outbound SMS log export for July 2026.
      Use the active DIDWW account.
      Tell me the export identifier and its current status.

.. dropdown:: Export orders

   .. code-block:: text

      Prepare an export of orders created during July 2026.
      Do not create any purchases or payments.

.. dropdown:: Export payments

   .. code-block:: text

      Prepare an export of payments received during July 2026.
      Do not create a new payment.

.. dropdown:: Check and download an export

   .. code-block:: text

      Check the status of export EXAMPLE-EXPORT-ID.
      If it is completed, provide the download link.
      Do not create another export.



Emergency calling with DIDWW MCP
================================

Use DIDWW MCP to review emergency calling requirements and existing services,
prepare the required end-user information, create a supported emergency
calling service, and manage its verification through a connected MCP client.

Emergency calling availability, supported emergency numbers, requirements, and
charges depend on the country and phone-number type.

.. important::

   Emergency calling is a safety-critical service. Confirm the active DIDWW
   account, actual end user, service address, selected phone numbers, supported
   emergency numbers, and charges before submitting a new service. Confirm
   that DIDWW has activated the service before relying on it for emergency
   calls.

What you can do
---------------

Describe the required result in plain language. Identify the active DIDWW
account, country, phone numbers, actual end user, and service address whenever
possible.

Review requirements and existing services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review emergency requirements
     - Review the identity type, mandatory identity and address fields,
       supported phone-number type, and applicable emergency calling
       requirement.
   * - Review emergency pricing
     - Review available setup and monthly pricing information for the
       applicable country and phone-number type.
   * - Review emergency calling services
     - List existing services and review their phone numbers and available
       pricing information.
   * - Review verification statuses
     - Review the latest available verification status for an existing
       emergency calling service.
   * - Validate an identity and address
     - Check whether the selected end-user identity and service address satisfy
       the applicable emergency calling requirement.
   * - Provide required documents securely
     - Request a time-limited DIDWW upload page when the selected identity or
       address is missing required proof documents.

Create and manage emergency calling services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Create an emergency calling service
     - Review the charges that will apply if the service is activated, confirm
       the preview, and submit the service for staff review.
   * - Resubmit an emergency verification
     - Submit corrected identity, address, or proof information for an existing
       emergency calling service that requires changes.
   * - Change the emergency service address
     - Select or correct the service address, validate it against the
       requirement, and resubmit the existing emergency verification with the
       updated address.
   * - Remove a DID number from a service
     - Detach a DID number from its emergency calling service. Removing every
       number automatically cancels the service within a few hours. DIDWW
       notifies the customer when the service is canceled.

Create a new emergency calling service
--------------------------------------

Creating a new emergency calling service is a paid workflow. A typical request
follows this sequence:

#. Identify the DID number or numbers that need emergency calling.
#. Review whether emergency calling is supported for their country and
   phone number type.
#. Review the required identity, address, and supporting documents.
#. Select the identity of the actual end user.
#. Select the address where the service will be used.
#. Validate the selected identity and address against the requirement.
#. Correct missing information and provide required documents through the
   secure DIDWW upload page.
#. Review the purchase preview for the active account and selected DID numbers.
#. Confirm the request only after verifying the charges that will apply if the
   service is activated.
#. DIDWW staff reviews the submitted identity, address, and supporting proofs.
#. If the request is approved, DIDWW activates the service and billing begins.
#. Review the verification status and resolve any reported issue.

The exact requirements depend on the country, phone number type, selected DID
numbers, and end-user type.

Choose the emergency service address
------------------------------------

The emergency service address must represent the location associated with the
service. Do not select an address merely because it is already verified or has
supporting documents.

The MCP client can:

- show identities and addresses available to the account
- check a selected identity and address against the requirement
- identify missing fields or documents
- identify information that must be corrected before submission

You remain responsible for selecting the correct end user and service address.

Documents for emergency requests
--------------------------------

Emergency verifications use the supporting documents associated with the
selected identity and address. Documents are not attached directly in the MCP
client conversation.

Ask the MCP client to identify missing fields or documents. When documents are
required, request a secure DIDWW upload page and open the time-limited link.
Complete the upload in the browser, then ask the MCP client to check the upload
or verification status.

.. important::

   Do not paste identity or address documents into the conversation.

Pricing and confirmation
------------------------

An emergency calling service is a paid monthly subscription after activation.
Submitting the request for staff review does not charge the account.

The initial request returns a cost preview and does not submit anything. The
preview shows the charges that will apply if DIDWW approves and activates the
service. Review:

- the active DIDWW account
- selected phone numbers
- end-user identity
- emergency service address
- setup charge, when present
- monthly charge per phone number
- total recurring charge

After the preview is confirmed, DIDWW submits a pending verification for staff
review. Billing starts only after staff confirms that the requirements are met
and activates the service. If the request is rejected or requires changes,
billing does not begin.

Resubmitting corrected information for an existing service does not add a
charge and does not require the paid-action confirmation flow.

Charges are taken from the prepaid balance of the active DIDWW account after
activation. DIDWW MCP cannot charge a payment card or add funds to the account.

Change the address and resubmit a verification
------------------------------------------------

Changing the address of an existing emergency calling service uses the
verification resubmission flow. It does not directly edit an approved
verification.

#. Review the existing service and its latest verification status.
#. Select an existing address or create the correct service address.
#. Validate the address and associated identity against the emergency calling
   requirement.
#. Provide missing proof documents through the secure DIDWW upload page.
#. Resubmit the existing emergency verification using the corrected address.
#. Review the resulting verification status.

Resubmitting corrected information for an existing service does not add a new
service charge. The service remains subject to its existing billing.

Review verification status
--------------------------

Ask the MCP client to review the latest verification status for the
emergency calling service.

If the request cannot be approved:

#. Review the available status information.
#. Identify missing or incompatible identity, address, or document information.
#. Correct the applicable identity, address, or proof information.
#. Ask the MCP client to resubmit the emergency verification.
#. Review the updated status.

Remove numbers or cancel a service
----------------------------------

You can ask the MCP client to remove a DID number from its existing
emergency calling service. Review the active account, service, and selected
number before applying the change.

Removing one DID number stops its emergency calling charge from the next
renewal. If other numbers remain assigned, the service continues for those
numbers.

Removing every DID number automatically cancels the emergency calling service
within a few hours. DIDWW notifies the customer when the service is canceled.
There is no separate MCP action for canceling an emergency calling service.

Product requirements
--------------------

An emergency calling request may be unavailable because of:

- insufficient DIDWW user permissions
- an unsupported country or phone-number type
- an incompatible identity or address
- missing mandatory identity, address, or proof information
- insufficient prepaid account balance
- the requested service belongs to another DIDWW account
- pricing or verification information is not available for the selected
  service

When possible, the response identifies the applicable requirement and the next
available action.

Permissions and confirmations
-----------------------------

The MCP client uses the permissions assigned to the DIDWW user for the active
account. Reviewing requirements, services, pricing, and statuses does not
change the account.

Creating a new emergency calling service requires emergency calling management
permission and confirmation of the purchase preview. Correcting and
resubmitting an existing verification requires emergency calling management
permission. Removing a DID number from an emergency calling service also
requires emergency calling management permission, but it does not use DIDWW's
two-step confirmation flow.

The MCP client may display its own approval before using a DIDWW tool. This
client approval is separate from DIDWW's confirmation of a paid service.

Current limitations
-------------------

DIDWW MCP does not support:

- selecting the legal end user or emergency service address on the customer's
  behalf
- adding phone numbers to an existing emergency calling service
- uploading documents directly in the MCP client conversation
- configuring outbound trunks (Voice OUT) for emergency calling

.. note::

   Use the DIDWW User Panel to add phone numbers to an existing service,
   configure the outbound trunk, or complete another action that is not
   available through MCP.

Example requests
----------------

.. dropdown:: Review emergency requirements and pricing

   .. code-block:: text

      Show the emergency calling requirements and prices for a geographic
      phone number in the United States.
      Include mandatory identity and address information.
      Do not create a service.

.. dropdown:: Review existing emergency services

   .. code-block:: text

      Show the emergency calling services in the active DIDWW account.
      Include their phone numbers, latest verification statuses, and available
      pricing information.
      Do not make any changes.

.. dropdown:: Validate an emergency service address

   .. code-block:: text

      Validate the selected identity and address for emergency calling on
      +1202XXXXXXX.
      Show missing fields, documents, or compatibility problems.
      Do not submit a verification.

.. dropdown:: Prepare a new emergency calling service

   .. code-block:: text

      Check whether +1202XXXXXXX supports emergency calling.
      If it does, show the required end-user information and documents.
      Show all setup and monthly charges that will apply after activation.
      Do not submit the request until I confirm the preview.

.. dropdown:: Provide missing documents

   .. code-block:: text

      Show which proof documents are missing for the selected identity and
      emergency service address.
      Create a secure DIDWW upload link for the missing documents.

.. dropdown:: Resubmit an emergency verification

   .. code-block:: text

      Show why the emergency verification for +1202XXXXXXX requires changes.
      Validate the corrected identity, address, and proof information.
      Confirm that resubmission adds no charge, then show the proposed request.

.. dropdown:: Change an emergency service address

   .. code-block:: text

      Show the current address and latest verification status for the
      emergency calling service assigned to +1202XXXXXXX.
      Validate the corrected service address and show any missing information.
      Resubmit the verification with the corrected address only after I approve
      the proposed change.

.. dropdown:: Remove a DID number from an emergency service

   .. code-block:: text

      Show the emergency calling service assigned to +1202XXXXXXX.
      Explain when its charge will stop and whether removing it will
      automatically cancel the service.
      Remove the number only after I approve the proposed change.

.. dropdown:: Review a verification status

   .. code-block:: text

      Review the latest verification for the selected emergency calling
      service.
      Explain any available status details or required corrections.
      Do not make any changes.


Inbound routing with DIDWW MCP
==============================

Use DIDWW MCP to review and manage supported inbound trunks, assign phone
numbers, and organize inbound call routing through a connected MCP client.

What you can do
---------------

Describe the routing result you want and identify the relevant account, phone numbers, trunks, or routing groups when possible.

Review and assign inbound routing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review inbound trunks
     - List inbound trunks and review their type, status, routing settings,
       assigned phone numbers, trunk group, and number list.
   * - Review active routing
     - Check where a phone number is currently routed and identify the trunk or
       trunk group involved.
   * - Find unassigned numbers
     - Find phone numbers that are not assigned to an inbound trunk or trunk
       group.
   * - Assign phone numbers
     - Assign one or multiple phone numbers to a supported inbound trunk or
       trunk group.
   * - Reassign phone numbers
     - Move one or multiple phone numbers from their current inbound route to
       another supported trunk or trunk group.

Manage inbound trunks
~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Manage SIP trunks
     - Create or update an inbound SIP trunk using the dedicated SIP action and
       configure supported call-delivery settings.
   * - Manage PSTN trunks
     - Create or update an inbound PSTN forwarding trunk using the dedicated
       PSTN action. DIDWW presents the applicable per-minute rate before
       creating the trunk or changing its destination.
   * - Manage phone.systems™ trunks
     - Create or update an inbound phone.systems™ trunk using the dedicated
       phone.systems™ action when the service is available for the account.
   * - Configure CNAM IN
     - Enable or disable incoming caller-name lookup on supported inbound
       trunks.
   * - Delete an inbound trunk
     - Delete a supported inbound trunk after reviewing and confirming the
       effect on its assigned phone numbers and routing.

Organize inbound routing
~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review trunk groups
     - List inbound trunk groups and review the trunks associated with each
       group.
   * - Create or update a trunk group
     - Create a trunk group, change its name, or organize supported trunks
       within it.
   * - Delete a trunk group
     - Delete a trunk group after reviewing the affected resources and
       confirming the action.
   * - Review inbound number lists
     - List number lists and review their allowed or rejected source numbers
       and prefixes.
   * - Create or update a number list
     - Create a number list or change its numbers, prefixes, and default
       behavior.
   * - Assign a number list
     - Attach a number list to a supported inbound trunk or detach the currently
       assigned list.
   * - Delete a number list
     - Delete an unused number list after confirmation. A list that is still
       assigned to a trunk must be detached before it can be deleted.

Before configuring routing
--------------------------

Make sure that:

- the phone number belongs to the active DIDWW account
- the phone number is active and supports the required service
- the account has sufficient capacity for incoming calls
- the destination is supported by the selected trunk type
- your DIDWW user has permission to manage the relevant numbers and trunks

.. note::

    If your DIDWW user can access multiple accounts, identify the account in your
    request or ask the MCP client to show the currently active account before
    making changes.

Permissions and confirmations
-----------------------------

The MCP client uses the permissions of the DIDWW user who authorized the
connection. It cannot access or change routing resources that the user is not
permitted to manage.

Requests that only review trunks or routing do not change your account. DIDWW
requires confirmation before actions such as:

- creating a PSTN trunk after presenting its per-minute rate
- changing a PSTN trunk destination after presenting the new rate
- deleting an inbound trunk
- deleting a trunk group or inbound number list

Review the active DIDWW account, selected phone numbers, routing destination,
affected resources, and any usage rates before confirming.

Your MCP client may display its own approval request before calling a DIDWW
tool. This application approval is separate from a DIDWW rate or
destructive-action confirmation.

Product requirements
--------------------

An inbound-routing request may be unavailable because of:

- the permissions assigned to the DIDWW user
- an inactive or ineligible phone number
- insufficient capacity for incoming calls
- an unsupported routing destination
- an account limit for trunks or trunk groups
- an incompatible trunk, group, or number list
- a service that is not enabled for the account

When DIDWW cannot complete a request, the response identifies the applicable
requirement or restriction when available. Use the DIDWW User Panel or contact
DIDWW Customer Support when the requested action cannot be completed through
MCP.

Current limitations
-------------------

DIDWW MCP does not currently support:

- creating or managing outbound trunks (Voice OUT)
- placing outbound calls
- submitting CNAM OUT requests

Example requests
----------------

.. dropdown:: Review current routing

   .. code-block:: text

      Show each of my Lithuanian phone numbers and the inbound trunk assigned to it.
      Do not make any changes.

.. dropdown:: Find unassigned numbers

   .. code-block:: text

      List the phone numbers that are not assigned to an inbound trunk or trunk group.
      Do not make any changes.

.. dropdown:: Assign a number to a trunk

   .. code-block:: text

      Show the proposed change for assigning +370XXXXXXXX to the SIP trunk named Support.
      Wait for my approval before applying the change.

.. dropdown:: Configure a SIP trunk

   .. code-block:: text

      Show the proposed configuration for a SIP trunk named Support.
      Explain which information you need, and wait for my approval before creating it.

.. dropdown:: Review a PSTN rate

   .. code-block:: text

      Show the applicable per-minute rate for creating a PSTN trunk that forwards calls to +370XXXXXXXX.
      Do not create the trunk until I confirm the rate.

.. dropdown:: Review a trunk group

   .. code-block:: text

      Show my inbound trunk groups and the trunks associated with each group.
      Do not make any changes.

.. dropdown:: Prepare an inbound number list

   .. code-block:: text

      Show the proposed entries for a number list that rejects calls from the prefix +XXXXXXXX.
      Wait for my approval before creating or assigning the list.




Messaging with DIDWW MCP
========================

Use DIDWW MCP to review and manage supported inbound SMS routing resources
through a connected MCP client. You can configure supported SMS trunks,
assign DID numbers, organize inbound routes into groups, and prepare SMS log
exports.

.. note::

    The available actions depend on the active DIDWW account, user permissions,
    enabled services, and the messaging capabilities of the selected DID numbers.

What you can do
---------------

Describe the result you want in plain language and identify the relevant account, DID numbers, SMS trunks, or trunk groups when possible.

Manage inbound SMS routing
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review SMS trunks
     - List SMS trunks and review their names, delivery methods, assigned DID
       numbers, and trunk-group membership.
   * - Create an SMS to Email trunk
     - Create an inbound SMS route that delivers messages received by an
       assigned DID number to an email address.
   * - Create an HTTP IN trunk
     - Create an inbound SMS route that forwards received messages to a web
       endpoint.
   * - Update an SMS trunk
     - Change the trunk name or the supported delivery settings for its
       configured type.
   * - Assign DID numbers
     - Assign one or multiple eligible DID numbers to an SMS trunk. A single
       request can include up to 100 DID numbers.
   * - Reassign DID numbers
     - Move eligible DID numbers from their current SMS route to another
       supported SMS trunk.
   * - Delete an SMS trunk
     - Delete an SMS trunk after reviewing and confirming the effect. Assigned
       DID numbers must be removed or routed elsewhere first.

Manage SMS trunk groups
~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review trunk groups
     - List SMS trunk groups and review their members and configured
       priorities.
   * - Create a trunk group
     - Create a group containing compatible inbound SMS trunks.
   * - Update a trunk group
     - Change the group name or its trunk membership.
   * - Delete a trunk group
     - Delete an SMS trunk group after reviewing and confirming the effect.
       Deleting a group also deletes its member trunks. The same delete action
       is used for a single SMS trunk and for a group.
   * - Review group membership
     - Check which inbound SMS trunks belong to a group and review their
       configured priorities.

Export SMS logs
~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Create an inbound SMS export
     - Prepare an export containing inbound SMS records for a supported date
       range.
   * - Create an outbound SMS export
     - Prepare an export containing outbound SMS records for a supported date
       range.
   * - Check export status
     - Check whether an export is pending, processing, or completed.
   * - Review existing exports
     - List SMS exports available to the active account and review their type,
       filters, and status.
   * - Download an export
     - Obtain a download link when the export is ready. DIDWW returns a direct
       link that opens without a User Panel sign-in, and a User Panel link for
       signed-in access.

Supported inbound SMS delivery
------------------------------

SMS to Email
~~~~~~~~~~~~

An SMS to Email trunk sends messages received by an assigned DID number to an
email address.

When requesting an SMS to Email trunk, identify:

- the destination email address
- the name to use for the trunk
- the required email subject and message format, when applicable

HTTP IN
~~~~~~~

An HTTP IN trunk forwards messages received by an assigned DID number to a web
endpoint.

When requesting an HTTP IN trunk, identify:

- the destination endpoint
- the name to use for the trunk
- the delivery method and formatting required by your application

For complete delivery settings and available message placeholders, see
:doc:`SMS Trunks <../../sms/sms-trunks/index>`.

Before configuring messaging
----------------------------

Make sure that:

- the DID number belongs to the active DIDWW account
- the DID number is active and supports incoming SMS
- the destination email address or web endpoint is available
- your DIDWW user has permission to manage the relevant DID numbers and SMS
  trunks
- the account has not reached its SMS trunk or trunk-group limit

.. note::

    If your DIDWW user can access multiple accounts, identify the account in your
    request or ask the MCP client to show the currently active account before
    making changes.

SMS log exports
---------------

You can request an export of inbound or outbound SMS records. When preparing an
export, identify:

- whether you need inbound or outbound SMS records
- the required date range
- the DID number, when you want to limit the export to one number

Export preparation may take several minutes. The MCP client can check the
export status and provide a download link when the file is ready. The direct
link opens the file without a User Panel sign-in, so treat it as confidential.

See :doc:`SMS Logs <../../logs-analytics/sms-logs/index>` for the available log
directions, fields, retention period, and User Panel export behavior.

.. note::
    - SMS log exports can cover the current month and the two previous months. Future dates are not supported.
    - Completed export files remain available for one month.

Permissions and confirmations
-----------------------------

The MCP client uses the permissions of the DIDWW user who authorized the
connection. It cannot access or change messaging resources that the user is not
permitted to manage.

Requests that only review SMS trunks, routing, or exports do not change your
messaging configuration. Creating, updating, assigning, or reassigning a
resource requires an explicit instruction.

Deleting an SMS trunk requires DIDWW confirmation. Review the active account,
trunk name, assigned DID numbers, and effect on SMS delivery before confirming
the deletion.

Your MCP client may display its own approval request before calling a DIDWW
tool. This application approval is separate from a DIDWW destructive-action
confirmation.

Product requirements
--------------------

A messaging request may be unavailable because of:

- the permissions assigned to the DIDWW user
- a DID number that does not support incoming SMS
- an inactive or ineligible DID number
- an invalid email address or web endpoint
- an incompatible SMS trunk or trunk group
- an account limit for SMS trunks or trunk groups
- a messaging service that is not enabled for the account

When DIDWW cannot complete a request, the response identifies the applicable
requirement or restriction when available. Use the DIDWW User Panel or contact
DIDWW Customer Support when the requested action cannot be completed through
MCP.

Current limitations
-------------------

DIDWW MCP does not currently support:

- sending an SMS message through DIDWW MCP
- managing A2P SMS campaigns or their verification requirements
- looking up inbound or outbound SMS rates
- creating or managing outbound or SMPP SMS trunks

.. note::

    Exporting outbound SMS records does not mean that sending outbound messages is
    available through MCP. Exports contain records produced by messaging services
    already used by the account.

Example requests
----------------

.. dropdown:: Review SMS trunks

   .. code-block:: text

      List my SMS trunks.
      Show their delivery types and assigned DID numbers.
      Do not make any changes.

.. dropdown:: Find eligible DID numbers

   .. code-block:: text

      Show my DID numbers that support incoming SMS.
      Identify which SMS trunk each number is assigned to.
      Do not make any changes.

.. dropdown:: Prepare an SMS to Email trunk

   .. code-block:: text

      Show the proposed configuration for an SMS to Email trunk named Billing alerts.
      Configure it to deliver messages to alerts@example.com.
      Wait for my approval before creating it.

.. dropdown:: Prepare an HTTP IN trunk

   .. code-block:: text

      Show the proposed configuration for an HTTP IN trunk named Production webhook.
      Explain which destination and delivery settings you need from me.
      Wait for my approval before creating it.

.. dropdown:: Assign a DID number

   .. code-block:: text

      Show the proposed change for assigning +12025550123 to the SMS to Email trunk named Support messages.
      Wait for my approval before applying the change.

.. dropdown:: Assign multiple DID numbers

   .. code-block:: text

      Show the proposed change for assigning +12025550123 and +12025550124 to the HTTP IN trunk named Production webhook.
      Wait for my approval before applying the change.

.. dropdown:: Review an SMS trunk group

   .. code-block:: text

      Show the SMS trunks in the group named Primary SMS routing.
      Include their configured priorities.
      Do not make any changes.

.. dropdown:: Prepare an SMS trunk group

   .. code-block:: text

      Show the proposed membership for an SMS trunk group named Primary SMS routing.
      Use the trunks Support email and Production webhook.
      Wait for my approval before creating the group.

.. dropdown:: Prepare an SMS log export

   .. code-block:: text

      Prepare an inbound SMS log export for +12025550123 for August 2026.
      Tell me when it is ready to download.

.. dropdown:: Delete an SMS trunk

   .. code-block:: text

      Delete the SMS trunk named Old webhook.
      Show me the assigned DID numbers.
      Explain the effect on SMS delivery before asking for my confirmation.


Phone numbers with DIDWW MCP
============================

Use DIDWW MCP to find and purchase phone numbers and manage numbers already
available in your account through a connected MCP client.

.. note::

    The available actions, prices, permissions, and service requirements depend on
    the active DIDWW account and the selected phone numbers.

What you can do
---------------

Describe the action or result you want in plain language. When possible, identify the relevant DIDWW account and phone numbers in your request.

Find and purchase phone numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Find available numbers
     - Search DIDWW coverage by country, area, prefix, number type, and other
       supported criteria.
   * - Review pricing
     - Compare available purchase options, setup charges, recurring charges,
       and included capacity before ordering.
   * - Purchase phone numbers
     - Purchase one or multiple phone numbers after reviewing and confirming
       the order and its charges.
   * - Order available and delayed numbers
     - Allow an order to proceed when some requested numbers are not immediately
       available and the selected offer supports back-ordering. The preview
       distinguishes numbers allocated immediately from numbers to be supplied
       later.
   * - Order immediately available numbers only
     - Require the complete quantity to be available immediately. The order does
       not proceed when the requested quantity is not currently available.

.. important::

    Availability and pricing can change between the search and the purchase. Review
    the purchase preview for the current charges and service conditions before
    confirming the order.

Immediate and delayed number allocation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When back-ordering is supported, a purchase can proceed even when the complete
quantity is not immediately available. The purchase preview or result shows:

- the quantity allocated immediately
- the quantity that will be supplied later

Review both quantities before confirming. To prevent delayed fulfillment, ask
the MCP client to purchase only when the complete quantity is available
immediately and not to place a back-order. If insufficient inventory is
available, the purchase does not proceed.

Manage phone numbers
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review phone numbers
     - List the phone numbers in your account and review a specific number's
       status, billing cycle, capacity, routing, and supported services.
   * - Update number settings
     - Change supported number settings and service assignments. Only settings
       permitted for the account and selected number can be changed.
   * - Continue automatic renewal
     - Renew a phone number every monthly billing cycle without setting an end
       date.
   * - Limit the remaining renewals
     - Renew a phone number for a specified number of additional monthly
       billing cycles, then allow it to expire.
   * - Stop number renewal
     - Keep a phone number active until its current expiration date, then allow
       it to expire. Renewal can be resumed before the number expires.
   * - Remove a number from emergency calling
     - Detach a phone number from its emergency calling service. Its emergency
       calling charge stops from the next renewal. If no numbers remain, DIDWW
       automatically cancels the service within a few hours and notifies the
       customer.
   * - Review number history
     - Review recent purchases, renewals, cancellations, and restorations for a
       phone number.
   * - Terminate a phone number
     - Terminate a number immediately after reviewing and confirming the
       effect. Incoming calls and SMS stop immediately, and the number is
       released from the account.
   * - Restore a phone number
     - Restore a recently terminated number when it is still eligible for
       restoration and the account has sufficient balance.
   * - Review active routing
     - Check whether a phone number is assigned to an inbound trunk or trunk
       group.

After a renewal change, the MCP client returns the resulting expiration date
and renewal setting.

Only removal from an emergency calling service is supported through the
phone number update. To assign a number, follow the emergency verification
flow described in :doc:`Emergency calling with DIDWW MCP <emergency-calling>`.

Stop renewal or terminate immediately
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the objective is only to stop future renewal charges, stop renewal instead
of terminating the phone number. The number remains fully usable until its
current expiration date, and renewal can be resumed before it expires.

Terminate a phone number only when it must be removed immediately. Termination
stops inbound calls and SMS and removes the number from the account. A
terminated number can generally be restored for approximately 35 days while it
remains in the terminated state. After that period, it can return to public
availability and may be permanently lost.

A phone number on a still-pending order is canceled with a refund instead. A
phone number purchased through a Bulk Order cannot be terminated through this
action.

Phone numbers and inbound routing
---------------------------------

Purchasing a phone number does not automatically configure it to receive calls.
Assign the number to a supported inbound trunk or trunk group after the
purchase.

Some phone numbers also require additional capacity before they can receive
incoming calls.

See :doc:`Inbound routing with DIDWW MCP <inbound-routing>` to learn which
routing actions can be completed through a connected MCP client.

Permissions and confirmations
-----------------------------

The MCP client uses the permissions of the DIDWW user who authorized the
connection. It cannot access phone numbers that the user is not permitted to
access.

Requests that only find or review information do not change your account. DIDWW
requires confirmation before:

- purchasing phone numbers, including accepting delayed fulfillment
- terminating a phone number immediately

Changing renewal settings or removing a number from emergency calling does not
use DIDWW's two-step confirmation flow. Removing a number from emergency
calling requires emergency calling management permission.

Review the active DIDWW account, selected location, quantity, one-time charges,
recurring charges, service conditions, affected routing, effect on incoming
calls and SMS, and restoration conditions before confirming.

Your MCP client may display its own approval request before calling a DIDWW
tool. This application approval is separate from a DIDWW purchase or
destructive-action confirmation.

Product requirements
--------------------

A phone-number request may be unavailable because of:

- the permissions assigned to the DIDWW user
- phone-number availability
- insufficient account balance
- country or number-type restrictions
- end-user verification requirements
- a required service that is not enabled for the account

When DIDWW cannot complete a request, the response identifies the applicable
requirement or restriction when available.

If the prepaid balance is insufficient, add funds through `Payment Methods in
the DIDWW User Panel <https://my.didww.com/#/payment_methods>`_, then request a
new purchase preview. DIDWW MCP cannot charge a payment card or add funds to
the account.

Use the DIDWW User Panel or contact DIDWW Customer Support when another
requested action cannot be completed through MCP.

Current limitations
-------------------

DIDWW MCP does not currently support:

- creating or managing number porting requests
- submitting CNAM OUT requests
- creating, applying, or managing configuration profiles
- selecting a specific premium or golden phone number

Use the DIDWW User Panel for actions that are not currently available through
MCP.

Example requests
----------------

.. dropdown:: Find numbers without purchasing

   .. code-block:: text

      Find available toll-free phone numbers in the United States.
      Show the setup and monthly charges. Do not purchase anything.

.. dropdown:: Review a purchase

   .. code-block:: text

      I need one geographic phone number in Vilnius, Lithuania.
      Show the complete purchase preview, including one-time and recurring
      charges. Do not place the order until I confirm it.

.. dropdown:: Purchase only immediately available numbers

   .. code-block:: text

      I need five geographic phone numbers in Vilnius, Lithuania.
      Purchase them only if all five are available immediately.
      Do not place a back-order or complete the purchase until I confirm it.

.. dropdown:: Review immediate and delayed quantities

   .. code-block:: text

      Prepare a preview for purchasing ten geographic phone numbers in Berlin,
      Germany. Show how many numbers will be allocated immediately and how many
      will be supplied later. Do not complete the purchase until I confirm it.

.. dropdown:: Review your phone numbers

   .. code-block:: text

      Show my Lithuanian phone numbers, their current status, and whether they
      are assigned to an inbound trunk. Do not make any changes.

.. dropdown:: Stop number renewal

   .. code-block:: text

      Show what will happen if I stop renewing +370XXXXXXXX.
      Do not make the change until I approve it.

.. dropdown:: Resume automatic renewal

   .. code-block:: text

      Resume automatic monthly renewal for +370XXXXXXXX.
      Show its resulting expiration date and renewal setting.

.. dropdown:: Set the remaining renewal cycles

   .. code-block:: text

      Renew +370XXXXXXXX for three more monthly billing cycles.
      Show its resulting expiration date and renewal setting.

.. dropdown:: Remove a number from emergency calling

   .. code-block:: text

      Show the emergency calling service assigned to +370XXXXXXXX.
      Explain when its charge will stop and whether removing it will cancel
      the service.
      Remove the number only after I approve the proposed change.

.. dropdown:: Terminate a phone number immediately

   .. code-block:: text

      I want to terminate +370XXXXXXXX immediately.
      Show its current routing, assigned services, and the effect on incoming
      calls and SMS.
      Explain the restoration period and wait for my confirmation.

.. dropdown:: Review number history

   .. code-block:: text

      Show the recent purchase, renewal, cancellation, and restoration history for +370XXXXXXXX.


Users and invitations with DIDWW MCP
====================================

Use DIDWW MCP to review who can access the active DIDWW account and manage
supported user invitations through a connected MCP client.

.. note::

   Users and invitations are available through DIDWW MCP only to users with
   the **Admin** role. MCP responses return this role under its internal name,
   ``SuperAdmin``.

What you can do
---------------

Describe the information or result you want in plain language. When possible,
identify the active DIDWW account, user, invitation email address, or required
roles.

Review account access
~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Review account users
     - List users who can access the active DIDWW account and review their
       email addresses and assigned roles.
   * - Review access information
     - Review whether a user is the account owner, whether two-factor
       authentication is enabled, and the available last-login information.
   * - Review invitation roles
     - Review the supported roles that can be assigned when preparing a new
       invitation.
   * - Review pending invitations
     - List pending invitations for the active account and review their email
       addresses, assigned roles, and statuses.

Manage invitations
~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Prepare a new invitation
     - Prepare an invitation for an email address with one or more supported
       roles. DIDWW shows the email address, assigned roles, and active account
       before sending the invitation.
   * - Cancel a pending invitation
     - Cancel an invitation that is still pending. An invitation that has
       already been accepted or canceled cannot be canceled again.

How users and invitations relate
--------------------------------

A user-access record represents a user who can already access the active
DIDWW account. The user's assigned roles determine which account information
and actions are available to them.

A pending invitation does not provide account access until the recipient
accepts it. Canceling a pending invitation prevents it from being used to
join the account.

User access and invitations belong to a specific DIDWW account. If you can
access multiple accounts, verify the active account before reviewing users or
preparing an invitation.

Before inviting a user
----------------------

Before asking the MCP client to prepare an invitation, verify:

- the active DIDWW account
- the recipient's email address
- the roles the recipient requires
- the account access those roles will provide

Assign only the roles required for the recipient's work. For detailed role
permissions, see :doc:`Users and roles
<../../account-settings/adding-new-roles>`.

Permissions and confirmations
-----------------------------

Only a user with the **Admin** role can review account users or manage
invitations through DIDWW MCP.

Reviewing account users, roles, and pending invitations does not change the
account.

Creating an invitation uses DIDWW two-step confirmation. The MCP client
first presents a preview containing the active account, recipient email
address, and assigned roles. DIDWW sends the invitation email only after you
confirm the preview.

A confirmation applies only to the invitation shown in the preview. If the
email address, active account, or assigned roles change, DIDWW requires a new
preview and confirmation.

Canceling an invitation is available only while the invitation is pending.
Review the email address, roles, status, and active account before requesting
cancellation.

Privacy and security
--------------------

User and invitation information returned through DIDWW MCP is processed by
the connected AI provider under its terms and privacy policy. Depending on the
request, this information can include:

- user and invitation email addresses
- assigned roles
- account-owner status
- two-factor authentication status
- last-login information

Request only the information needed for the account-access task. Verify the
recipient's email address before confirming an invitation because DIDWW sends
the invitation to that address.

DIDWW MCP does not expose API keys or other account secrets. Do not enter API
keys, passwords, or two-factor authentication codes in an AI conversation.

Product requirements
--------------------

A user or invitation request may be unavailable because:

- your DIDWW user does not have the **Admin** role
- the selected user or invitation belongs to another DIDWW account
- an invitation is no longer pending
- the email address or selected roles are not accepted

When possible, the response identifies the applicable requirement or explains
which action must be completed in the DIDWW User Panel.

Current limitations
-------------------

DIDWW MCP does not support:

- changing the roles assigned to an existing user
- revoking an existing user's account access
- listing invitations that are no longer pending
- canceling an invitation that has already been accepted or canceled
- listing, creating, editing, exposing, or deleting API keys

Use the DIDWW User Panel to change an existing user's roles or revoke their
account access.

Example requests
----------------

.. dropdown:: Review account users

   .. code-block:: text

      Show the users who can access the active DIDWW account.
      Include their roles, owner status, two-factor authentication status,
      and available last-login information.
      Do not make any changes.

.. dropdown:: Review invitation roles

   .. code-block:: text

      Show the roles that can be assigned in a new DIDWW user invitation.
      Do not create or send an invitation.

.. dropdown:: Review pending invitations

   .. code-block:: text

      Show the pending invitations for the active DIDWW account.
      Include each email address, assigned roles, and invitation status.
      Do not cancel or send any invitations.

.. dropdown:: Prepare a user invitation

   .. code-block:: text

      Prepare an invitation for ops@example.com with the Technical role.
      Show the active account, email address, and assigned role.
      Do not send the invitation until I confirm it.

.. dropdown:: Cancel a pending invitation

   .. code-block:: text

      Find the pending invitation for ops@example.com.
      Show its active account, assigned roles, and current status.
      Explain what cancellation will do and wait for my instruction.


Capacity with DIDWW MCP
=======================

Use DIDWW MCP to review capacity, purchase flat-rate channels, assign
purchased channels, and manage supported capacity groups.

Capacity determines how many simultaneous incoming calls DIDWW can deliver.
For complete explanations of included, dedicated, shared, metered, and hybrid
capacity, capacity modes, and capacity priority, see :doc:`How capacity works
<../../phone-numbers/capacity/how-capacity-works>`.

What you can do
---------------

Describe the required result in plain language. When possible, identify the
active DIDWW account, relevant DID numbers, and expected number of simultaneous
incoming calls.

Review capacity
~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - Available information
   * - Review capacity pools
     - Review supported countries, flat-rate channel prices, metered rates,
       purchased and unassigned channels, allocations, and renewal information.
   * - Review capacity groups
     - Review each group's capacity pool, shared channels, metered channel
       limit, and assigned DID numbers.
   * - Review a DID number
     - Review its current capacity mode, included channels, dedicated channels,
       and capacity-group assignment.
   * - Check an assignment
     - Check whether a compatible pool has enough unassigned flat-rate channels
       for a proposed dedicated or shared assignment.

Purchase flat-rate channels
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Flat-rate channels are purchased from a compatible capacity pool using funds
already available in the active account's prepaid balance.

Before completing a purchase, DIDWW shows a preview that includes the active
account, capacity pool, channel quantity, price, renewal information, and
whether the purchase is refundable. The purchase is completed only after the
preview is confirmed.

If the prepaid balance is insufficient, add funds through `Payment Methods in
the DIDWW User Panel <https://my.didww.com/#/payment_methods>`_, then request a
new purchase preview. DIDWW MCP cannot charge a payment card or add funds to the
account.

Assign capacity
~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What changes
   * - Assign dedicated channels
     - Reserves purchased flat-rate channels from a compatible pool for one DID
       number.
   * - Change a dedicated assignment
     - Increases, decreases, or removes a DID number's dedicated-channel
       assignment. Released channels remain purchased and become unassigned in
       the pool.
   * - Assign a DID number to a capacity group
     - Allows the DID number to use the group's shared or metered channels.
   * - Unassign a DID number from a capacity group
     - Stops the DID number from using that group's capacity.

Assigning channels that are already purchased does not buy additional
capacity. These assignments are reversible.

Manage capacity groups
~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Action
     - What you can request
   * - Create a capacity group
     - Create a group in a selected capacity pool with shared channels, metered
       channels, or both.
   * - Update a capacity group
     - Change its name, shared-channel allocation, or metered-channel limit.
   * - Assign or unassign DID numbers
     - Add eligible DID numbers to a compatible group or remove them after
       reviewing the effect on incoming-call capacity.
   * - Delete a capacity group
     - Delete an empty group and return its shared channels to the pool as
       unassigned purchased capacity.

Before making changes
---------------------

Check that:

- the expected DIDWW account is active
- the selected capacity pool supports the countries of the DID numbers
- enough unassigned flat-rate channels are available for an assignment
- the prepaid balance is sufficient for a channel purchase
- the DIDWW user has permission to manage the relevant DID numbers and capacity

A request can also be rejected when a product validation applies. The MCP
client returns the available reason when the request cannot be completed.

Confirmations and approvals
---------------------------

DIDWW confirmation and MCP client tool approval are separate controls.

.. list-table::
   :header-rows: 1
   :widths: 45 27 28

   * - Action
     - DIDWW confirmation
     - MCP client approval
   * - Review capacity
     - No
     - May be displayed by the client.
   * - Purchase flat-rate channels
     - Yes. DIDWW returns a purchase preview before changing the account.
     - May also be displayed by the client.
   * - Create a capacity group
     - Yes. DIDWW returns a preview before creating the group.
     - May also be displayed by the client.
   * - Update a capacity group
     - Required when the change increases metered capacity. Other supported
       updates do not use DIDWW confirmation.
     - May be displayed by the client.
   * - Delete a capacity group
     - Yes. DIDWW returns a deletion preview before removing the group.
     - May also be displayed by the client.
   * - Assign or unassign purchased channels or DID numbers
     - No
     - May be displayed by the client.

An MCP client's approval prompt authorizes it to call a DIDWW tool. When DIDWW
confirmation is required, the first call returns a preview and makes no change.
The action is completed only after that DIDWW preview is confirmed.

Current limitations
-------------------

DIDWW MCP does not currently support:

- viewing detailed capacity usage or exceeded-capacity events
- changing a DID number's current or next capacity mode
- reducing the total number of purchased flat-rate channels

Use the DIDWW User Panel for these actions. DIDWW MCP can release dedicated or
shared assignments, but the released flat-rate channels remain purchased in the
capacity pool.

Example requests
----------------

.. dropdown:: Review a DID number's capacity

   .. code-block:: text

      Show the current capacity for +370XXXXXXXX.
      Include its capacity mode, included and dedicated channels,
      and capacity-group assignment. Do not make any changes.

.. dropdown:: Review compatible capacity pools

   .. code-block:: text

      Show the capacity pools that support my Lithuanian DID numbers.
      Include flat-rate prices, metered rates, purchased channels,
      unassigned channels, and renewal information.
      Do not purchase or assign anything.

.. dropdown:: Review a channel purchase

   .. code-block:: text

      Show the purchase preview for five flat-rate channels in a compatible
      capacity pool. Include the price, renewal information, and balance.
      Do not complete the purchase until I confirm it.

.. dropdown:: Assign dedicated channels

   .. code-block:: text

      Check whether three unassigned flat-rate channels can be assigned to
      +370XXXXXXXX as dedicated capacity.
      Show the current and proposed assignments before making the change.

.. dropdown:: Create a shared capacity group

   .. code-block:: text

      Prepare a capacity group named Lithuania Support with five shared
      flat-rate channels for +370XXXXXXXX and +370YYYYYYYY.
      Show the pool, available channels, and proposed assignments.
      Do not create the group until I confirm it.

.. dropdown:: Configure metered overflow

   .. code-block:: text

      Show a proposed capacity group for my Sales DID numbers.
      Use five shared flat-rate channels and allow up to 20 simultaneous
      metered calls for overflow. Include the applicable rates.
      Do not create or change anything until I confirm it.

.. dropdown:: Change an existing assignment

   .. code-block:: text

      Show the current capacity configuration for +370XXXXXXXX.
      Assign it to the capacity group named Lithuania Support and explain
      which capacity it can use after the change.

.. dropdown:: Delete a capacity group

   .. code-block:: text

      Review the capacity group named Old Overflow.
      Show its assigned DID numbers and allocated channels.
      Explain the effect of deleting it.
      Do not delete the group until I confirm it.


.. _didww_api_v34:
.. _didww_api_v33:
.. _didww_api_v32:
.. _didww_api_v31:
.. _didww_api_v30:
.. _user_panel_api:

API Documentation v2026-04-16 (Latest Version)
==============================================

The DIDWW API is a REST-based service that enables seamless integration of your applications with DIDWW services.
It allows you to manage phone numbers, configure services, set capacities, create SIP trunks, and retrieve call detail records (CDRs) and other operational data.

This API is ideal for building custom dashboards, developing mobile applications, and automating both front-end and back-end processes.

The API is fully compliant with the `JSON API <https://jsonapi.org/format/>`_ specification, which standardizes how applications request and modify resources, and how servers respond to those requests. It provides a straightforward set of HTTP endpoints that support **GET, PUT, POST, PATCH, and DELETE** methods, enabling seamless access to our services.

.. note::

 This documentation assumes familiarity with web programming concepts, JSON data formats, and the JSON API specification. For additional details, refer to the `JSON API official website <https://jsonapi.org/format/>`_.

Getting started with DIDWW API
----------------------------------

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`light-bulb` **Getting Started**
      :link: ../configuration
      :link-type: doc
      :text-align: left

      Learn how to configure and authenticate your setup to begin using the DIDWW API.

   .. grid-item-card:: :octicon:`terminal` **API Requests in Postman**
      :link: ../postman
      :link-type: doc
      :text-align: left

      Learn how to use the DIDWW API using Postman.

   .. grid-item-card:: :octicon:`code` **Use Case Examples**
      :link: ../examples/index
      :link-type: doc
      :text-align: left

      Explore practical examples demonstrating how to integrate and use the DIDWW API.

   .. grid-item-card:: :octicon:`file-code` **Specification**
      :link: ../specification/index
      :link-type: doc
      :text-align: left

      Review the detailed API specification, endpoints, and supported parameters.

   .. grid-item-card:: :octicon:`tools` **SDKs and Tools**
      :link: user-panel-api-sdks-and-tools
      :link-type: ref
      :text-align: left

      Access official SDKs, client libraries, and integration tools for the DIDWW API.

   .. grid-item-card:: :octicon:`versions` **API Versioning**
      :link: ../api-versioning
      :link-type: doc
      :text-align: left

      Understand how versioning works to maintain compatibility across API updates.

API versions
------------

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`versions` **Version (Latest) 2026-04-16**
      :link: overview
      :link-type: doc
      :text-align: left

      .. raw:: html

         <br></br>

   .. grid-item-card:: :octicon:`versions` **Version 2022-05-10**
      :link: ../2022-05-10/overview
      :link-type: doc
      :text-align: left

      .. raw:: html

         <br></br>

   .. grid-item-card:: :octicon:`versions` **Version 2021-12-15**
      :link: ../2021-12-15/overview
      :link-type: doc
      :text-align: left

      .. raw:: html

         <br></br>

   .. grid-item-card:: :octicon:`versions` **Version 2021-04-19**
      :link: ../2021-04-19/index
      :link-type: doc
      :text-align: left

      .. raw:: html

         <br></br>

   .. grid-item-card:: :octicon:`versions` **Version 2017-09-18**
      :link: ../2017-09-18/index
      :link-type: doc
      :text-align: left

      .. raw:: html

         <br></br>

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Introduction

  Getting Started <../configuration.rst>
  API Requests in Postman <../postman.rst>
  SDKs and Tools <../sdks-and-tools.rst>
  Use Case Examples <../examples/index.rst>
  Specification <../specification/index.rst>
  API Versioning <../api-versioning.rst>

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: API Documentation v2026-04-16 (Latest)

   Overview <overview>
   Coverage Resources <coverage-resources/index>
   Inventory Resources <inventory-resources/index>
   Regulation Resources <regulation-resources/index>
   Emergency Resources <emergency-resources/index>
   Export <export/index>
   Common Definitions <common-definitions/index>
   Callback Details <callbacks-details>
   Changelog <changelog>

.. |postman| image:: /img/postman/postman.svg
   :class: inline-img no-shadow no-border
   :width: 24px
   :height: 24px



.. _user-panel-api:

Getting Started
===============

The DIDWW API v3 provides a powerful interface for programmatically managing phone number inventory, ordering, and service configurations. This guide explains how to authenticate using API keys, work in different environments, manage API versioning, and use SDKs and tools for integration.

----

.. raw:: html

    <br>

API Authentication and Keys
----------------------------

To interact with the DIDWW API, you need to obtain and configure an API Security Key. Follow the steps below to get started.

.. _api_key:

How to Get Your API Key
^^^^^^^^^^^^^^^^^^^^^^^^

1. Sign in to your `DIDWW Account <https://my.didww.com/#/users/sign_in>`_ for production, or to your `DIDWW Sandbox Account <https://my-sandbox.didww.com/#/users/sign_in>`_ for sandbox.
2. Navigate to the **API** section in the left-hand menu.
3. Select the **DIDWW API 3**.
4. Click on **Create new API Key**.

.. figure:: https://doc.didww.com/_images/create_new_api_key.png
   :figclass: align-center
   :alt: Create new API Key button.

   **Fig. 1.** Create new API Key button.

5. In the **Create API Key** form:

   - **Friendly name**: Enter a descriptive name for the key (e.g., Production Key, Integration Test).
   - **Access IP's**: Optionally restrict access by specifying allowed IP addresses (e.g., `192.0.2.0/24`).
   - **Enable callbacks**: Activate this option to allow DIDWW to send real-time HTTP notifications for events such as order updates, export completion, address verifications, and voice out trunk status changes.

6. Click **Submit**. A new key will be added to the **API Keys** table.

.. figure:: https://doc.didww.com/_images/create_new_api_key2.png
   :figclass: align-center
   :alt: Creating a new API Key in the DIDWW User Panel.

   **Fig. 2.** Creating a new API Key in the DIDWW User Panel.

.. note::

   - Include the API key in your request headers using the ``Api-Key`` prefix.
   - Each API key is limited to **20 requests per second** to ensure consistent performance across all users. If this limit is exceeded, the API will return an HTTP **429 Too Many Requests** error.
   - To obtain a sandbox API key, contact the `DIDWW Technical Support Team <https://www.didww.com/contacts>`_.

----

.. raw:: html

    <br>

.. _api-environments:

API Environments
-----------------

DIDWW provides two separate environments for API integration:

    - **Production environment**: Used for live operations involving actual number inventory and billing.
    - **Sandbox environment**: Used for development and testing purposes, simulating production behavior without affecting real data or incurring charges.

The sandbox environment mirrors the functionality of the production environment, making it ideal for validating API requests, application logic, and workflow integration before going live. No actual number provisioning or billing operations occur in the sandbox.

Production environment
^^^^^^^^^^^^^^^^^^^^^^^

::

   https://api.didww.com/v3/

Sandbox environment
^^^^^^^^^^^^^^^^^^^^^^^

::

   https://sandbox-api.didww.com/v3/

----

.. raw:: html

    <br>

.. _user-panel-api-sdks-and-tools:

SDKs and Tools
---------------

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
      :link: https://github.com/didww/didww-api-3-php-sdk
      :link-type: url
      :text-align: left

      Access the official PHP SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
      :link: https://github.com/didww/didww-api-3-java-sdk
      :link-type: url
      :text-align: left

      Access the official Java SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
      :link: https://github.com/didww/didww-api-3-python-sdk
      :link-type: url
      :text-align: left

      Access the official Python SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
      :link: https://github.com/didww/didww-api-3-typescript-sdk
      :link-type: url
      :text-align: left

      Access the official TypeScript SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`material-icon-theme:go` **Go SDK**
      :link: https://github.com/didww/didww-api-3-go-sdk
      :link-type: url
      :text-align: left

      Access the official DIDWW API client SDK for the Go programming language.

   .. grid-item-card:: :iconify:`devicon:dot-net` **.NET SDK**
      :link: https://github.com/didww/didww-api-3-dotnet-sdk
      :link-type: url
      :text-align: left

      Access the official DIDWW API client SDK for the .NET platform.

   .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Client**
      :link: https://github.com/didww/didww-v3-ruby
      :link-type: url
      :text-align: left

      Use the official Ruby client for interacting with the DIDWW API.

   .. grid-item-card:: :iconify:`skill-icons:rails` **Ruby on Rails Sample App**
      :link: https://github.com/didww/didww-v3-rails-sample
      :link-type: url
      :text-align: left

      View a sample Rails app showing how to integrate with the DIDWW API.

   .. grid-item-card:: :iconify:`devicon:postman` **Postman Public Workspace**
      :link: https://www.postman.com/didww-api/workspace/didww-api3-documentation
      :link-type: url
      :text-align: left

      Explore DIDWW API endpoints in the Postman public workspace.

.. raw:: html

    <br>

API Use Case Examples
---------------------

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: **Buy a DID Number That Requires Verification**
      :link: user-panel-api-examples-verification
      :link-type: ref
      :text-align: center

      Learn how to purchase and verify a DID number when regulatory requirements apply.

   .. grid-item-card:: **Buy Numbers from a Specific DID Group**
      :link: user-panel-api-examples-random-dids
      :link-type: ref
      :text-align: center

      Learn how to select and purchase numbers from a specific DID group using API v3.

   .. grid-item-card:: **Buy a Specific Number from DID Inventory**
      :link: user-panel-api-examples-available-dids
      :link-type: ref
      :text-align: center

      Learn how to select and purchase a specific number from available DID inventory using API v3.

   .. grid-item-card:: **Register Emergency Calling Service**
      :link: api-examples-register-emergency-calling-service
      :link-type: ref
      :text-align: center

      Learn how to register existing DIDs for emergency calling by using emergency requirements, validations, and verifications.

   .. grid-item-card:: **Update Emergency Calling Service**
      :link: api-examples-update-emergency-calling-service
      :link-type: ref
      :text-align: center

      Learn how to replace the address of an existing emergency calling service by submitting a new emergency verification.

.. raw:: html

    <br>

.. raw:: html

    <style>
        .rst-content .section ul, .rst-content .toctree-wrapper ul, .rst-content section ul, .wy-plain-list-disc, article ul {
            margin-bottom: 0px;
            vertical-align: middle;
        }

    .sd-tab-content {
        box-shadow: none;
    }
    .sd-tab-set>label {
        border-color: var(--sd-color-tabs-underline);
        color: inherit;
    }

    /* Green check-circle */
    .sd-octicon-x-circle {
        color: #d73a49;
        fill: currentColor;
    }

    /* Red x-circle */
    .sd-octicon-check-circle {
        color: #28a745;
        fill: currentColor;
    }

    .hide-table {
        display: none;
    }

    </style>

.. raw:: html

   <style>
     em {
       font-size: 115%;
       font-weight: 700 !important;
       font-style: normal !important; /* Removes italic if desired */
       font-family: Roobert-semibold !important;
     }
   </style>

.. raw:: html

    <style>

    img.inline-img.no-shadow.black-end-white-monday {
        height: 25px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.black-end-white-zoho {
        filter: invert(1);
        height: 37px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
    }

    img.inline-img.no-shadow.no-border {
        border-radius: 0px !important;
    }

    img.inline-img.no-shadow.no-top-margin.wide-img {
        height: 74px !important;          /* Lock the height */
        width: auto !important;           /* Allow proportional width scaling */
        max-height: 74px;                 /* Prevent vertical expansion */
        margin-top: 0 !important;         /* Remove top margin */
        padding-top: 0 !important;        /* Remove top padding */
        line-height: 0;                   /* Prevents line-height gaps */
        vertical-align: middle;           /* Align inline properly */
        object-fit: contain;              /* Ensures no distortion */
    }

        /* Make sure the parent container has a relative position if needed */
    .section-container {
      position: relative;
    }

    /* Light mode: show the SVG as a background element */
    html.light .styles_waves__tcfLl {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;    /* Adjust width as necessary */
      height: auto;   /* If needed you can set a fixed height */
      z-index: -1;    /* Place it behind all other content */
      pointer-events: none; /* Ensure it won't capture mouse events */
    }

    /* Dark mode: hide the SVG background */
    html.dark .styles_waves__tcfLl {
      display: none;
    }

        .styles_title__pmgeW {
            font-size: 64px;
            line-height: 76.8px;
            color: #023f7f
        }

      :root {
        /* LIGHT THEME */
        --sd-color-primary: #005fcc;
        --sd-color-card-background: var(--sd-color-card-background);
        --sd-color-card-text: #1e1e1e;
        --sd-color-card-border: #d1d5db;
        /* Shadow variable removed from use */

        --sy-c-border: #d1d5db;
        --sy-c-bold: #374151;
        --gray-1: #e5e7eb;
        --sd-gutter-x: 1rem;
        --sd-gutter-y: 1rem;
        --page-background: #ffffff;
      }

      [data-theme="dark"],
      html.dark {
        /* DARK THEME */
        --sd-color-card-background: #111111;
        --sd-color-card-text: #f9f9f9;
        /* No shadow is applied */

        --sy-c-border: #4b5563;
        --sy-c-bold: #fff;
        --page-background: #000000;
      }

      html, body {
        background-color: var(--page-background);
        color: var(--sd-color-card-text);
        transition: background-color 0.3s ease, color 0.3s ease;
      }

      /* This style mirrors your .sd-card and .sd-text-center rules without any box-shadow.
         It uses the theme colors and spacing, and includes a small hover scale effect */
      .surface {
        background-color: var(--sd-color-card-background);
        color: var(--sd-color-card-text);
        border: 1px solid var(--sd-color-card-border);
        border-radius: 15px;
        padding: var(--sd-gutter-y) var(--sd-gutter-x);
        transition: background-color 0.3s ease, color 0.3s ease, transform 0.15s ease-in-out;
        width: 100%;
        box-sizing: border-box;
      }

      .surface:hover {
        transform: scale(1.02);
      }

      /* Optional grid layout to display items in a row */
      .surface-grid {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: var(--sd-gutter-x);
        width: 100%;
      }

      @media (max-width: 991.98px) {
        .surface-grid {
          grid-template-columns: 1fr;
        }
      }

        /* Responsive Columns: Four */
    @media (min-width: 1728px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1532px) and (max-width: 1727.98px),
           (min-width: 992px) and (max-width: 1127.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1128px) and (max-width: 1531.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 24rem;
      }
    }

    @media (min-width: 768px) and (max-width: 991.98px),
           (min-width: 576px) and (max-width: 767.98px),
           (max-width: 575.98px) {
      .sd-row-cols-md-3 > *,
      .sd-row-cols-sm-3 > * {
        min-width: 100%;
      }
    }

    .sd-card-body {
        -ms-flex: 1 1 auto;
        flex: 1 1 auto;
        padding: 2rem 2rem 2rem 2rem;
    }

    .. .sd-row {
        margin-top: calc(var(--sd-gutter-y) * 3);
    }

    </style>


.. _api_requests_in_postman:

=======================
API Requests in Postman
=======================

Postman is a graphical tool for building, sending, and debugging API requests without writing code.
You can use it to explore the DIDWW API, inspect responses, confirm your API keys, and prototype integrations before adding them to your application.

----

.. raw:: html

   <br>

Before You Begin
----------------

- An active account with DIDWW is required. `Create Your Account <https://my.didww.com/users/sign_up>`_.
- Create at least one active API key in the DIDWW User Panel. See :doc:`Create API Key <configuration>`.
- It is recommended to install the Postman application. `Download Postman <https://www.postman.com/downloads/>`_.
- Sign in to an active Postman account. `Create an account <https://identity.getpostman.com/signup>`_.

----

.. raw:: html

   <br>

Step 1: Fork the DIDWW API Collection
-------------------------------------

Create a personal copy of the official DIDWW API collection in your Postman workspace so you can edit and test the requests.

.. raw:: html

   <div class="postman-run-button"
   data-postman-action="collection/fork"
   data-postman-var-1="23329000-94fb7eaa-e6d9-48cb-913f-2d03976de8cc"
   data-postman-collection-url="entityId=23329000-94fb7eaa-e6d9-48cb-913f-2d03976de8cc&entityType=collection&workspaceId=c7e9c67d-ac71-4c91-a5ef-b12f6619f415"
   data-postman-param="env%5BDIDWW%20Sandbox%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoieW91ckRpZHd3QXBpS2V5IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoieW91ckRpZHd3QXBpS2V5Iiwic2Vzc2lvbkluZGV4IjoxfV0=">
   </div>
   <p></p>
   <script type="text/javascript">
   (function (p,o,s,t,m,a,n) {
   !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
   !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
   (n = o.createElement("script")),
   (n.id = s+t), (n.async = 1), (n.src = m), n
   ));
   }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
   </script>

Use the button above to fork the latest DIDWW API3 collection directly, or follow the manual steps below.

Open the DIDWW Workspace
^^^^^^^^^^^^^^^^^^^^^^^^

1. Open the official `DIDWW API Postman Workspace <https://www.postman.com/didww-api/workspace/didww-api3-documentation/overview>`_.
2. If you are not already signed in, Postman will prompt you to log in.

.. figure:: https://doc.didww.com/_images/fig1.png
   :alt: Postman sign-in screen.
   :figclass: align-center
   :width: 100%

   Fig. 1. Postman sign-in screen.

Fork the Collection
^^^^^^^^^^^^^^^^^^^

1. In the left sidebar, locate the latest **DIDWW API3** collection version.
2. Click the **Actions (···)** button next to the collection name and choose **Fork** to create a personal copy in your workspace.

.. figure:: https://doc.didww.com/_images/fig2.png
   :alt: Actions and Fork Button.
   :figclass: align-center
   :width: 100%

   Fig. 2. Actions and Fork Button.

3. Enter a **Fork label** and select your **Workspace**.
4. (Optional) Select the **Environment to fork** or :ref:`configure the environments later <api_using_postman_environment>`.
5. (Optional) Enable **Watch original collection** if you want to be notified about changes to the original collection.
6. Click **Fork Collection**.

.. figure:: https://doc.didww.com/_images/fig3.png
   :alt: Forking the DIDWW API collection into your workspace.
   :figclass: align-center
   :width: 100%

   Fig. 3. Forking the collection into your personal workspace.

Open the Collection in the Postman Application
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Open the **Postman App**. Your personal copy of the collection appears automatically.

.. figure:: https://doc.didww.com/_images/fig3.5.png
   :alt: Forked collection in the Postman App.
   :figclass: align-center
   :width: 100%

   Fig. 4. Forked collection in the Postman App.

----

.. raw:: html

   <br>

.. _api_using_postman_environment:

Step 2: Configure Environments
------------------------------

Use Postman **Environments** to store the hostname and API key for each API mode.
This helps you switch between production and sandbox environments safely and reduces the chance of using the wrong API key or host.

.. grid:: 1 1 1 2
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`beaker` **Sandbox Environment**
      :link: api_using_postman_environment_sandbox
      :link-type: ref
      :text-align: left

      Configure the host and apiKey variables for the Sandbox API.

   .. grid-item-card:: :octicon:`server` **Production Environment**
      :link: api_using_postman_environment_prod
      :link-type: ref
      :text-align: left

      Configure the host and apiKey variables for the Production API.

.. raw:: html

   <br>

.. _api_using_postman_environment_sandbox:

Configure the Sandbox Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Click on the **+** symbol to the left of the **Search environments** bar to create another environment.
2. Name it, for example: **DIDWW Sandbox**.
3. Add the following variables:

   .. list-table::
      :header-rows: 1
      :widths: 20 30 50

      * - **Variable**
        - **Value**
        - **Description**
      * - ``host``
        - ``sandbox-api.didww.com``
        - Hostname for the **sandbox** API.
      * - ``apiKey``
        - ``<YOUR_SANDBOX_API_KEY>``
        - Your sandbox API key from the User Panel.

.. note::

    - If you do not have a sandbox account or API key, contact `support@didww.com <mailto:support@didww.com>`_.

    - The DIDWW Postman collection uses ``{{host}}`` to build URLs (for example: ``https://{{host}}/v3/dids``).  Enter only the hostname (for example, ``sandbox-api.didww.com``) without ``https://`` or ``/v3``.

.. figure:: https://doc.didww.com/_images/fig5.png
   :alt: Sandbox environment configured with host and apiKey.
   :figclass: align-center
   :width: 100%

   **Fig. 6.** Example Sandbox Environment.

.. _api_using_postman_environment_prod:

Configure the Production Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. In Postman, go to the **Environments** tab.
2. Click the **+** symbol to the left of the **Search environments** bar to create a new environment.
3. Name it, for example: **DIDWW Production**.
4. Add the following variables:

   .. list-table::
      :header-rows: 1
      :widths: 20 30 50

      * - **Variable**
        - **Value**
        - **Description**
      * - ``host``
        - ``api.didww.com``
        - Hostname for the **production** API.
      * - ``apiKey``
        - ``<YOUR_PRODUCTION_API_KEY>``
        - Your production API key from the User Panel.

.. note::

    The DIDWW Postman collection uses ``{{host}}`` to build URLs (for example: ``https://{{host}}/v3/dids``). Enter only the hostname (for example, ``api.didww.com``) without ``https://`` or ``/v3``.

.. figure:: https://doc.didww.com/_images/fig4.png
   :alt: Production environment configured with host and apiKey.
   :figclass: align-center
   :width: 100%

   **Fig. 5.** Example Production Environment.

Select the Environment
^^^^^^^^^^^^^^^^^^^^^^

Click the :octicon:`check-circle` button to set the correct environment active before sending API requests.

.. figure:: https://doc.didww.com/_images/fig6.png
   :alt: Selecting environment in Postman.
   :figclass: align-center
   :width: 100%

   **Fig. 7.** Switching between Production and Sandbox.

.. raw:: html

   <br>

Step 3: Configure Required Headers and Authentication
--------------------------------------------------------

The DIDWW API follows the `JSON:API specification <https://jsonapi.org/format/#content-negotiation>`_.
All requests must include the correct JSON:API headers and your API key.

.. note::
   For more detailed hostnames and authentication rules, see the :doc:`Getting Started with the DIDWW API <configuration>` and :doc:`Specification headers <specification/headers>` sections.

.. raw:: html

   <br>

Open a Sample Request
^^^^^^^^^^^^^^^^^^^^^

You can use any request in the collection for this step. For example:

1. In your forked DIDWW API collection, expand the **Inventory Resources** folder.
2. Click **DID** to open the DID resource group.
3. Select the **Get DIDs** request.

.. figure:: https://doc.didww.com/_images/fig7.png
   :alt: Example request opened in Postman with headers visible.
   :figclass: align-center
   :width: 100%

   **Fig. 8.** Sample DIDWW API request opened in Postman.

.. raw:: html

   <br>

Verify the Required Headers
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The official DIDWW Postman collection already includes the required headers.
Verify that they are present, enabled, and correctly configured.

1. With the **Get DIDs** request open, go to the **Headers** tab.
2. Ensure that the following headers exist and are enabled:

   .. list-table::
      :header-rows: 1
      :widths: 5 7 20

      * - **Header**
        - **Example Value**
        - **Description**
      * - ``Accept``
        - ``application/vnd.api+json``
        - Required for all API responses.
      * - ``Content-Type``
        - ``application/vnd.api+json``
        - Required for all JSON request bodies.
      * - ``Api-Key``
        - ``{{apiKey}}``
        - Authentication header using the ``apiKey`` variable from the selected environment.

.. warning::
   Never share your API key in screenshots, code samples, or public repositories.
   If it becomes exposed, rotate it immediately in the DIDWW User Panel.

.. figure:: https://doc.didww.com/_images/fig7.5.png
   :alt: Example request opened in Postman with headers visible.
   :figclass: align-center
   :width: 100%

   **Fig. 9.** Sample DIDWW API request opened in Postman.

----

.. raw:: html

   <br>

.. _api_using_postman_first_request:

Step 4: Send Your First Request
-------------------------------

When the environment and headers are configured, you can send any request from the collection.

1. Open a request of your choice (for example, **Get DIDs**).
2. Make sure the correct environment is selected.
3. Click **Send**.

.. figure:: https://doc.didww.com/_images/fig8.png
   :alt: Sending a request using the configured environment.
   :figclass: align-center
   :width: 100%

   **Fig. 10.** Sending a test request in Postman.

----

.. raw:: html

   <br>

Step 5: Check the Response and Troubleshoot Errors
--------------------------------------------------

After you send a request, the response appears in the lower Postman panel. Here you can review the **status code** and the **JSON response body**.

Success Response
^^^^^^^^^^^^^^^^^

A valid, authenticated request returns a **200 OK** status and a JSON response.

.. figure:: https://doc.didww.com/_images/fig9.png
   :alt: Example JSON response from DIDWW API.
   :figclass: align-center
   :width: 100%

   **Fig. 11.** Successful API response.

Troubleshooting API Errors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

401 Unauthorized
    ``Api-Key`` is missing or invalid. Set the ``apiKey`` variable correctly in the active environment.

406 Not Acceptable
    The ``Accept`` header is incorrect. Set it to ``application/vnd.api+json``.

415 Unsupported Media Type
    The ``Content-Type`` header is missing or incorrect. Set it to ``application/vnd.api+json`` for any request with a JSON body.

404 Not Found
    The host, endpoint path, or resource ID is incorrect, or the API key does not match the selected host. Make sure ``{{host}}`` is exactly ``api.didww.com`` or ``sandbox-api.didww.com`` (without ``https://`` or ``/v3``) and verify the request URL.

422 Unprocessable Entity
    The request body is missing required fields or is not valid JSON:API. Ensure POST or PATCH requests follow the JSON:API document structure.
    See: `JSON API specification <https://jsonapi.org/format/#document-structure>`_

.. .. figure:: /img/postman/fig10.png
       :alt: Viewing status codes and error responses.
       :figclass: align-center
       :width: 100%

       **Fig. 12.** Viewing error responses in Postman.


==============
SDKs and Tools
==============

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
      :link: https://github.com/didww/didww-api-3-php-sdk
      :link-type: url
      :text-align: left

      Access the official PHP SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
      :link: https://github.com/didww/didww-api-3-java-sdk
      :link-type: url
      :text-align: left

      Access the official Java SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
      :link: https://github.com/didww/didww-api-3-python-sdk
      :link-type: url
      :text-align: left

      Access the official Python SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
      :link: https://github.com/didww/didww-api-3-typescript-sdk
      :link-type: url
      :text-align: left

      Access the official TypeScript SDK for integrating with the DIDWW API.

   .. grid-item-card:: :iconify:`material-icon-theme:go` **Go SDK**
      :link: https://github.com/didww/didww-api-3-go-sdk
      :link-type: url
      :text-align: left

      Access the official DIDWW API client SDK for the Go programming language.

   .. grid-item-card:: :iconify:`devicon:dot-net` **.NET SDK**
      :link: https://github.com/didww/didww-api-3-dotnet-sdk
      :link-type: url
      :text-align: left

      Access the official DIDWW API client SDK for the .NET platform.

   .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Client**
      :link: https://github.com/didww/didww-v3-ruby
      :link-type: url
      :text-align: left

      Use the official Ruby client for interacting with the DIDWW API.

   .. grid-item-card:: :iconify:`skill-icons:rails` **Ruby on Rails Sample App**
      :link: https://github.com/didww/didww-v3-rails-sample
      :link-type: url
      :text-align: left

      View a sample Rails app showing how to integrate with the DIDWW API.

   .. grid-item-card:: :iconify:`devicon:postman` **Postman Public Workspace**
      :link: https://www.postman.com/didww-api/workspace/didww-api3-documentation
      :link-type: url
      :text-align: left

      Explore DIDWW API endpoints in the Postman public workspace.

:orphan:

=================================
API Resources Summary v2022-05-10
=================================

.. note::

   You are viewing an older version of the API reference.

   For the latest version guidance, see the :doc:`latest API3 documentation <../2026-04-16/index>`.

.. raw:: html

    <div class="postman-run-button"
    data-postman-action="collection/fork"
    data-postman-var-1="23329000-7178161d-b951-44a7-a75f-9dcd15b970f5"
    data-postman-collection-url="entityId=23329000-7178161d-b951-44a7-a75f-9dcd15b970f5&entityType=collection&workspaceId=c7e9c67d-ac71-4c91-a5ef-b12f6619f415"
    data-postman-param="env%5BDIDWW%20Sandbox%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoieW91ckRpZHd3QXBpS2V5IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoieW91ckRpZHd3QXBpS2V5Iiwic2Vzc2lvbkluZGV4IjoxfV0=">
    </div>
    <p></p>
    <script type="text/javascript">
    (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
    (n = o.createElement("script")),
    (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
    }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
    </script>

The DIDWW API allows you to perform an extensive set of actions such as querying the DID coverage and inventory, ordering and configuring phone numbers and services, setting capacity and creating SIP trunks by using the following methods:

 * **GET** - Fetch data, where the data can be a collection or resources or an individual resource
 * **POST** - Create a new resource
 * **PATCH** - Update an existing resource
 * **DELETE** - Remove an existing resource

.. csv-table::
   :header: "API Call", "Method/s", "Details"

   ":ref:`balance <balance_v33>`","GET", "Returns the prepaid balance as well as the available credit on the account."
   ":ref:`cities <cities_v33>`", "GET", "Returns a list of cities included in the current DIDWW inventory, or returns the details of a specific city."
   ":ref:`countries <countries_v33>`","GET","Returns a list of countries included in the current DIDWW inventory, or return the details of a specific country."
   ":ref:`dids <dids_v33>`","GET, PATCH","Returns a list of all of the DIDs owned by an account or the details for a single DID, or modify the settings for a single DID owned by an account."
   ":ref:`did_groups <did_groups_v33>`","GET","Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code."
   ":ref:`did_group_types <did_group_types_v33>`", "GET","Returns a list of the various types of DIDs supported by DIDWW (for example, mobile, toll-free, SMS)."
   ":ref:`capacity_pools <capacity_pools_v33>`","GET, PATCH","Returns a list of the Capacity Pools which include information about channels quantity, supported Countries, Shared Capacity Groups."
   ":ref:`shared_capacity_groups <shared_capacity_groups_v33>`","GET, POST, PATCH, DELETE","Returns a list of the Capacity Groups assigned to Capacity Pool."
   ":ref:`export <export_v33>`","GET, POST","Returns a call detail records (CDRs) or create a CDR for export."
   ":ref:`orders <orders_v33>`","GET, POST, DELETE","Returns a list of the orders previously placed in this account, create a new order, or delete an order."
   ":ref:`regions <regions_v33>`","GET","Returns a list of regions (for example, states within the USA) included in the current DIDWW inventory."
   ":ref:`voice_in_trunks <voice_in_trunks_v33>`","GET, POST, PATCH, DELETE","Returns a list of all of the voice in trunks configured by this account, create a new trunk, modify the settings of an existing trunk, or delete a trunk."
   ":ref:`voice_out_trunks <voice_out_trunks_v33>`","GET, POST, PATCH, DELETE","Returns a list of all voice out trunks configured by this account, create a new trunk, modify the existing trunk, or delete a trunk."
   ":ref:`voice_in_trunk_groups <voice_in_trunk_groups_v33>`","GET, POST, PATCH, DELETE","Returns the details of a voice in trunk group, create a new trunk group, modify trunk group settings, or delete a trunk group."
   ":ref:`available_dids <available_dids_v33>`","GET","Returns a list of available DID numbers in the current DIDWW coverage."
   ":ref:`did_reservation <did_reservation_v33>`","GET, POST, DELETE","Returns a list or a single DID reservations for the account."
   ":ref:`address_verifications <address_verifications_v33>`","GET, POST","Returns a list or a single address verifications for the account."
   ":ref:`addresses <addresses_v33>`","GET, POST, PATCH, DELETE","Returns the details of a address, create a new address, modify address settings, or delete an address."
   ":ref:`encrypted_files <encrypted_files_v33>`","GET, POST, DELETE","Returns the details of a encrypted file, create a new encrypted file, or delete an encrypted file."
   ":ref:`identities <identities_v33>`","GET, POST, PATCH, DELETE","Returns the details of a identity, create a new identity, modify identity settings, or delete an identity."
   ":ref:`permanent_supporting_documents <permanent_documents_v33>`","POST, DELETE","Create a new permanent supporting document, or delete a permanent supporting document."
   ":ref:`proof_types <proof_types_v33>`","GET","Returns a list or a single proof_types for the account."
   ":ref:`proofs <proofs_v33>`","POST, DELETE","Create a new proof, or delete a proof."
   ":ref:`requirements <requirements_v33>`","GET","Returns a list or a single requirements for the account."
   ":ref:`supporting_document_templates <supporting_document_template_v33>`","GET","Returns a list or a single supporting document templates for the account."
   ":ref:`areas <areas_v33>`","GET","Returns a list or a single regulatory area."
   ":ref:`nanpa_prefixes <nanpa_prefixes_v33>`","GET","Returns a list NANPA prefixes or a single NANPA prefix."


.. |br| raw:: html

    </br>

.. _callbacks_details_v33:

=================
Callbacks Details
=================

Callbacks allow you to receive events related to your :ref:`Orders <orders_v33>`, :ref:`Exports <export_v33>`,
:ref:`Address Verifications <address_verifications_v33>`, and :ref:`Voice Out Trunks <voice_out_trunks_v33>` via HTTP request.

Order Callback Request Parameters
=================================

Configure a **callback_url** and **callback_method** attributes for single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either **GET** or **POST**.

With **GET** request you will receive payload as query parameters.
**POST** request will set the "Content-Type" header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of order status change DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "ID of an order"
   "``type``", "``orders``"
   "``status``", "``completed`` or ``canceled``"

Export Callback Request Parameters
==================================

Configure a **callback_url** and **callback_method** attributes for single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either **GET** or **POST**.

With **GET** request you will receive payload as query parameters.
**POST** request will set the "Content-Type" header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of export complete DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "ID of an export"
   "``type``", "``exports``"
   "``status``", "``completed``"

Address Verification Callback Request Parameters
================================================

Configure a **callback_url** and **callback_method** attributes for a single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either **GET** or **POST**.

    - With a **GET** request, you will receive the payload as query parameters.
    - With a **POST** request, DIDWW sets the "Content-Type" header to ``application/x-www-form-urlencoded`` and sends the payload in the request body.

In case of address verification status change DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "Unique ID of the address verification"
   "``type``", "Resource type, always ``address_verifications``"
   "``status``", "Verification status: ``approved`` or ``rejected``."
   "``reject_reason``", "Reason for rejection, provided if the status is ``rejected``.

   .. important:: The ``reject_reason`` field is always included, but it only contains a value when the status is ``rejected``. |br| For all other statuses, this field will be empty."

Voice OUT Trunk Callback Request Parameters
===========================================

Configure a **callback_url** attribute for single resource via the REST API,
and DIDWW will make an HTTP POST request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL.

In case of Voice OUT Trunk being blocked due to set 24 hour limit value being reached or trunk being unblocked
DIDWW makes an HTTP POST request to the **callback_url** with "Content-Type" header set to “application/json”
and body as JSON array with one or more JSON objects.

Each JSON object will have following parameters:

.. csv-table::
   :header: "Parameter", "Type", "Description"

   "``id``", "``string``", "ID of a Voice OUT Trunk"
   "``type``", "``string``", "``voice_out_trunks``"
   "``status``", "``string``", "``active`` or ``blocked``"
   "``threshold_reached``", "``boolean``", "``false`` or ``true``"
   "``created_at``", "``string``", "Date and Time of event creation"

Example
=======

.. code-block:: json

    [
        {
            "id": "f36d1d17-bd16-42b9-af42-0cfe166bf3ec",
            "type": "voice_out_trunks",
            "status": "blocked",
            "threshold_reached": true,
            "created_at": "2017-06-25T08:21:41.795Z"
        }
    ]

HTTP Request Validation
=======================

If your application exposes sensitive data or is possibly mutative to your data,
then you may want to be sure that the HTTP requests to your web application are indeed coming from DIDWW,
and not a malicious third party.
To allow you this level of security, DIDWW cryptographically signs its requests. Here's how it works:

#. Turn on TLS on your server and configure your DIDWW account to use HTTPS URLs in **callback_url**.
#. DIDWW assembles and normalizes the payload.
    * If your request is a POST, DIDWW takes all the POST fields, sorts them alphabetically by their name, and concatenates the parameters name and value (with no delimiters).
    * If your request is a GET, DIDWW takes all the GET query fields (except the query added to the URL itself), sorts them alphabetically by their name, and concatenates the parameters name and value (with no delimiters).
#. DIDWW normalizes the URL (the full URL with a scheme, port, query string, and fragments), concatenates with normalized payload and sign it using HMAC-SHA1 and your **API key** as the key.
#. DIDWW sends this signature in an HTTP header called **X-DIDWW-Signature**.

.. note::

 Only an **API key** with the **enable_callbacks** option enabled will be used.
 If there is no **API key** with this option enabled, then no callback will be performed.
 Therefore, it's crucial to make sure that the correct **API key** is being used to generate the **X-DIDWW-Signature**
 for the validation process to function properly.
 Callbacks can be enabled only for a single **API key**.

Then, on your end, if you want to verify the authenticity of the request,
you can leverage the built-in request validation method provided by all of our SDKs:

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Gem**
      :link: https://github.com/didww/didww-v3-ruby/blob/master/lib/didww/callback/request_validator.rb
      :link-type: url

      Use the APIv3 Ruby gem to validate callback requests and verify their authenticity.

   .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
      :link: https://github.com/didww/didww-api-3-php-sdk/blob/master/src/Callback/RequestValidator.php
      :link-type: url

      Use the official PHP SDK to validate incoming callback requests from DIDWW.

   .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
      :link: https://github.com/didww/didww-api-3-java-sdk/blob/main/src/main/java/com/didww/sdk/callback/RequestValidator.java
      :link-type: url

      Use the official Java SDK to verify the integrity and origin of callback requests.

   .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
      :link: https://github.com/didww/didww-api-3-python-sdk/blob/main/src/didww/callback/request_validator.py
      :link-type: url

      Use the official Python SDK to validate DIDWW callback request signatures.

   .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
      :link: https://github.com/didww/didww-api-3-typescript-sdk/blob/main/src/callback/request-validator.ts
      :link-type: url

      Use the official TypeScript SDK to verify callback request signatures.

   .. grid-item-card:: :iconify:`logos:go` **Go Sample**
      :link: https://github.com/didww/didww-api-3-go-sdk/blob/main/callback.go
      :link-type: url

      Use the Go sample to implement callback request validation compatible with DIDWW API v3.

Algorithm implementation details
================================

Steps to perform validation manually:

#. Take the full URL of the request URL you specify in the **callback_url** attribute, from the protocol (https...) through the end of the query string (everything after the ?).
#. If the request is a POST, sort all of the POST parameters alphabetically (using Unix-style case-sensitive sorting order).
#. If the request is a GET, sort all of the query parameters alphabetically (except that are specifically set in **callback_url**, using Unix-style case-sensitive sorting order).
#. For POST requests iterate through the sorted list of POST parameters, and append the variable name and value (with no delimiters) to the end of the URL string.
#. For GET requests iterate through the sorted list of GET parameters (except that are specifically set in **callback_url**) and append the variable name and value (with no delimiters) to the end of the URL string.
#. Sign the resulting string with HMAC-SHA1 using your **API key** as the key (remember, your API key's case matters!).
#. Encode the resulting hash as a hex-encoded string (each byte of result data transformed into hex from 00 to ff, most encryption libraries have a function that returns hex digest on the previous step).
#. Compare your hash to ours, submitted in the **X-DIDWW-Signature** header. If they match, then you're good to go.

Here's an example. DIDWW made a POST to your application as part of an order callback:

..  code-block::

    https://mycompany.com/didww_callbacks?opaque=123

And DIDWW posted the following POST fields:

 * type: :code:`orders`
 * status: :code:`completed`
 * id: :code:`bf2cee72-6caa-4ae2-917e-bea01945691e`

Create a string that is your URL with the full query string and explicitly set the port:

..  code-block::

    https://mycompany.com:443/didww_callbacks?opaque=123

Then, sort the list of POST variables by the parameter name (using Unix-style case-sensitive sorting order):

 * id: :code:`bf2cee72-6caa-4ae2-917e-bea01945691e`
 * status: :code:`completed`
 * type: :code:`orders`

Next, append each POST variable, name and value, to the string with no delimiters:

..  code-block::

    https://mycompany.com:443/didww_callbacks?opaque=123idbf2cee72-6caa-4ae2-917e-bea01945691estatuscompletedtypeorders

Hash the resulting string using HMAC-SHA1, using following test API key :code:`szrdgh6547umt7tht7xbqhj6g9gdbyp7`
and encode as a hex-encoded string

The resulting signature should be :code:`30f66e9d72eb5e193051fd02952f70d8e934b4ff`

.. note::

 Concerned about SHA1 security issues? DIDWW does not use SHA-1 alone.
 In short, the critical component of HMAC-SHA1 that distinguishes it from SHA-1 alone is the use of your **DIDWW API key** as a complex secret key.
 While there are possible collision-based attacks on SHA-1, HMACs are not affected by those same attacks -
 it's the combination of the underlying hashing algorithm (SHA-1) and the strength of the secret key (API key) that protects you in this case.

IP addresses
============
Requests are being sent from IPv4 network 46.19.208.0/21 and IPv6 network 2a01:ad00::/32

HTTP Response Error Handling
============================

When DIDWW receives **non 2XX** response status code from an HTTP request to the **callback_url** it will re-attempt to send it again up to 9 times.

After 10 attempt DIDWW will stop sending callback event.

HTTP request timeout more than 60 seconds will consider as failed response.

.. csv-table::
   :header: "Callback attempt ", "Wait interval"

   "2", "1 minute "
   "3", "10 minutes "
   "4", "30 minutes"
   "5", "1 hour"
   "6", "3 hours"
   "7", "6 hours "
   "8", "12 hours "
   "9", "1 day "
   "10", "2 days "

Testing Callbacks on local machine behind NAT
=============================================

In order to test Callbacks feature on local servers behind NAT, tools such as `ngrok <https://ngrok.com/docs/start>`_ or `localtunnel <https://theboroer.github.io/localtunnel-www/>`_ could be used.
These tools allows you to expose a web server running on your local machine to the internet.


.. _changelog_2022_05_10:

=========
Changelog
=========

Breaking Changes
================

* The ``local_prefix`` attribute has been removed from the ``/v3/did_groups`` response.
* The ``filter[local_prefix]`` parameter has been removed from the ``/v3/did_groups`` endpoint.
* The ``phone_number`` attribute in ``/v3/identities`` now accepts only numeric (digit-only) values.

Enhancements
============

* Added support for filtering in ``/v3/did_groups`` using the following parameters:

  * ``filter[nanpa_prefix.id]``
  * ``filter[nanpa_prefix.npanxx]``
* Added ``filter[nanpa_prefix.id]`` support to the ``/v3/available_dids`` endpoint.
* In ``/v3/orders``, the ``items`` attribute for DID Order Item Attributes now supports the ``nanpa_prefix_id`` field.
* Filtering by name is now case-insensitive for the following endpoints:

  * ``/v3/cities``
  * ``/v3/countries``
  * ``/v3/did_groups`` (by ``area_name``)
  * ``/v3/regions``
  * ``/v3/areas``

New Endpoints
=============

.. list-table::
   :header-rows: 1
   :widths: 40 30

   * - Endpoint
     - Access Level
   * - ``/v3/nanpa_prefixes``
     - Read

.. _quantity_based_price_object_v33:

===================================
Channel Quantity Based Price Object
===================================

Quantity based pricing lets you automatically apply different discount prices to channels in Capacity pool that depend on the quantity.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "setup_price", "``string``", "Price for Order creation per channel."
   "monthly_price", "``string``", "Monthly price for Order renew based on Capacity pool billing cycle date (renew_date)."
   "qty", "``integer``", "Quantity on channels from which price per channel will be with discount."



===========
Definitions
===========

.. toctree::

  stock-keeping-unit-object.rst
  channel-quantity-based-price-object.rst


.. _stock_keeping_unit_object_v33:

=========================
Stock Keeping Unit Object
=========================

Unique identification ID of inventory unit.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "setup_price", "``string``", "Price for Order creation."
   "monthly_price", "``string``", "Monthly price for order renew."
   "channels_included_count", "``integer``", "Included channels capacity for each DID."

.. _available_did_object_v33:

====================
Available DID Object
====================

Available DID Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "number","``string``","DID Number"




=================
Get Available DID
=================

Returns a single Available DID from DIDWW inventory.

.. note::

 Available DID request is not enabled by default. To enable this feature, please contact our Customer Service or Sales Departments. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/available_dids/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number of the Available DID."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "did_group", ":ref:`DID Group Object <did_group_object_v33>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v33>`"
   "nanpa_prefix", ":ref:`Nanpa Prefix Object <nanpa_prefix_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple request
   
        .. http:example:: curl
        
           GET /v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144 HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API token]
           
           
           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json
           
            {
                "data": {
                    "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                    "type": "available_dids",
                    "attributes": {
                        "number": "12124727604"
                    },
                    "relationships": {
                        "did_group": {
                            "links": {
                                "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                                "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                            }
                        },
                        "nanpa_prefix": {
                            "links": {
                                "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                                "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Include did_group
   
      .. http:example:: curl
      
        GET /v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144?include=did_group HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json        

        {
            "data": {
                "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                "type": "available_dids",
                "attributes": {
                    "number": "12124727604"
                },
                "relationships": {
                    "did_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                        },
                        "data": {
                            "type": "did_groups",
                            "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c"
                        }
                    },
                    "nanpa_prefix": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                        }
                    }
                }
            },
            "included": [
                {
                    "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "212",
                        "features": [
                            "voice_in",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "New York",
                        "allow_additional_channels": true
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/stock_keeping_units"
                            }
                        },
                        "requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/requirement",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 8
                    }
                }
            ],
            "meta": {
                "api_version": "2022-05-10"
            }
        }

   .. tab:: Include did_group.stock_keeping_units
   
      .. http:example:: curl
      
        GET /v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144?include=did_group.stock_keeping_units HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
            "data": {
                "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                "type": "available_dids",
                "attributes": {
                    "number": "12124727604"
                },
                "relationships": {
                    "did_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                        },
                        "data": {
                            "type": "did_groups",
                            "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c"
                        }
                    },
                    "nanpa_prefix": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                        }
                    }
                }
            },
            "included": [
                {
                    "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "212",
                        "features": [
                            "voice_in",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "New York",
                        "allow_additional_channels": true
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/stock_keeping_units"
                            },
                            "data": [
                                {
                                    "type": "stock_keeping_units",
                                    "id": "af589936-3e8d-498c-b127-8054ef026dfa"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "5dec9d3e-f25a-4ac3-a9b0-efcdd9ec744b"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "e48e981f-ab6d-48a6-aaf6-e75539fc1011"
                                }
                            ]
                        },
                        "requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/requirement",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 8
                    }
                },
                {
                    "id": "af589936-3e8d-498c-b127-8054ef026dfa",
                    "type": "stock_keeping_units",
                    "attributes": {
                        "setup_price": "0.0",
                        "monthly_price": "0.09",
                        "channels_included_count": 0
                    }
                },
                {
                    "id": "5dec9d3e-f25a-4ac3-a9b0-efcdd9ec744b",
                    "type": "stock_keeping_units",
                    "attributes": {
                        "setup_price": "0.0",
                        "monthly_price": "0.19",
                        "channels_included_count": 2
                    }
                },
                {
                    "id": "e48e981f-ab6d-48a6-aaf6-e75539fc1011",
                    "type": "stock_keeping_units",
                    "attributes": {
                        "setup_price": "4.42",
                        "monthly_price": "4.42",
                        "channels_included_count": 5
                    }
                }
            ],
            "meta": {
                "api_version": "2022-05-10"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 

.. _available_dids_v33_get_available_dids:

==================
Get Available DIDs
==================

Returns a list of Available DIDs. :ref:`Pagination <api_pagination>` and :ref:`Sorting <api_sorting>` are disabled.

.. warning::

   Do not use the number selection tool to populate another database with available numbers, as DID inventory changes frequently.

.. note::

   - The ``/v3/available_dids`` endpoint is disabled by default. Contact **Customer Service** or **Sales** to enable it.
   - Results are returned in random order.
   - Requests are not cached. A new request may return the same results as a previous one, depending on the filters applied.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/available_dids``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "did_group", ":ref:`DID Group Object <did_group_object_v33>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v33>`"
   "nanpa_prefix", ":ref:`Nanpa Prefix Object <nanpa_prefix_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Available DID ``id`` field."
   "number_contains", "``string``", "No", "No", "The ``number`` field."
   "did_group.id", "``string``", "No", "Yes", "DID Group ``id`` field."
   "did_group_type.id", "``string``", "No", "Yes", "DID Group ``type id`` field."
   "country.id", "``string``", "No", "Yes", "DID Group ``country id`` field."
   "region.id", "``string``", "No", "Yes", "DID Group ``region id`` field."
   "city.id", "``string``", "No", "Yes", "DID Group ``city id`` field."
   "did_group.needs_registration", "``boolean``", "No", "No", "DID Group ``needs_registration`` field."
   "did_group.features", "``string``", "No", "Yes", "DID Group ``features`` field."
   "nanpa_prefix.id", "``string``", "No", "No", "Nanpa prefix ``id`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "number", "The ``number`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/available_dids HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": [
                    {
                        "id": "55ac507c-6248-412a-abbb-a02bbe7034e6",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727600"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "54563944-801d-40ba-add1-b9e48b669493",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14803023230"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "126607e3-1ff7-4399-89cf-aea426c47134",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858120"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "90113411-3037-4f25-a33b-7898b601f271",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858091"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "a017bb1a-b4b1-48cb-9331-31bf6394f191",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858035"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "7f396769-5203-470c-9595-b158c6bba7c8",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727603"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "065fda4b-1730-4e20-81d0-96f7335347ea",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727606"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "5dead00e-6751-411a-929b-a25e5bace5b0",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858086"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727604"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_count": 361188,
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Include did_group and did_group.stock_keeping_units
      
   
      .. http:example:: curl
         
            GET /v3/available_dids?include=did_group&include=did_group.stock_keeping_units HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": [
                    {
                        "id": "1f5c3a09-03ea-4adb-98ac-37075753ecfd",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907306"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "93796469-642e-49d9-945d-473904c10591",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316908161"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "fe44fba4-a5c9-4e01-a5c3-1e9075e91638",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907298"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "2b86c154-1576-416e-a6c9-d6a1f1479cea",
                        "type": "available_dids",
                        "attributes": {
                            "number": "17634977780"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "07ff1c6f-23cb-4938-a5cb-abb751e67c46"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "6d391601-51cd-4e22-ae1d-f58153b5bd2a",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907218"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "4449880c-d11a-431c-ae94-32bf61f43655",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316908157"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "3f186a11-c01e-41be-ad0a-8d1611078e74",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907182"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "57180089-2d22-4508-b2b4-0f6a69730dd2",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907303"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "033d2f74-ef23-4779-95ed-3c0e3bbe2363",
                        "type": "available_dids",
                        "attributes": {
                            "number": "18197718303"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "b77cfb79-be19-44d7-a2e6-39c28253df73"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "630ec71a-f86b-4543-bd72-4799144fe5d7",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316908151"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "80672e46-0ca9-4d45-8709-a537a526d7cc",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "631",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Nogales",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/stock_keeping_units"
                                },
                                "data": [
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "11005837-36ac-49a0-91b7-97a0f35829b1"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "697ce6ad-73f3-458d-8bd3-dd1f33718c2a"
                                    }
                                ]
                            },
                            "requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/requirement",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 231
                        }
                    },
                    {
                        "id": "07ff1c6f-23cb-4938-a5cb-abb751e67c46",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "763",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Osseo",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/stock_keeping_units"
                                },
                                "data": [
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "aef9387a-6b7e-489c-9927-818e27a20b57"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "2418d053-f6ed-44a4-8414-926ba7193e53"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "ad642989-191f-4df6-80e3-176942ef5643"
                                    }
                                ]
                            },
                            "requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/requirement",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 1
                        }
                    },
                    {
                        "id": "b77cfb79-be19-44d7-a2e6-39c28253df73",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "819",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Ottawa-Hull",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/stock_keeping_units"
                                },
                                "data": [
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "09c1ebf4-f52c-413b-92bc-960d089f4fc8"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "a0b4086c-7734-4d41-962a-6f9b9593ad6d"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "dc8b2df7-23b6-4723-b918-84efb987eae5"
                                    }
                                ]
                            },
                            "requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/requirement",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 2
                        }
                    },
                    {
                        "id": "11005837-36ac-49a0-91b7-97a0f35829b1",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "3.82",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "697ce6ad-73f3-458d-8bd3-dd1f33718c2a",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "6.99",
                            "channels_included_count": 2
                        }
                    },
                    {
                        "id": "aef9387a-6b7e-489c-9927-818e27a20b57",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.09",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "2418d053-f6ed-44a4-8414-926ba7193e53",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.19",
                            "channels_included_count": 2
                        }
                    },
                    {
                        "id": "ad642989-191f-4df6-80e3-176942ef5643",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "4.42",
                            "monthly_price": "4.42",
                            "channels_included_count": 5
                        }
                    },
                    {
                        "id": "09c1ebf4-f52c-413b-92bc-960d089f4fc8",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.18",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "a0b4086c-7734-4d41-962a-6f9b9593ad6d",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.28",
                            "channels_included_count": 2
                        }
                    },
                    {
                        "id": "dc8b2df7-23b6-4723-b918-84efb987eae5",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "4.42",
                            "monthly_price": "4.42",
                            "channels_included_count": 5
                        }
                    }
                ],
                "meta": {
                    "total_count": 361188,
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Include nanpa_prefix

      .. http:example:: curl

            GET /v3/available_dids?include=nanpa_prefix HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "c6ff0b43-aed2-4697-b2d5-6ec8ca36a415",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14805539893"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9"
                                }
                            }
                        }
                    },
                    {
                        "id": "b721db67-a85b-4e76-9df0-5e2977f99655",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14802405726"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "34bed380-d056-4d2f-909b-4463f1935ec6"
                                }
                            }
                        }
                    },
                    {
                        "id": "c99679cf-7f5d-45de-b86f-1e7606e603fc",
                        "type": "available_dids",
                        "attributes": {
                            "number": "19164148368"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "11049f22-ac70-4a1f-8ef3-e95f86f19aae"
                                }
                            }
                        }
                    },
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e"
                                }
                            }
                        }
                    },
                    {
                        "id": "f0bd90e3-ce64-4b4e-935b-afe75f600e8f",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858027"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "41686b02-738b-4fa0-bb0e-cf20c5761c5e"
                                }
                            }
                        }
                    },
                    {
                        "id": "065fda4b-1730-4e20-81d0-96f7335347ea",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727606"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e"
                                }
                            }
                        }
                    },
                    {
                        "id": "cbaf7322-c045-45f1-9b2a-6a3ce59ad27a",
                        "type": "available_dids",
                        "attributes": {
                            "number": "17328579010"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "209e3b8a-c72e-46c3-a7ff-5de4975d93cc"
                                }
                            }
                        }
                    },
                    {
                        "id": "f54296e7-fcfd-4693-ae11-b8700c41cc72",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858151"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "41686b02-738b-4fa0-bb0e-cf20c5761c5e"
                                }
                            }
                        }
                    },
                    {
                        "id": "05ca4efd-f73f-4cc9-a0db-8c2248291f4a",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14807174998"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "249a5255-31e1-4501-afee-80e4d7d1b06b"
                                }
                            }
                        }
                    },
                    {
                        "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727604"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "553"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "34bed380-d056-4d2f-909b-4463f1935ec6",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "240"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "11049f22-ac70-4a1f-8ef3-e95f86f19aae",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "916",
                            "nxx": "414"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "212",
                            "nxx": "472"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "41686b02-738b-4fa0-bb0e-cf20c5761c5e",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "685"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "209e3b8a-c72e-46c3-a7ff-5de4975d93cc",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "732",
                            "nxx": "857"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "249a5255-31e1-4501-afee-80e4d7d1b06b",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "717"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/region"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_count": 361188,
                    "api_version": "2022-05-10"
                }
            }
             
Response
========

Top Level Meta Attributes
-------------------------

.. csv-table::
   :header: "Name", "Type", "Description"
   :widths: 4, 3, 10
   
   "total_count","``integer``","Total count of available DIDs that match the query."
   "available_count","``integer``","Count of available DIDs for reservation." 

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"



.. _available_dids_v33:
 
=============
Available DID
=============
 
Returns a single or a list of available DID numbers included in DIDWW inventory. 

.. note::

 Available DIDs request is not enabled by default. To enable this feature, please contact our Customer Service or Sales Departments.

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-available-did.rst
  get-available-dids.rst
  available-did-object.rst



.. _city_object_v33:

===========
City Object
===========

City Object definition.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","City name"

.. _cities_v33_get_cities:

==========
Get Cities
==========

Returns a list of cities. Maximum :ref:`page size <api_pagination>` is 1000. Default page size is 1000.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/cities``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "filter[<filter_name>]","``string``, ``boolean``","No",":ref:`Filtering <api_filters>`"
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value","Description"
   
   "country",":ref:`Country Object <country_object_v33>`"
   "region",":ref:`Region Object <region_object_v33>`"
   "area",":ref:`Area Object <area_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank","Allow Array","Filters by:"
   
   "id","``string``","No","Yes","City ``id`` field."
   "name","``string``","Yes","Yes","City ``name`` field. Case insensitive."
   "country.id","``string``","Yes","Yes","A ``country.id`` field."
   "region.id","``string``","Yes","Yes","A ``region.id`` field."
   "is_available","``boolean``","No","No","Indicates if DID numbers in the specified city are currently available for purchase"
   "area.id","``string``","Yes","Yes","A ``area.id`` field."

Sorting
-------

.. csv-table::
   :header: "Value","Sort by"
   
   "name","City ``name`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value","Returns"
   
   "name","City ``name`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple request
   
        .. http:example:: curl 
        
           GET /v3/cities HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]
           
           
           HTTP/2 200 OK
           Content-Type: application/vnd.api+json
           
           {
             "data": [
               {
                 "id": "dccb89ba-f777-4128-b99b-b25e19ccf4ea",
                 "type": "cities",
                 "attributes": {
                   "name": "Aachen"
                 },
                 "relationships": {
                   "country": {
                     "links": {
                       "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/country",
                       "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/country"
                     }
                   },
                   "region": {
                     "links": {
                       "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/region",
                       "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/region"
                     }
                   },
                   "area": {
                     "links": {
                       "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/area",
                       "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/area"
                     }
                   }
                 }
               }
             ]
           }

   .. tab:: Filter by name or country.id
   
      .. http:example:: curl
         
            GET /v3/cities?filter[name]=Springfield&filter[country.id]=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
                  "type": "cities",
                  "attributes": {
                    "name": "Springfield"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
                      }
                    },
                    "region": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
                      }
                    },
                    "area": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
                      }
                    }
                  }
                }
              ]
            }
            

   .. tab:: Include Country Resource
      
   
      .. http:example:: curl
         
            GET /v3/cities?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
                  "type": "cities",
                  "attributes": {
                    "name": "Springfield"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
                      }
                    },
                    "region": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
                      }
                    },
                    "area": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
                      }
                    }
                  }
                }
              ],
              "included": [
                {
                  "id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
                  "type": "countries",
                  "attributes": {
                    "name": "United States",
                    "prefix": "1",
                    "iso": "US"
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"

========
Get City
========

Returns a city for a given city ID number. Note that a unique identification number is allocated to each city included in the DIDWW coverage.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/cities/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the City."
   "include","``string``","No",":ref:`Inclusion <api_includes>`"   

Includes
--------

.. csv-table::
   :header: "Value","Description"
   
   "country",":ref:`Country Object <country_object_v33>`"
   "region",":ref:`Region Object <region_object_v33>`"
   "area",":ref:`Area Object <area_object_v33>`"
   
Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "cdf449bc-e3fb-42cc-bf31-b88f91e40de4",
                "type": "cities",
                "attributes": {
                  "name": "London"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/relationships/country",
                      "related": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/country"
                    }
                  },
                  "region": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/relationships/region",
                      "related": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/country"
                    }
                  },
                  "area": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/relationships/area",
                      "related": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/area"
                    }
                  }
                }
              }
            }
            

   .. tab:: Include Country 
      
   
      .. http:example:: curl
         
            GET /v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "498f2880-591f-436d-aacd-46ad3a7d8be8",
                "type": "cities",
                "attributes": {
                  "name": "London"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/relationships/country",
                      "related": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "2e89d524-55b6-4b6c-a0af-3c1ed0f407f9"
                    }
                  },
                  "region": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/relationships/region",
                      "related": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/region"
                    }
                  },
                  "area": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/relationships/area",
                      "related": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/area"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "2e89d524-55b6-4b6c-a0af-3c1ed0f407f9",
                  "type": "countries",
                  "attributes": {
                    "name": "United Kingdom",
                    "prefix": "44",
                    "iso": "GB"
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"

.. _cities_v33:

 
======
Cities
======
 
Returns a single or a list of cities included in DIDWW inventory. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-city.rst
  get-cities.rst
  city-object.rst



.. _country_object_v33:

==============
Country Object
==============

Country Object attributes

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","Country name (for example United Kingdom)."
   "prefix","``string``","Country prefix (country calling code, for example 44)."
   "iso","``iso``","Country ISO code (for example GB)."

   
   
   
   
   

   



.. _countries_v33_get_countries:

=============
Get Countries
=============

Returns a list of countries. :doc:`../../../specification/pagination` is disabled.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/countries``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "filter[<filter_name>]","``string``, ``boolean``","No",":ref:`Filtering <api_filters>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank","Allow Array","Filters by:"
   
   "id","``string``","No","Yes","Country ``id`` field."
   "name","``string``","Yes","Yes","Country ``name`` field."
   "prefix","``string``","Yes","Yes","Country ``prefix`` field."
   "iso","``string``","Yes","Yes","Country ``iso`` field."
   "is_available","``boolean``","No","No","Indicates if DID numbers in the specified country are currently available for purchase."
   
Sorting
-------

.. csv-table::
   :header: "Value","Sorts by"
   
   "name","Country ``name`` field"
   "prefix","Country ``prefix`` field"
   "iso","Country ``iso`` field"

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value","Returns"
   
   "name","Country ``name`` attribute."
   "prefix","Country ``prefix`` attribute."
   "iso","Country ``iso`` attribute."

Example
=======

.. http:example:: curl

   GET /v3/countries HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
   
   
   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json
   
   {
       "data": [
       {
           "id": "9c56fe0f-eff0-4742-85f6-24868959344a",
           "type": "countries",
           "attributes": {
               "name": "United Kingdom",
               "prefix": "44",
               "iso": "GB"
              }
        },
        {
            "id": "5d3d7640-16d2-4dc0-9aca-408789fbefc6",
            "type": "countries",
            "attributes": {
                "name": "United States",
                "prefix": "1",
                "iso": "US"
            }
        }
        ]
   }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"



===========
Get Country
===========

Returns a country for a given country ID number. Note that a unique identification number is allocated to each country included in the DIDWW coverage.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/countries/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number for the country"

Example
=======

.. http:example:: curl 

   GET /v3/countries/e352699c-3764-415b-8946-dd470c1e0ed7 HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API Token]
   
   
   HTTP/2 200 OK
   Content-Type: application/vnd.api+json
   
   {
   	"data":{
   		"id": "e352699c-3764-415b-8946-dd470c1e0ed7",
   		"type": "countries",
   		"attributes": {
   			"name": "United Kingdom",
   			"prefix": "44",
   			"iso": "GB"
   		}
   	}
   }
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"
   




.. _countries_v33:
 
=========
Countries
=========
 
Returns a list of countries included in the current DIDWW inventory, or return the details of a specific country. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-country.rst
  get-countries.rst
  country-object.rst



.. _did_group_type_object_v33:

=====================
DID Group Type Object
=====================

DID Group Type Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","DID Group Type name, such as **Local**, **Mobile** or **Toll-free**."

   

   





==================
Get DID Group Type
==================

Returns a single DID Group Type. A DID Group Type defines a broad category of DID services supported by DIDWW (for example, mobile, local and toll-free).

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_group_types/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number of a DID Group Type."

Example
=======

.. http:example:: curl 

   GET /v3/did_group_types/4e057223-2a0a-4707-8b35-4e6ef96c9dd9 HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API Token]
   
   
   HTTP/2 200 OK
   Content-Type: application/vnd.api+json
   
   {
       "data": {
           "id": "4e057223-2a0a-4707-8b35-4e6ef96c9dd9",
           "type": "did_group_types",
           "attributes": {
               "name": "Local"
              }
        }
   }
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"

   
   
   
   

   



.. _did_group_types_v33_get_did_group_types:

===================
Get DID Group Types
===================

Returns a list of DID Group Types. A DID Group Type defines a broad category of DID services supported by DIDWW (for example, mobile, local and toll-free).

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_group_types``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Group Type ``id`` field."
   "name", "``string``", "Yes", "Yes", "Group Type ``name`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "DID Group Type ``name`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "name", "DID Group Type ``name`` attribute."

Example
=======

.. http:example:: curl

   GET /v3/did_group_types HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
   
   
   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json
   
   {
       "data": [
       {
           "id": "5827aaef-b3e7-4282-ab9f-e9c17a3e9b93",
           "type": "did_group_types",
           "attributes": {
               "name": "Local"
              }
        },
        {
            "id": "842b298a-9243-4989-a455-4bceac0c7e0e",
            "type": "did_group_types",
            "attributes": {
                "name": "National"
            }
        },
        {
            "id": "96462614-64cf-4898-a434-4e03f8d7f6ab",
            "type": "did_group_types",
            "attributes": {
                "name": "Toll-free"
            }
        },
        {
            "id": "bf31407e-d583-4a1b-b8ee-a5f0d77d865a",
            "type": "did_group_types",
            "attributes": {
                "name": "Mobile"
            }
        },
        {
            "id": "5ad07e30-11f3-4ff9-ba87-fd06575c8f06",
            "type": "did_group_types",
            "attributes": {
                "name": "Shared Cost"
            }
        },
        {
            "id": "e961316f-7f16-4d29-b619-2fd7c421c738",
            "type": "did_group_types",
            "attributes": {
                "name": "Global"
            }
        }
        ],
        "meta": {
            "total_records": 6
            },
            "links": {
                "first": "https://api.didww.comv3/did_group_types?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/did_group_types?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
   }
            

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _did_group_types_v33:
 
==============
DID Group Type
==============
 
Returns a single or a list of the various types of DIDs that are supported in DIDWW inventory. For example: mobile, toll-free, local. Features that are supported: SMS IN, SMS OUT, Voice IN, Voice OUT. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-did-group-type.rst
  get-did-group-types.rst
  did-group-type-object.rst



.. _did_group_object_v33:

================
DID Group Object
================

DID Group Object attributes and meta attributes.

Meta attributes are not available through :ref:`includes <api_includes>`.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "area_name ","``string``","DID Group area name. This will be the name of the city, or a designation applicable to the area code such as **National**."
   "prefix ","``string``","DID Group prefix (city or area calling code)."
   "features","Array of ``strings``","Features available for the DID Group, including voice, sms and t38. A DID Group may have multiple features."
   "is_metered ","``boolean``","Defines if the DID Group supports metered services (per-minute billing)."
   "allow_additional_channels ","``boolean``","Defines if channel capacity may be added to this DID Group."

Meta Attributes
===============

.. csv-table::
   :header: "Name","Type","Description"
   
   "needs_registration ","``boolean``","Defines if end-user registration is required for this DID Group."
   "is_available ","``boolean``","Defines if numbers in this DID Group are currently in stock. "
   "available_dids_enabled","``boolean``","Defines if the DID Group supports numbers selection feature. "
   "total_count","``integer``","Defines current stock available."




=============
Get DID Group
=============

Returns a single DID Group. DID Groups are phone numbers that share a common city or area code.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   :widths: 6, 5, 5, 10

   "id", "``string``", "Yes", "Unique ID number of a DID Group."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"
   :widths: 5, 10

   "country", ":ref:`Country Object <country_object_v33>`"
   "region", ":ref:`Region Object <region_object_v33>`"
   "city", ":ref:`City Object <city_object_v33>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "stock_keeping_units", "A list of :ref:`Stock Keeping Unit Objects <stock_keeping_unit_object_v33>`"
   "requirement", ":ref:`Requirements Object <requirements_object_v33>`"

Example
=======

.. http:example:: curl

    GET /v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API Token]

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "2187c36d-28fb-436f-8861-5a0f5b5a3ee1",
            "type": "did_groups",
            "attributes": {
                "prefix": "241",
                "features": [
                    "voice_in"
                ],
                "is_metered": false,
                "area_name": "Aachen",
                "allow_additional_channels": true
            },
            "relationships": {
                "country": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/country",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/country"
                    }
                },
                "city": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/city",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/city"
                    }
                },
                "did_group_type": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/did_group_type",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/did_group_type"
                    }
                },
                "region": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/region",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/region"
                    }
                },
                "stock_keeping_units": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/stock_keeping_units",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/stock_keeping_units"
                    }
                },
                "requirement": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/requirement",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/requirement"
                    }
                }
            },
            "meta": {
                "available_dids_enabled": false,
                "needs_registration": true,
                "is_available": true,
                "total_count": 7
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   :widths: 5, 5, 10
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



.. _did_groups_v33_get_did_groups:

==============
Get DID Groups
==============

Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``, ``boolean``, ``Integer``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"
   "region", ":ref:`Region Object <region_object_v33>`"
   "city", ":ref:`City Object <city_object_v33>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "stock_keeping_units", "A list of :ref:`Stock Keeping Unit Objects <stock_keeping_unit_object_v33>`"
   "requirement", ":ref:`Requirements Object <requirements_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Group ``id`` field."
   "prefix", "``string``", "Yes", "Yes", "The group ``prefix`` field."
   "nanpa_prefix.id", "``string``", "Yes", "Yes", "The nanpa prefix ``id`` field."
   "nanpa_prefix.npanxx", "``string``", "Yes", "Yes", "The nanpa prefix ``npa`` / ``nxx`` fields."
   "area_name", "``string``", "Yes", "Yes", "The ``area_name`` field (for example London). Case insensitive."
   "is_metered", "``boolean``", "No", "No", "The ``is_metered`` field."
   "allow_additional_channels", "``boolean``", "No", "No", "The ``allow_additional_channels`` field."
   "available_dids_enabled", "``boolean``", "No", "No", "The ``available_dids_enabled`` field."
   "features", "``string``", "No", "Yes", "The ``features`` field. Can be one/several/all of 'voice_in', 'voice_out', 't38', 'sms_in', 'sms_out'. example: 'voice_in,sms_in'"
   "needs_registration", "``boolean``", "No", "No", "The ``needs_registration`` field."
   "is_available", "``boolean``", "No", "No", "The ``is_available`` field."
   "country.id", "``string``", "Yes", "Yes", "The ``country.id`` field."
   "region.id", "``string``", "Yes", "Yes", "The ``region.id`` field."
   "city.id", "``string``", "Yes", "Yes", "The ``city.id`` field."
   "did_group_type.id", "``string``", "Yes", "Yes", "The ``did_group_type.id`` field."
   "meta.total_count_gteq", "``Integer``", "Yes", "No", "A filter on the list based on the ``meta.total_count_gteq`` field, where ``gteq`` stands for greater-equal."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "country.name", "The ``country.name`` field."
   "did_group_type.name", "The ``did_group_type.name`` field."
   "prefix", "City ``prefix`` field."
   "is_metered", "The ``is_metered`` field."
   "area_name", "The ``area_name`` field."
   "allow_additional_channels", "The ``allow_additional_channels`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "prefix", "City ``prefix`` attribute."
   "is_metered", "The ``is_metered`` attribute."
   "area_name", "The ``area_name`` attribute."
   "allow_additional_channels", "The ``allow_additional_channels`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple request

        .. http:example:: curl

            GET /v3/did_groups HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [{
                    "id": "ac160b14-e670-490f-b158-d3ba552c623f",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "241",
                        "local_prefix": "",
                        "features": [
                            "voice",
                            "voice_out",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "Aachen",
                        "allow_additional_channels": true
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/stock_keeping_units"
                            }
                        },
                        "requirement": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/requirement",
                                "related": "https://sandbox-api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": false,
                        "needs_registration": true,
                        "is_available": true,
                        "total_count": 21
                    }

                }],
                "meta": {
                    "total_records": 1,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?page%5Bnumber%5D=32&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by country.id, did_group_type.id - Include sku_id

      .. http:example:: curl

            GET /v3/did_groups?filter[country.id]=c8647639-fc9c-47b2-acec-7c9e14465c25&filter[did_group_type.id]=0d51924c-e863-44ff-be59-10547c138955&include=stock_keeping_units HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [{
                    "id": "1d5aad75-b853-4125-9a1a-da3fedfc5674",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "7",
                        "local_prefix": "",
                        "features": [
                            "voice",
                            "voice_out",
                            "sms",
                            "sms_out"
                        ],
                        "is_metered": false,
                        "area_name": "Mobile",
                        "allow_additional_channels": true
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/stock_keeping_units"
                            },
                            "data": [{
                                    "type": "stock_keeping_units",
                                    "id": "cb17c069-098e-4be1-a7eb-eb4529e8c5f5"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "e194165e-eda7-4718-9bbe-c5c583bd189a"
                                }
                            ]
                        },
                        "requirement": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/requirement",
                                "related": "https://sandbox-api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 99
                    }
                }],
                "included": [{
                        "id": "cb17c069-098e-4be1-a7eb-eb4529e8c5f5",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.3",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "e194165e-eda7-4718-9bbe-c5c583bd189a",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.8",
                            "channels_included_count": 2
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bdid_group_type.id%5D=0d51924c-e863-44ff-be59-10547c138955&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bdid_group_type.id%5D=0d51924c-e863-44ff-be59-10547c138955&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by city.id, prefix - Include sku_id

      .. http:example:: curl

            GET /v3/did_groups?filter[city.id]=e696dec7-9c65-4e99-aab7-55a1f98154f0&include=stock_keeping_units&filter[prefix]=20 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [{
                    "id": "fc271bcc-1f9c-4c19-8174-28b7c55a208a",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "20",
                        "local_prefix": "",
                        "features": [
                            "voice",
                            "voice_out",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "London",
                        "allow_additional_channels": true
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/stock_keeping_units"
                            },
                            "data": [{
                                    "type": "stock_keeping_units",
                                    "id": "0ba87a94-7143-48cb-a0f6-d50a6a0c8cfa"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "1a86de53-3131-491f-9e4b-3392da45d441"
                                }
                            ]
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 932
                    }
                }],
                "included": [{
                        "id": "0ba87a94-7143-48cb-a0f6-d50a6a0c8cfa",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.3",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "1a86de53-3131-491f-9e4b-3392da45d441",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.8",
                            "channels_included_count": 2
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2021-12-15"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0&filter%5Bprefix%5D=20&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0&filter%5Bprefix%5D=20&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by nanpa_prefix.id

      .. http:example:: curl

            GET /v3/did_groups?filter[nanpa_prefix.id]=1d968dcf-8ee7-40fa-8073-cdbc027bc3b3 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "b59a0277-9d74-4417-b477-192794496928",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "201",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Hackensack",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/stock_keeping_units"
                                }
                            },
                            "requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/requirement",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 3
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.id%5D=1d968dcf-8ee7-40fa-8073-cdbc027bc3b3&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.id%5D=1d968dcf-8ee7-40fa-8073-cdbc027bc3b3&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by nanpa_prefix.npanxx

      .. http:example:: curl

            GET /v3/did_groups?filter[nanpa_prefix.npanxx]=201221 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "b59a0277-9d74-4417-b477-192794496928",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "201",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Hackensack",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/stock_keeping_units"
                                }
                            },
                            "requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/requirement",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 3
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.npanxx%5D=201221&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.npanxx%5D=201221&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"

.. _did_groups_v33:
 
=========
DID Group
=========
 
Returns a single or a list of DID Groups which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code.

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-did-group.rst
  get-did-groups.rst
  did-group-object.rst



.. _create_did_reservation_v33:

======================
Create DID Reservation
======================

Creates a DID Reservation.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/did_reservations``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Nullable", "Description"

   "include", "``string``", "Optional", "True", ":ref:`Inclusion <api_includes>`"

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "available_dids", ":ref:`to-one <api_relationships>`", "Linkage for included available DIDs."

Example
=======

.. http:example:: curl

   POST /v3/did_reservations HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
      
    {
      "data": {
        "type": "did_reservations",
        "attributes": {
          "description": "DIDWW"
        },
        "relationships": {
          "available_did": {
            "data": {
              "type": "available_dids",
              "id": "8bc37f63-acd7-4e43-a760-1a1caa6e4683"
            }
          }
        }
      }
    }
        
        
   HTTP/1.1 201 Created
   Content-Type: application/vnd.api+json
	
	{
	  "data": {
	    "id": "80167e78-62a1-4720-bf00-229fa7e1935d",
	    "type": "did_reservations",
	    "links": {
	      "self": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d"
	    },
	    "attributes": {
	      "expire_at": "2018-03-15 12:34:56",
	      "created_at": "2018-03-15 12:14:56",
	      "description": "DIDWW"
	    },
	    "relationships": {
	      "available_did": {
	        "links": {
	          "self": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d/relationships/available_did",
	          "related": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d/available_did"
	        }
	      }
	    }
	  }
	}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "201","Yes","Created DID Reservation with not reserved Available DID.Returns :ref:`DID Reservation Object <did_reservation_object_v33>`"
   "202","Yes","Updated DID Reservation with already reserved Available DID. Request updates current reservation if exists. Returns :ref:`DID Reservation Object <did_reservation_object_v33>`" 
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>` " 
   "401","No",":ref:`Unauthorized <api_key>`" 




======================
Delete DID Reservation
======================

Deletes a DID Reservation.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/did_reservations/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the DID Reservation."

Example
=======

.. http:example:: curl

   DELETE /v3/did_reservations/1156df17-bcea-4c9a-9c1d-29320e288c03 HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
   
   
   HTTP/1.1 204 No Content
   Content-Type: application/vnd.api+json
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "204","Yes","DID Reservation deleted.   "
   "401","No",":ref:`Unauthorized <api_key>`" 
  


.. _did_reservation_object_v33:

======================
DID Reservation Object
======================

DID Reservation Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "expire_at","``DateTime``","Expiration date and time."
   "created_at","``DateTime``","Creation date and time."
   "description","``string``","Description"



===================
Get DID Reservation
===================

Returns a single DID Reservation.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_reservations/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number of the DID Reservation."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "available_did", ":ref:`Available DID Object <available_did_object_v33>`"
   "available_did.did_group", ":ref:`DID Group Object <did_group_object_v33>`"
   "available_did.did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                    "type": "did_reservations",
                    "attributes": {
                        "expire_at": "2022-06-27T10:52:16.564Z",
                        "created_at": "2022-06-27T10:42:16.577Z",
                        "description": "DIDWW"
                    },
                    "relationships": {
                        "available_did": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                            }
                        }
                    }
                },
                "meta": {
                    "available_count": 9,
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Request with available_did include
   
      .. http:example:: curl
      
            GET /v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d?include=available_did HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]      

   
           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                    "type": "did_reservations",
                    "attributes": {
                        "expire_at": "2022-06-27T10:52:16.564Z",
                        "created_at": "2022-06-27T10:42:16.577Z",
                        "description": "DIDWW"
                    },
                    "relationships": {
                        "available_did": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                            },
                            "data": {
                                "type": "available_dids",
                                "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573"
                            }
                        }
                    }
                },
                "included": [
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "available_count": 9,
                    "api_version": "2022-05-10"
                }
            }
   
   
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




====================
Get DID Reservations
====================

Returns a list of DID Reservations.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_reservations``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "available_did", ":ref:`Available DID Object <available_did_object_v33>`"
   "available_did.did_group", ":ref:`DID Group Object <did_group_object_v33>`"
   "available_did.did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "DID Reservation ``id`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "expire_at", "The ``expire_at`` attribute."
   "created_at", "The ``created_at`` attribute."
   "description", "The ``description`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/did_reservations HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                        "type": "did_reservations",
                        "attributes": {
                            "expire_at": "2022-06-27T10:52:16.564Z",
                            "created_at": "2022-06-27T10:42:16.577Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                                }
                            }
                        }
                    },
                    {
                        "id": "e85a5b1f-850d-498f-8418-ec74cccc9e9a",
                        "type": "did_reservations",
                        "attributes": {
                            "expire_at": "2022-06-27T10:59:58.131Z",
                            "created_at": "2022-06-27T10:49:58.151Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/available_did"
                                }
                            }
                        }
                    },
                    {
                        "id": "4789767d-d59a-485b-9adb-da14b4859f51",
                        "type": "did_reservations",
                        "attributes": {
                            "expire_at": "2022-06-27T11:00:03.332Z",
                            "created_at": "2022-06-27T10:50:03.344Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/available_did"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 3,
                    "available_count": 7,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_reservations?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_reservations?page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Request with available_did include
   
      .. http:example:: curl
      
            GET /v3/did_reservations?include=available_did HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]      

   
           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                        "type": "did_reservations",
                        "attributes": {
                            "expire_at": "2022-06-27T10:52:16.564Z",
                            "created_at": "2022-06-27T10:42:16.577Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                                },
                                "data": {
                                    "type": "available_dids",
                                    "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573"
                                }
                            }
                        }
                    },
                    {
                        "id": "e85a5b1f-850d-498f-8418-ec74cccc9e9a",
                        "type": "did_reservations",
                        "attributes": {
                            "expire_at": "2022-06-27T10:59:58.131Z",
                            "created_at": "2022-06-27T10:49:58.151Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/available_did"
                                },
                                "data": {
                                    "type": "available_dids",
                                    "id": "8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f"
                                }
                            }
                        }
                    },
                    {
                        "id": "4789767d-d59a-485b-9adb-da14b4859f51",
                        "type": "did_reservations",
                        "attributes": {
                            "expire_at": "2022-06-27T11:00:03.332Z",
                            "created_at": "2022-06-27T10:50:03.344Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/available_did"
                                },
                                "data": {
                                    "type": "available_dids",
                                    "id": "7f396769-5203-470c-9595-b158c6bba7c8"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907325"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "7f396769-5203-470c-9595-b158c6bba7c8",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727603"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 3,
                    "available_count": 7,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_reservations?include=available_did&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_reservations?include=available_did&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"



.. _did_reservation_v33:
 
===============
DID Reservation
===============
 
Returns a single or a list of DID reservations for the account. Allows to create or cancel a DID reservation. DID Reservation default values: 10 DID Numbers, 10 Minutes. 

Supported methods: ``GET``, ``POST``, ``DELETE``.
 
.. toctree:: 
  :titlesonly:
  	
  get-did-reservation.rst
  get-did-reservations.rst
  create-did-reservation.rst
  delete-did-reservation.rst
  did-reservation-object.rst





==================
Coverage Resources
==================
 
The following requests allows you to retrieve the contents of DIDWW inventory.
 
.. toctree:: 
  :titlesonly:
  	
  countries/index
  regions/index
  city/index
  nanpa/index
  did-group-type/index
  did-group/index
  available-did/index
  did-reservation/index

.. _regions_v33:
 
=======
Regions
=======
 
Returns a single or a list of regions included in DIDWW inventory. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-region.rst
  get-regions.rst
  region-object.rst



==========
Get Region
==========

Returns a single Region.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/regions/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier for the Region"
   "include","``string``","No",":ref:`Inclusion <api_includes>` "   		            
   
Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "8ce33ee2-73da-4baa-85a0-cd607d0e9733",
                    "type": "regions",
                    "attributes": {
                        "name": "Alberta",
                        "iso": "CA-AB"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/relationships/country",
                                "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
                            }
                        }
                    }
                }
            }
            

   .. tab:: Include Country
      
   
      .. http:example:: curl
         
            GET /v3/regions/e2f3f115-11f1-43cf-8279-08b29d94403d?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "8ce33ee2-73da-4baa-85a0-cd607d0e9733",
                    "type": "regions",
                    "attributes": {
                        "name": "Alberta",
                        "iso": "CA-AB"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/relationships/country",
                                "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
                            }
                        }
                    }
                },
                "included": [
                {
                    "id": "fa914558-9c64-4e01-967b-3302bd65a97b",
                    "type": "countries",
                    "attributes": {
                        "name": "Canada",
                        "prefix": "1",
                        "iso": "CA"
                    }
                }
                ]
            }
            
            
    

   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"

.. _regions_v33_get_regions:

===========
Get Regions
===========

Returns a collection of Regions. :ref:`Pagination <api_pagination>` is disabled.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/regions``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "filter[<filter_name>]","``string``","No",":ref:`Filtering <api_filters>`"
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value","Description"
   
   "country",":ref:`Country Object <country_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank","Allow Array","Filters by:"
   
   "id","``string``","No","Yes","Region ``id`` field."
   "name","``string``","Yes","Yes","Region ``name`` field. Case insensitive."
   "country.id","``string``","Yes","Yes","A ``country.id`` field."
   "iso","``string``","No","Yes","Region ``iso`` field."

Sorting
-------

.. csv-table::
   :header: "Value","Sort by"
   
   "name","Region ``name`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value","Return"
   
   "name","Region ``name`` attribute."

Examples
========

.. tabs::

   .. tab:: Filter by country.id

        .. http:example:: curl 
        
           GET /v3/regions HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]
           
           
           HTTP/2 200 OK
           Content-Type: application/vnd.api+json
           
           {
           	"data":{

           		"id": "e2f3f115-11f1-43cf-8279-08b29d94403d",
           		"type": "regions",
           		"attributes": {
           			"name": "Alberta",
                    "iso": "CA-AB"
           		},
           		"relationships": {
           		    "country": {
           		        "links": {
           		            "self": "https://api.didww.com/v3/regions/e2f3f115-11f1-43cf-8279-08b29d94403d/relationships/country",
           		            "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
           		           }
           		         }
           		      }
           		   }
           		}

   .. tab:: Filter by country.id
   
        .. http:example:: curl
         
            GET /v3/regions?filter[country.id]=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&sort=-name HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "525dab52-0f4b-43cb-b1f6-83ee97a0b5ff",
                    "type": "regions",
                    "attributes": {
                        "name": "Wyoming",
                        "iso": "US-WY"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/525dab52-0f4b-43cb-b1f6-83ee97a0b5ff/relationships/country",
                                "related": "https://api.didww.com/v3/regions/525dab52-0f4b-43cb-b1f6-83ee97a0b5ff/country"
                            }
                        }
                    }
                }
            }
            

   .. tab:: Include Country Resource
      
   
        .. http:example:: curl
         
            GET /v3/regions?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "8ce33ee2-73da-4baa-85a0-cd607d0e9733",
                    "type": "regions",
                    "attributes": {
                        "name": "Alberta",
                        "iso": "CA-AB"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/relationships/country",
                                "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
                            }
                        }
                    }
                },
                "included": [
                {
                    "id": "fa914558-9c64-4e01-967b-3302bd65a97b",
                    "type": "countries",
                    "attributes": {
                        "name": "Canada",
                        "prefix": "1",
                        "iso": "CA"
                    }
                }
                ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"

.. _region_object_v33:

==============
Regions Object
==============

Region Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","Region name (for example Quebec)."
   "iso","``iso``","ISO3166-2 code for `USA <https://www.iso.org/obp/ui/#iso:code:3166:US>`_, `Canada <https://www.iso.org/obp/ui/#iso:code:3166:CA>`_, and `United Kingdom <https://www.iso.org/obp/ui/#iso:code:3166:GB>`_, ``null`` for other countries"

   

   



.. _nanpa_prefixes_v33:

============
NANPA Prefix
============

Returns a single or a list of NANPA Prefix included in DIDWW inventory.

.. note::
    NANPA Prefixes are available only for all countries with country code +1. 

Supported methods: ``GET``

.. toctree::
  :titlesonly:

  get-nanpa-prefix.rst
  get-nanpa-prefixes.rst
  nanpa-prefixes-object.rst

================
Get NANPA Prefix
================

Returns information about single NANPA prefix.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/nanpa_prefixes/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the NANPA Prefix."
   "include","``string``","No",":ref:`Inclusion <api_includes>` "  

Examples
========

.. tabs::

   .. tab:: GET NANPA Prefix

      .. http:example:: curl

            GET /v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                    "type": "nanpa_prefixes",
                    "attributes": {
                        "npa": "201",
                        "nxx": "221"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2022-05-10"
                }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"

.. _nanpa_v33_get_nanpa:

==================
Get NANPA Prefixes
==================

Returns a collection of NANPA Prefixes.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/nanpa_prefixes``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"
   "region", ":ref:`Region Object <region_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "NANPA Prefixes ``id`` field."
   "npa", "``string``", "Yes", "Yes", "NANPA Prefixes ``npa`` field."
   "nxx", "``string``", "Yes", "Yes", "NANPA Prefixes ``nxx`` field."
   "npanxx", "``string``", "No", "No", "NANPA Prefixes ``npa`` / ``nxx`` fields."
   "country.id", "``string``", "Yes", "Yes", "A ``country.id`` field."
   "region.id", "``string``", "Yes", "Yes", "A ``region.id`` field."
   "did_group.is_available", "``boolean``", "No", "No", "Availability of DIDs in stock for prefix."
   "did_group.features", "``string``", "No", "Yes", "Availability of DIDs in stock with features for prefix. Can be one/several/all of 'voice_in', 'voice_out', 't38', 'sms_in', 'sms_out'."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "npa", "NANPA Prefixes ``npa`` field."
   "nxx", "NANPA Prefixes ``nxx`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "id", "The ``id`` field."
   "npa", "The ``npa`` field."
   "nxx", "The ``nxx`` field."
   "country", "The ``country`` field."
   "region", "The ``region`` field."

Examples
========

.. tabs::

   .. tab:: GET NANPA Prefixes

        .. http:example:: curl

           GET /v3/nanpa_prefixes HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]

           HTTP/2 200 OK
           Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "221"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "c8770990-8a6f-4e11-8b88-420cc9375931",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "234"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "a5958064-96d7-4594-b9bc-a5b9c3bba01f",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "275"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "fcd178f8-3085-42c2-9831-7ca30fc01789",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "301"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "1ff532b2-fec0-4f13-b661-d688ac29dfb0",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "345"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/region"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 4330,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/nanpa_prefixes?page%5Bnumber%5D=1&page%5Bsize%5D=5",
                    "next": "https://api.didww.com/v3/nanpa_prefixes?page%5Bnumber%5D=2&page%5Bsize%5D=5",
                    "last": "https://api.didww.com/v3/nanpa_prefixes?page%5Bnumber%5D=866&page%5Bsize%5D=5"
                }
            }

   .. tab:: Filter by US country.id

        .. http:example:: curl

            GET /v3/nanpa_prefixes?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "221"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "c8770990-8a6f-4e11-8b88-420cc9375931",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "234"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "a5958064-96d7-4594-b9bc-a5b9c3bba01f",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "275"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "fcd178f8-3085-42c2-9831-7ca30fc01789",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "301"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "1ff532b2-fec0-4f13-b661-d688ac29dfb0",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "345"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/region"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 1609,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&page%5Bnumber%5D=1&page%5Bsize%5D=5",
                    "next": "https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&page%5Bnumber%5D=2&page%5Bsize%5D=5",
                    "last": "https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&page%5Bnumber%5D=322&page%5Bsize%5D=5"
                }
            }

   .. tab:: Include Country Resource

        .. http:example:: curl

            GET /v3/nanpa_prefixes?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "221"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "c8770990-8a6f-4e11-8b88-420cc9375931",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "234"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "a5958064-96d7-4594-b9bc-a5b9c3bba01f",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "275"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "fcd178f8-3085-42c2-9831-7ca30fc01789",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "301"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "1ff532b2-fec0-4f13-b661-d688ac29dfb0",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "345"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/region"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                        "type": "countries",
                        "attributes": {
                            "name": "United States",
                            "prefix": "1",
                            "iso": "US"
                        },
                        "relationships": {
                            "regions": {
                                "links": {
                                    "self": "https://api.didww.com/v3/countries/1f6fc2bd-f081-4202-9b1a-d9cb88d942b9/relationships/regions",
                                    "related": "https://api.didww.com/v3/countries/1f6fc2bd-f081-4202-9b1a-d9cb88d942b9/regions"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 4330,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://api.didww.com/v3/nanpa_prefixes?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=5",
                    "next": "https://api.didww.com/v3/nanpa_prefixes?include=country&page%5Bnumber%5D=2&page%5Bsize%5D=5",
                    "last": "https://api.didww.com/v3/nanpa_prefixes?include=country&page%5Bnumber%5D=866&page%5Bsize%5D=5"
                }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"



.. _nanpa_prefix_object_v33:

===================
NANPA Prefix Object
===================

NANPA Prefix Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "npa","``string``","Numbering plan area code"
   "nxx","``string``","Central office code "

.. |br| raw:: html

   <br />

.. _user-panel-api-examples-v33-random-dids-v33:
.. _user-panel-api-examples-v33-did-group-v33:
.. _api-examples-buy-available-dids-v33:

====================================
Buy Available DID Number(s)
====================================

This example shows the **end-to-end process for purchasing a DID number**
from DID inventory.

This flow allows the platform to assign an available DID number from the
inventory that matches the selected criteria.

To buy a DID number from DID inventory, follow these steps:

- :ref:`Step 1: Find the Country <user-panel-api-examples-v33-random-dids-v33_step1-v33>`
- :ref:`Step 2: Show Inventory Filters for the Selected Country <user-panel-api-examples-v33-random-dids-v33_step2-v33>`
- :ref:`Step 3: Retrieve DID Availability, Pricing, and Coverage <user-panel-api-examples-v33-random-dids-v33_step3-v33>`
- :ref:`Step 4: Create the Order <user-panel-api-examples-v33-random-dids-v33_step4-v33>`

.. note::

   The UUIDs shown in the examples below are for illustration purposes only.

   Always execute requests in your own environment and use the UUIDs returned in API responses.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-random-dids-v33_step1-v33:

Step 1: Find the Country ID
===========================

Retrieve the unique ID for the target country using the ``/countries`` endpoint.
From the response, save the ``country.id`` for use in later steps when
retrieving cities, regions, NANPA prefixes, and DID Groups.

For more information, see the :ref:`/v3/countries <countries_v33_get_countries>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Find a country by ISO code*

      Use this approach when your application already knows the target country
      (for example, from a stored customer selection or a predefined checkout flow).
      Filter by ISO code to retrieve the matching country and its ``country.id``.

      .. http:example:: curl

         GET /v3/countries?filter[iso]=US HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

      .. note::
         This example filters by country ISO code. Adjust filters as needed to match
         your use case.

   .. tab-item:: *List countries available for purchase*

      Use this approach when building a **country dropdown** for end users.
      This request returns countries that have DID Groups in coverage and DID numbers
      available for purchase. You can sort the results by name and use each item’s
      ``attributes.name`` for display and ``id`` as the selected ``country.id`` for
      later steps.

      ``filter[is_available]`` is a boolean filter:

      - When ``true``, returns countries with DID numbers available for purchase.
      - When ``false``, returns countries that exist in coverage but currently have no
        DID numbers available for purchase.

      .. http:example:: curl

         GET /v3/countries?filter[is_available]=true&sort=name HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                     "type": "countries",
                     "attributes": {
                         "name": "Canada",
                         "prefix": "1",
                         "iso": "CA"
                     }
                 },
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-random-dids-v33_step2-v33:

Step 2: Show Inventory Filters for the Selected Country
========================================================

After the user selects a country and your application saves the
``country.id``, the next step is to help the user narrow the available DID
inventory.

At this stage, your site should display the filters that are supported for the
selected country. The available filters depend on the numbering rules and
inventory structure for that country.

Available filtering options for this flow include:

- **DID Group Types** filters DID inventory by number category, such as Local, Mobile, National, or Toll-free.
- **Cities**  filters DID inventory by city within the selected country.
- **Regions** filters DID inventory by region within the **United States**, **Canada**, and the **United Kingdom**.
- **NANPA Prefixes (NPA/NXX)** filters **Local** DID inventory in the **United States** and **Canada** by area code and central office code.

.. note:: Use the filtering method that matches the selected country and your search experience.

Building the Filtering Experience Example
-----------------------------------------

Guide the user through the filtering flow:

1. The user selects a country from the country list.
2. Your application saves the selected ``country.id``.
3. Your site displays the inventory filters available for that country.
4. The user chooses a filter option and selects a value.
5. Your application saves the returned resource ID, such as ``city.id``, or ``nanpa_prefix.id``.
6. Use the saved ID in the next step to retrieve DID Inventory using ``GET /v3/did_groups``.

For example:

- If the user selects **United States** or **Canada**, your site can also
  allow the user to select a **region** and then choose **NPA/NXX** prefix.
- To display NPA/NXX options for the United States, the customer should first
  select a **state**. After that, your application can retrieve and display the
  list of available NANPA prefixes for that state.

.. note::

   Do not show all possible filters unconditionally. Instead, show or enable only the
   filters that are relevant to the selected country and to the search flow
   supported by your application.

Filtering Examples
------------------------------

.. tab-set::
   :class: my-tabs
   :sync-group: did-filter

   .. tab-item:: *Search by City*
      :sync: city

      Use this filter when your application allows the user to narrow DID availability by **city**.

      Before you can filter DID inventory by city in the next step, you must first retrieve the corresponding ``city.id`` using the ``/cities`` endpoint.

      To narrow the results, use the saved ``country.id`` together with the city name entered or selected by the user.

      For more information, see the :ref:`/v3/cities <cities_v33_get_cities>` endpoint documentation.

      .. http:example:: curl

         GET /v3/cities?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[name]=New%20York HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "368bf92f-c36e-473f-96fc-d53ed1b4028b",
                     "type": "cities",
                     "attributes": {
                         "name": "New York"
                     }
                 }
             ]
         }

   .. tab-item:: *Search by NANPA Prefix (NPA/NXX)*
      :sync: nanpa

      Use this filter when your application allows the user to narrow DID
      inventory by **NPA/NXX**.

      This filtering option is available only for **United States** and
      **Canada**, because these countries use the **North American Numbering
      Plan (NANP)**.

      Before you can filter DID inventory by NANPA prefix in the next step, you
      must first retrieve the corresponding ``nanpa_prefix.id``. To do this,
      first retrieve the selected **state** or **province** using the
      ``/regions`` endpoint, and save the returned ``region.id``.

      Then use the saved ``country.id`` together with ``region.id`` to retrieve
      available NANPA prefixes by using the ``/nanpa_prefixes`` endpoint.

      From the response, save the returned ``nanpa_prefix.id``. You will use this
      value in the next step to filter DID Groups by NANPA prefix.

      The flow is:

      1. Save the selected ``country.id``.
      2. Retrieve the selected state or province and save ``region.id``.
      3. Retrieve NANPA prefixes using ``country.id`` and ``region.id``.
      4. Save the selected ``nanpa_prefix.id`` for the next step.

      .. rubric:: 1. Retrieve the State or Province

      First, use the saved ``country.id`` to retrieve the state or province
      selected by the user.

      For more information, see the
      :ref:`/v3/regions <regions_v33_get_regions>` endpoint documentation.

      .. http:example:: curl

         GET /v3/regions?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[name]=New%20York HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "ab7e83bc-814b-4cfa-a14c-d2df3de2a545",
                     "type": "regions",
                     "attributes": {
                         "name": "New York",
                         "iso": "US-NY"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

      .. rubric:: 2. Retrieve NPA/NXX Values for the Selected Region

      Next, use the saved ``country.id`` and ``region.id`` to retrieve the
      available NANPA prefixes for that state or province.

      Your application can then display the returned ``npa`` and ``nxx``
      values in a dropdown or searchable list so the user can select the
      required code.

      Save the selected ``nanpa_prefix.id`` for use in the next step when
      retrieving DID Inventory using ``GET /did_groups``.

      For more information, see the
      :ref:`/v3/nanpa_prefixes <nanpa_v33_get_nanpa>` endpoint documentation.

      .. http:example:: curl

         GET /v3/nanpa_prefixes?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[region.id]=ab7e83bc-814b-4cfa-a14c-d2df3de2a545 HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "48b91ed5-13db-4920-a4cb-d0260d692053",
                     "type": "nanpa_prefixes",
                     "attributes": {
                         "npa": "212",
                         "nxx": "111"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-random-dids-v33_step3-v33:

Step 3: Retrieve DID Availability, Pricing, and Number Selection Availability
=============================================================================

Use the ``/did_groups`` endpoint to retrieve the DID number inventory groups
that match the selected inventory criteria.

This endpoint is the primary source for building DID number coverage and
availability in your application. It allows you to present users with:

- available DID number types, such as Local, Mobile, National, and Toll-free
- supported prefixes and geographic areas
- available features, such as voice and SMS
- pricing options and included channel configurations
- whether registration is required before activation

Include ``stock_keeping_units`` in the request to retrieve SKU pricing and
included channel configurations for each DID Group.

From the ``GET /did_groups`` response, save the ``stock_keeping_units.id``
that will be used to create the order in the next step.

For more information, see the :ref:`/v3/did_groups <did_groups_v33_get_did_groups>` endpoint documentation.

.. tab-set::
   :class: my-tabs
   :sync-group: did-filter

   .. tab-item:: *Filter by City*
      :sync: city

      Use this approach when the inventory was located using ``city.id`` in
      :ref:`Step 2 <user-panel-api-examples-v33-random-dids-v33_step2-v33>`.

      Then apply ``filter[city.id]`` to retrieve DID Groups available in the selected city.

      .. http:example:: curl

         GET /v3/did_groups?include=stock_keeping_units&filter[city.id]=368bf92f-c36e-473f-96fc-d53ed1b4028b HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9",
               "type": "did_groups",
               "attributes": {
                 "prefix": "212",
                 "features": [
                   "voice_in"
                 ],
                 "is_metered": false,
                 "area_name": "New York",
                 "allow_additional_channels": true,
                 "service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/country",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/country"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/city",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/did_group_type",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/did_group_type"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/region",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/stock_keeping_units",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/stock_keeping_units"
                   },
                   "data": [
                     {
                       "type": "stock_keeping_units",
                       "id": "a7ecfee0-693e-459c-8eff-244121847ac2"
                     },
                     {
                       "type": "stock_keeping_units",
                       "id": "e2406add-fd8a-475c-b959-81e9619d7a4b"
                     }
                   ]
                 },
                 "requirement": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/requirement",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": false,
                 "is_available": true,
                 "total_count": 620
               }
             }
           ],
           "included": [
             {
               "id": "a7ecfee0-693e-459c-8eff-244121847ac2",
               "type": "stock_keeping_units",
               "attributes": {
                 "setup_price": "4.0",
                 "monthly_price": "4.00",
                 "channels_included_count": 0
               }
             },
             {
               "id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
               "type": "stock_keeping_units",
               "attributes": {
                 "setup_price": "4.0",
                 "monthly_price": "4.0",
                 "channels_included_count": 2
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2022-05-10"
           },
           "links": {
             "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *Filter by NANPA Prefix*
      :sync: nanpa

      Use this approach when the inventory was located using
      ``nanpa_prefix.id`` in :ref:`Step 2 <user-panel-api-examples-v33-random-dids-v33_step2-v33>`.

      Then apply ``filter[nanpa_prefix.id]`` to retrieve DID Groups that match the selected NANPA prefix.

      .. http:example:: curl

         GET /v3/did_groups?include=stock_keeping_units&filter%5Bnanpa_prefix.id%5D=48b91ed5-13db-4920-a4cb-d0260d692053 HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9",
               "type": "did_groups",
               "attributes": {
                 "prefix": "212",
                 "features": [
                   "voice_in"
                 ],
                 "is_metered": false,
                 "area_name": "New York",
                 "allow_additional_channels": true,
                 "service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/country",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/country"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/city",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/did_group_type",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/did_group_type"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/region",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/stock_keeping_units",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/stock_keeping_units"
                   },
                   "data": [
                     {
                       "type": "stock_keeping_units",
                       "id": "a7ecfee0-693e-459c-8eff-244121847ac2"
                     },
                     {
                       "type": "stock_keeping_units",
                       "id": "e2406add-fd8a-475c-b959-81e9619d7a4b"
                     }
                   ]
                 },
                 "requirement": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/requirement",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": false,
                 "is_available": true,
                 "total_count": 620
               }
             }
           ],
           "included": [
             {
               "id": "a7ecfee0-693e-459c-8eff-244121847ac2",
               "type": "stock_keeping_units",
               "attributes": {
                 "setup_price": "4.0",
                 "monthly_price": "4.00",
                 "channels_included_count": 0
               }
             },
             {
               "id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
               "type": "stock_keeping_units",
               "attributes": {
                 "setup_price": "4.0",
                 "monthly_price": "4.0",
                 "channels_included_count": 2
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2022-05-10"
           },
           "links": {
             "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-random-dids-v33_step4-v33:

Step 4: Create the DID Order
============================

Create the order using the selected ``stock_keeping_units.id`` retrieved in the previous step.

This ensures the order is created for a **DID number** that matches the
selected inventory criteria from the previous steps.

For more information, see the :ref:`/v3/orders <orders_v33_create_order>` endpoint documentation.

.. note::

   - A positive prepaid balance is required to successfully create the order.
   - For simplicity, detailed item attributes are not included in this response example.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Buy Numbers from Inventory*

      In :ref:`Step 3 <user-panel-api-examples-v33-random-dids-v33_step3-v33>`, the inventory was identified using the selected ``sku.id``.

      Use the selected ``sku.id`` to create an order for an available DID number from the matching inventory.

      In this example, we purchase a number with 2 included channels.

      For more information, see the :ref:`/v3/orders <orders_v33_create_order>` endpoint documentation.

      .. http:example:: curl

         POST /v3/orders HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "orders",
             "attributes": {
               "allow_back_ordering": true,
               "items": [
                 {
                   "type": "did_order_items",
                   "attributes": {
                     "sku_id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
                     "qty": 1
                   }
                 }
               ]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
            "data": {
                "id": "eb23b1a4-f4fd-4960-9f46-750ec920cde8",
                "type": "orders",
                "attributes": {
                    "amount": "8.0",
                    "status": "Pending",
                    "created_at": "2026-03-18T11:41:20.443Z",
                    "description": "DID",
                    "reference": "RNQ-961086",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "4.0",
                                "mrc": "4.0",
                                "prorated_mrc": false,
                                "billed_from": null,
                                "billed_to": null,
                                "setup_price": "4.0",
                                "monthly_price": "4.0",
                                "did_group_id": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
         }

   .. tab-item:: *Buy Numbers with Selected NANPA Prefix*

      In :ref:`Step 3 <user-panel-api-examples-v33-random-dids-v33_step3-v33>`, the inventory
      was identified using the selected ``nanpa_prefix.id`` together with
      ``sku.id``.

      Use the selected ``nanpa_prefix.id`` together with ``sku.id`` to create an
      order for an available DID number that matches the selected NANPA prefix.

      In this example, we purchase a number with 2 included channels.

      For more information, see the :ref:`/v3/orders <orders_v33_create_order>`
      endpoint documentation.

      .. http:example:: curl

         POST /v3/orders HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "orders",
             "attributes": {
               "allow_back_ordering": false,
               "items": [
                 {
                   "type": "did_order_items",
                   "attributes": {
                     "nanpa_prefix_id": "48b91ed5-13db-4920-a4cb-d0260d692053",
                     "sku_id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
                     "qty": 1
                   }
                 }
               ]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
            "data": {
                "id": "372cc3c7-49a2-41ef-be64-85b7b297e4e3",
                "type": "orders",
                "attributes": {
                    "amount": "0.09",
                    "status": "Pending",
                    "created_at": "2026-03-18T12:06:49.115Z",
                    "description": "DID",
                    "reference": "PJB-535885",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "0.09",
                                "prorated_mrc": false,
                                "billed_from": null,
                                "billed_to": null,
                                "setup_price": "0.0",
                                "monthly_price": "0.09",
                                "did_group_id": "7f3a4f3f-8aba-4447-9cb5-66a4e8e4f6ff"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
         }


.. |br| raw:: html

   <br />

.. _user-panel-api-examples-v33-verification-v33:
.. _api-examples-buy-a-did-that-requires-verification-v33:

===========================================
Buy a DID Number That Requires Verification
===========================================

This example shows the **end-to-end process for purchasing a DID number**
that is subject to **regulatory verification requirements** and completing the
verification flow required to activate it.

Certain DID numbers require end-user registration based on country, number type,
or applicable regulatory rules. When registration applies, additional
information such as an identity, address, proofs, and supporting documents must
be collected, validated, and submitted before the DID can be activated.

The flow outlined below covers discovering available numbers and registration
requirements, collecting and validating end-user data, and initiating the
verification process needed for DID activation.

To purchase a DID and complete the required verification flow, follow these steps:

- :ref:`Step 1: Find the Country ID <user-panel-api-examples-v33-verification-v33-step1-v33>`
- :ref:`Step 2: Find the City ID <user-panel-api-examples-v33-verification-v33-step2-v33>`
- :ref:`Step 3: Retrieve DID Availability, Pricing, and Registration Requirements <user-panel-api-examples-v33-verification-v33-step3-v33>`
- :ref:`Step 4: Create the DID Order <user-panel-api-examples-v33-verification-v33-step4-v33>`
- :ref:`Step 5: Retrieve the DID ID Created by the DID Order <user-panel-api-examples-v33-verification-v33-step5-v33>`
- :ref:`Step 6: Retrieve and Review Registration Requirements <user-panel-api-examples-v33-verification-v33-step6-v33>`
- :ref:`Step 7: Create an Identity <user-panel-api-examples-v33-verification-v33-step7-v33>`
- :ref:`Step 8: Create an Address <user-panel-api-examples-v33-verification-v33-step8-v33>`
- :ref:`Step 9: Encrypt and Upload Documents <user-panel-api-examples-v33-verification-v33-step9-v33>`
- :ref:`Step 10: Create Identity and Address Proofs <user-panel-api-examples-v33-verification-v33-step1-v330-v33>`
- :ref:`Step 11: Create a Permanent Supporting Document (If Required) <user-panel-api-examples-v33-verification-v33-step1-v331-v33>`
- :ref:`Step 12: Validate Identity and Address Against Requirements <user-panel-api-examples-v33-verification-v33-step1-v332-v33>`
- :ref:`Step 13: Assign End-User Details and Start DID Verification <user-panel-api-examples-v33-verification-v33-step1-v333-v33>`

.. note::
   The UUIDs shown in the examples below are for illustration purposes only.

   Always execute requests in your own environment and use the actual UUIDs
   returned in API responses.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step1-v33:

Step 1: Find the Country ID
===========================

Retrieve the unique ID for the target country using the ``/countries`` endpoint.
From the response, save the ``country.id`` for use in later steps (for example,
when retrieving requirements or building address data).

For more information, see the :ref:`/v3/countries <countries_v33_get_countries>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Find a country by ISO code*

      Use this approach when your application already knows the target country
      (for example, from a stored customer selection or a predefined checkout flow).
      Filter by ISO code to retrieve the matching country and its ``country.id``.

      .. http:example:: curl

         GET /v3/countries?filter[iso]=DE HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7",
                     "type": "countries",
                     "attributes": {
                         "name": "Germany",
                         "prefix": "49",
                         "iso": "DE"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

      .. note::
         This example filters by country ISO code. Adjust filters as needed to match
         your use case.

   .. tab-item:: *List countries available for purchase*

      Use this approach when building a **country dropdown** for end users.
      This request returns countries that have DID Groups in coverage and DID numbers
      available for purchase. You can sort the results by name and use each item’s
      ``attributes.name`` for display and ``id`` as the selected ``country.id`` for
      later steps.

      ``filter[is_available]`` is a boolean filter:

      - When ``true``, returns countries with DID numbers available for purchase.
      - When ``false``, returns countries that exist in coverage but currently have no
        DID numbers available for purchase.

      .. http:example:: curl

         GET /v3/countries?filter[is_available]=true&sort=name HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "7549be3c-1077-433d-9a77-25416373660d",
                     "type": "countries",
                     "attributes": {
                         "name": "Sweden",
                         "prefix": "46",
                         "iso": "SE"
                     }
                 },
                 {
                     "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                     "type": "countries",
                     "attributes": {
                         "name": "Canada",
                         "prefix": "1",
                         "iso": "CA"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step2-v33:

Step 2: Find the City ID
========================

Depending on your application flow, selecting a city may be optional or required.
If your application allows users to narrow DID availability by **city** (for
example, when displaying a coverage list for local numbers), you should retrieve
and store the corresponding ``city.id``.

If your application does **not** differentiate availability by city (for example,
when listing all cities within a country or purchasing non–city-specific DIDs),
this step can be skipped.

Use the saved ``country.id`` to retrieve the city where the DID will be purchased.
From the response, save the ``city.id`` for use in later steps when retrieving
DID Groups or building address data.

For more information, see the :ref:`/v3/cities <cities_v33_get_cities>` endpoint documentation.

.. http:example:: curl

    GET /v3/cities?filter[country.id]=f711b8ee-7576-4d40-9dd4-f51a69cee8a7&filter[name]=Aachen HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "bc7df5b9-3852-401c-b21d-8c8871efd86f",
                "type": "cities",
                "attributes": {
                    "name": "Aachen"
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2022-05-10"
        }
    }

.. note::

   This example filters the response by a single city name. Adjust the request
   parameters as needed to match your use case.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-sku-and-requirements-v33:
.. _user-panel-api-examples-v33-verification-v33-step3-v33:

Step 3: Retrieve DID Availability, Pricing, and Registration Requirements
=========================================================================

This step uses the ``/did_groups`` endpoint, which is the **primary source for
building DID number coverage and availability** in your application.

It allows you to present end users with:

- available DID number types (Local, Mobile, National, Toll-free)
- supported prefixes and geographic areas
- available features (such as voice and SMS)
- pricing options and included channel options
- whether regulatory registration is required before activation

Include ``stock_keeping_units`` and ``requirement`` in the request to obtain
the following information:

- **Stock Keeping Units (SKU)** – Represents individual inventory units within
  the DID Group. Each SKU defines the price of the DID and the number of included
  channels.
- **Registration requirement** – Indicates whether end-user registration is
  required for DIDs in this area. Optionally, the restriction message can be
  displayed to the user before purchase to inform them that additional details
  will be required to activate the number.

From the ``GET /did_groups`` response, save the following values:

- ``stock_keeping_units.id`` – Required to create the DID order in the next step.
- ``requirement.id`` – Optional at this step. It can be used in later steps to validate identity and address information once the DID country and type are known and registration requirements apply (see :ref:`user-panel-api-examples-v33-verification-v33-step1-v332-v33`).

For more information, see the :ref:`/v3/did_groups <did_groups_v33_get_did_groups>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Filter by City*

      Use this approach when your flow narrows down availability by location
      (for example, after the user selects a country and a city/area). The response
      can be used to list purchasable DID Groups for that location and to determine
      whether registration is required before ordering.

      .. http:example:: curl

          GET /v3/did_groups?include=stock_keeping_units,requirement&filter[city.id]=bc7df5b9-3852-401c-b21d-8c8871efd86f HTTP/1.1
          Host: api.didww.com
          Api-Key: [API token]
          Accept: application/vnd.api+json

          HTTP/1.1 200 OK
          Content-Type: application/vnd.api+json

          {
              "data": [
                  {
                      "id": "16f7a8ea-cbfd-4429-8b94-995421d73814",
                      "type": "did_groups",
                      "attributes": {
                          "prefix": "3",
                          "features": [
                                "voice_in",
                                "sms_out"
                          ],
                          "is_metered": false,
                          "area_name": "Aachen",
                          "allow_additional_channels": true
                      },
                      "relationships": {
                          "stock_keeping_units": {
                              "data": [
                                  {
                                      "type": "stock_keeping_units",
                                      "id": "9438cb3c-8e82-4d48-8b66-ec995dc13132"
                                  },
                                  {
                                      "type": "stock_keeping_units",
                                      "id": "fedaec98-af1e-4441-bd7e-1c6668312ad5"
                                  }
                              ]
                          },
                          "requirement": {
                              "data": {
                                  "type": "requirements",
                                  "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7"
                              }
                          }
                      },
                      "meta": {
                          "needs_registration": true,
                          "is_available": true,
                          "total_count": 98
                      }
                  }
              ],
              "included": [
                  {
                      "id": "9438cb3c-8e82-4d48-8b66-ec995dc13132",
                      "type": "stock_keeping_units",
                      "attributes": {
                          "setup_price": "5.0",
                          "monthly_price": "0.4",
                          "channels_included_count": 0
                      }
                  },
                  {
                      "id": "fedaec98-af1e-4441-bd7e-1c6668312ad5",
                      "type": "stock_keeping_units",
                      "attributes": {
                          "setup_price": "5.0",
                          "monthly_price": "2.1",
                          "channels_included_count": 2
                      }
                  },
                  {
                      "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7",
                      "type": "requirements",
                      "attributes": {
                          "identity_type": "Any",
                          "personal_area_level": "WorldWide",
                          "business_area_level": "WorldWide",
                          "address_area_level": "Area",
                          "personal_proof_qty": 1,
                          "business_proof_qty": 1,
                          "address_proof_qty": 0,
                          "personal_mandatory_fields": ["id_number"],
                          "business_mandatory_fields": ["vat_id"],
                          "service_description_required": false,
                          "restriction_message": "Germany Local DID End User registration requirements:\n\nFor personal identity verification:\n* Name, last name\n* Contact phone number\n* German passport or ID copy\n\nFor business identity verification:\n* Name, last name\n* Contact phone number\n* Company name\n* German company incorporation certificate copy\n\nFor address verification:\n* Address matching the DID area code\n* Utility bill (less than 6 months old)\n"
                      }
                  }
              ]
          }

   .. tab-item:: *Display Country Coverage*

      Use this approach when your UI begins with a **country selection** and presents
      available DID options, such as on a **Buy Numbers** page with filters by DID
      Group type and features.

      By including country, region, DID Group type, SKUs, and requirement-related
      resources, your application can show registration conditions before purchase when applicable.

      .. http:example:: curl

           GET /v3/did_groups?filter[country.id]=dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e&sort=area_name&include=country,region,stock_keeping_units,did_group_type,requirement,requirement.personal_onetime_document,requirement.business_onetime_document,requirement.personal_permanent_document,requirement.business_permanent_document HTTP/1.1
           Host: api.didww.com
           Api-Key: [API token]
           Accept: application/vnd.api+json

           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json

           {
               "data": [
                   {
                       "id": "2187c36d-28fb-436f-8861-5a0f5b5a3ee1",
                       "type": "did_groups",
                       "attributes": {
                           "prefix": "241",
                           "features": [
                               "voice_in",
                               "t38"
                           ],
                           "is_metered": false,
                           "area_name": "Aachen",
                           "allow_additional_channels": true
                       },
                       "relationships": {
                           "country": {
                               "data": {
                                   "type": "countries",
                                   "id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e"
                               }
                           },
                           "did_group_type": {
                               "data": {
                                   "type": "did_group_types",
                                   "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                               }
                           },
                           "region": {
                               "data": null
                           },
                           "stock_keeping_units": {
                               "data": [
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "b98e368b-20d4-45e1-a7c3-319351b084fd"
                                   },
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "63bab5b4-c65f-4412-bca1-5085f5318317"
                                   }
                               ]
                           },
                           "requirement": {
                               "data": {
                                   "type": "requirements",
                                   "id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6"
                               }
                           }
                       },
                       "meta": {
                           "available_dids_enabled": false,
                           "needs_registration": true,
                           "is_available": true,
                           "total_count": 8
                       }
                   },
                   {
                       "id": "0b8e8c19-f3a8-4d90-a18f-657393703379",
                       "type": "did_groups",
                       "attributes": {
                           "prefix": "821",
                           "features": [
                               "voice_in",
                               "t38"
                           ],
                           "is_metered": false,
                           "area_name": "Augsburg",
                           "allow_additional_channels": true
                       },
                       "relationships": {
                           "country": {
                               "data": {
                                   "type": "countries",
                                   "id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e"
                               }
                           },
                           "did_group_type": {
                               "data": {
                                   "type": "did_group_types",
                                   "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                               }
                           },
                           "region": {
                               "data": null
                           },
                           "stock_keeping_units": {
                               "data": [
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "1a9c4d79-1306-455d-99c1-c5fd48abeae2"
                                   },
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "b31df3bb-bd5d-4315-b7c0-08a4f865c029"
                                   }
                               ]
                           },
                           "requirement": {
                               "data": {
                                   "type": "requirements",
                                   "id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6"
                               }
                           }
                       },
                       "meta": {
                           "available_dids_enabled": false,
                           "needs_registration": false,
                           "is_available": true,
                           "total_count": 11
                       }
                   }
               ],
               "included": [
                   {
                       "id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e",
                       "type": "countries",
                       "attributes": {
                           "name": "Germany",
                           "prefix": "49",
                           "iso": "DE"
                       }
                   },
                   {
                       "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
                       "type": "did_group_types",
                       "attributes": {
                           "name": "Local"
                       }
                   },
                   {
                       "id": "2c165e9d-c6f5-4fe1-ad0e-bacf5bab3d86",
                       "type": "did_group_types",
                       "attributes": {
                           "name": "National"
                       }
                   },
                   {
                       "id": "b98e368b-20d4-45e1-a7c3-319351b084fd",
                       "type": "stock_keeping_units",
                       "attributes": {
                           "setup_price": "0.0",
                           "monthly_price": "0.8",
                           "channels_included_count": 0
                       }
                   },
                   {
                       "id": "63bab5b4-c65f-4412-bca1-5085f5318317",
                       "type": "stock_keeping_units",
                       "attributes": {
                           "setup_price": "0.0",
                           "monthly_price": "4.8",
                           "channels_included_count": 2
                       }
                   },
                   {
                       "id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6",
                       "type": "requirements",
                       "attributes": {
                           "identity_type": "Any",
                           "personal_area_level": "Country",
                           "business_area_level": "Country",
                           "address_area_level": "City",
                           "personal_proof_qty": 2,
                           "business_proof_qty": 1,
                           "address_proof_qty": 1,
                           "personal_mandatory_fields": [
                               "country"
                           ],
                           "business_mandatory_fields": [
                               "country"
                           ],
                           "service_description_required": true,
                           "restriction_message": "German Local DID End User registration requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* German passport or ID copy\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n\r\nFor address verification:\r\n* Address matching: the DID area code, address in the certificate/ID (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\n ."
                       }
                   },
                   {
                       "id": "94be4d74-c968-4d81-91c5-2d11b4e45328",
                       "type": "supporting_document_templates",
                       "attributes": {
                           "name": "LOI Example",
                           "permanent": false,
                           "url": "https://api.didww.com/storage/public/xptvgb8derrz0ru95wr9oi68g9tg?response-content-disposition=attachment%3B+filename%3D%22LOI+Example.pdf%22"
                       }
                   },
                   {
                       "id": "206ccec2-1166-461f-9f58-3a56823db548",
                       "type": "supporting_document_templates",
                       "attributes": {
                           "name": "Generic LOI",
                           "permanent": false,
                           "url": "https://api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn?response-content-disposition=attachment%3B+filename%3D%22Generic+LOI.pdf%22"
                       }
                   }
               ],
               "meta": {
                   "total_records": 38,
                   "api_version": "2022-05-10"
               }
           }

.. important::

     - If ``needs_registration`` is ``true``, the DID remains inactive until end-user details
       are assigned and the verification process is created, completed, and approved.
     - If ``needs_registration`` is ``false``, no registration requirements apply
       (``requirement.data`` is ``null``), and the DID can be activated without registration.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step4-v33:

Step 4: Create the DID Order
============================

Create the DID order using the selected ``stock_keeping_units.id``.
From the order response, save the ``order.id``, which is required in the next step to retrieve the DID created by the order.

For more information, see the :ref:`/v3/orders <orders_v33_create_order>` endpoint documentation.

.. note::

   - A positive prepaid balance is required to successfully create a DID order.
   - For simplicity, detailed item attributes are not included in this response example.

.. http:example:: curl

    POST /v3/orders HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "orders",
        "attributes": {
          "allow_back_ordering": true,
          "items": [
            {
              "type": "did_order_items",
              "attributes": {
                "sku_id": "fedaec98-af1e-4441-bd7e-1c6668312ad5",
                "qty": 1
              }
            }
          ]
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "38ba6528-7460-410c-8fcc-262afb005ab3",
            "type": "orders",
            "attributes": {
                "amount": "2.1",
                "status": "Pending",
                "created_at": "2026-01-08T09:10:20.270Z",
                "description": "DID",
                "reference": "YOY-267643"
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step5-v33:

Step 5: Retrieve the DID ID Created by the DID Order
====================================================

.. note::

   You may retrieve the DID ID immediately after the order is created, as shown
   in this step, or retrieve it later depending on your application flow and
   user interface design.

   Retrieving the DID ID at this stage is optional. The DID ID is not required to
   retrieve registration requirements or to create identity and address resources.
   However, it is required later when assigning end-user details and starting DID
   verification (see :ref:`user-panel-api-examples-v33-verification-v33-step1-v333-v33`).

Retrieve the DID resource created by the order using the saved ``order.id``.
From the response, save the ``did.id`` for future reference.

For more information, see the :ref:`/v3/dids <dids_v33>` resource documentation.

.. http:example:: curl

    GET /v3/dids?filter[order.id]=38ba6528-7460-410c-8fcc-262afb005ab3 HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "ad74ee84-aac8-4006-8c91-c08c59a32200",
                "type": "dids",
                "attributes": {
                    "blocked": true,
                    "capacity_limit": null,
                    "description": null,
                    "terminated": false,
                    "awaiting_registration": true,
                    "created_at": "2026-01-16T07:38:42.000Z",
                    "billing_cycles_count": null,
                    "number": "4924111111112",
                    "expires_at": "2026-02-16T07:38:42.508Z",
                    "channels_included_count": 2,
                    "dedicated_channels_count": 0
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2022-05-10"
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step6-v33:

Step 6: Retrieve and Review Registration Requirements
=====================================================

Depending on your application flow, registration requirements may already be
known. For example, they may be displayed together with a DID Group while
displaying number availability or coverage information, or they may be retrieved
dynamically based on user selections such as country and DID Group type. If the
requirement is already known, use the saved ``requirement.id`` from Step 3
(:ref:`Get the SKU ID and Registration Requirement
<user-panel-api-examples-v33-sku-and-requirements-v33>`) to retrieve the full registration
requirement details.

In all cases, the retrieved requirement defines the identity, address, proofs,
and supporting documents that must be created in the next steps and serves as
the authoritative source for validation and verification.

The registration requirement specifies:

- which identity types (Personal or Business) are allowed
- which identity fields are mandatory
- how many identity and address proofs must be provided
- which proof types are accepted
- whether address proofs are required
- whether permanent and/or one-time supporting documents are required
- whether a service description must be provided
- any country, area, or city restrictions that apply

Before continuing to the next steps, review the **accepted proof types** defined
in the registration requirement. These proof types determine which document
categories the end user is allowed to submit for identity or address verification.

Your application should use this information to display valid document options
to the user (for example, Passport or Utility Bill) and to ensure that each
uploaded and encrypted document is linked to an accepted proof type when
creating proofs in :ref:`Step 10 <user-panel-api-examples-v33-verification-v33-step1-v330-v33>`.

Accepted proof types are provided in the requirement response under the following
relationships:

- **Business identity proofs** ``relationships.business_proof_types.data[].id``
- **Personal identity proofs** ``relationships.personal_proof_types.data[].id``
- **Address proofs** (if required) ``relationships.address_proof_types.data[].id``

Each proof created later must reference one of these accepted proof types,
together with an encrypted document and the corresponding identity or address.

For more information, see the :ref:`Requirements <requirements_v33>` resource documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Retrieve by Requirement ID*

      Use this approach when you already have the ``requirement.id`` (for example,
      it was returned in Step 3 together with the selected SKU/DID Group). This
      request returns the full requirement details, including accepted proof types
      and supporting document templates.

      .. http:example:: curl

            GET /v3/requirements?filter[id]=c6f606d8-106a-43d6-997e-17c7da5ae5d7&include=personal_proof_types,business_proof_types,address_proof_types,personal_permanent_document,business_permanent_document,personal_onetime_document,business_onetime_document HTTP/1.1
            Host: api.didww.com
            Api-Key: [API token]
            Accept: application/vnd.api+json

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7",
                        "type": "requirements",
                        "attributes": {
                            "identity_type": "Any",
                            "personal_area_level": "WorldWide",
                            "business_area_level": "WorldWide",
                            "address_area_level": "Area",
                            "personal_proof_qty": 1,
                            "business_proof_qty": 1,
                            "address_proof_qty": 0,
                            "personal_mandatory_fields": ["id_number"],
                            "business_mandatory_fields": ["vat_id"],
                            "service_description_required": false,
                            "restriction_message": "German Local DID End User registration requirements: ..."
                        },
                        "relationships": {
                            "personal_permanent_document": {
                                "data": {
                                    "type": "supporting_document_templates",
                                    "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                                }
                            },
                            "business_permanent_document": {
                                "data": {
                                    "type": "supporting_document_templates",
                                    "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                                }
                            },
                            "personal_onetime_document": {
                                "data": null
                            },
                            "business_onetime_document": {
                                "data": null
                            },
                            "personal_proof_types": {
                                "data": [
                                    {
                                        "type": "proof_types",
                                        "id": "108b1fcf-686e-4017-a6c7-cf38c175f76a"
                                    }
                                ]
                            },
                            "business_proof_types": {
                                "data": [
                                    {
                                        "type": "proof_types",
                                        "id": "80253913-cd8b-4ce2-91a9-9299587ac409"
                                    }
                                ]
                            },
                            "address_proof_types": {
                                "data": []
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
                        "type": "supporting_document_templates",
                        "attributes": {
                            "name": "Belgium Registration Form",
                            "permanent": true,
                            "url": "https://api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra?response-content-disposition=attachment%3B+filename%3D%22Belgium+Registration+Form.pdf%22"
                        }
                    },
                    {
                        "id": "108b1fcf-686e-4017-a6c7-cf38c175f76a",
                        "type": "proof_types",
                        "attributes": {
                            "name": "Passport",
                            "entity_type": "Personal"
                        }
                    },
                    {
                        "id": "80253913-cd8b-4ce2-91a9-9299587ac409",
                        "type": "proof_types",
                        "attributes": {
                            "name": "Passport",
                            "entity_type": "Business"
                        }
                    }
                ]
            }

   .. tab-item:: *Retrieve by Country and DID Group Type*

      Use this approach when the registration ``requirement.id`` is not known in advance and
      your application allows the user to check requirements based on their selection.
      After the user selects a **country** and a **DID Group type**, retrieve the
      matching requirements (including ``country`` and ``did_group_type``) and display:

        - the ``restriction_message``
        - any available supporting document template download links (when present)

      .. http:example:: curl

          GET /v3/requirements?include=country,did_group_type,personal_permanent_document,business_permanent_document HTTP/1.1
          Host: api.didww.com
          Api-Key: [API token]
          Accept: application/vnd.api+json

          HTTP/1.1 200 OK
          Content-Type: application/vnd.api+json

          {
            "data": [
              {
                "id": "6f71cc7b-8c13-4958-8623-60f750b8bcca",
                "type": "requirements",
                "attributes": {
                  "identity_type": "Any",
                  "personal_area_level": "WorldWide",
                  "business_area_level": "WorldWide",
                  "address_area_level": "Area",
                  "personal_proof_qty": 1,
                  "business_proof_qty": 0,
                  "address_proof_qty": 0,
                  "personal_mandatory_fields": null,
                  "business_mandatory_fields": null,
                  "service_description_required": false,
                  "restriction_message": "French Local DID End User registration requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n\r\nFor address verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.\r\n\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process."
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/country",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "7d9f8011-40a4-4fd7-a970-c3b679a75daf"
                    }
                  },
                  "did_group_type": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/did_group_type",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/did_group_type"
                    },
                    "data": {
                      "type": "did_group_types",
                      "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                    }
                  },
                  "personal_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_permanent_document",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_permanent_document"
                    },
                    "data": {
                      "type": "supporting_document_templates",
                      "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                    }
                  },
                  "business_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_permanent_document",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_permanent_document"
                    },
                    "data": null
                  },
                  "personal_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_onetime_document",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_onetime_document"
                    }
                  },
                  "business_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_onetime_document",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_onetime_document"
                    }
                  },
                  "personal_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_proof_types",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_proof_types"
                    },
                    "data": [
                      {
                        "type": "proof_types",
                        "id": "19cd7b22-559b-41d4-99c9-7ad7ad63d5d1"
                      }
                    ]
                  },
                  "business_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_proof_types",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_proof_types"
                    }
                  },
                  "address_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/address_proof_types",
                      "related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/address_proof_types"
                    }
                  }
                }
              },
              {
                "id": "273d3bec-9a13-45b0-8fb4-c06bf46c1b34",
                "type": "requirements",
                "attributes": {
                  "identity_type": "Any",
                  "personal_area_level": "WorldWide",
                  "business_area_level": "WorldWide",
                  "address_area_level": "WorldWide",
                  "personal_proof_qty": 0,
                  "business_proof_qty": 0,
                  "address_proof_qty": 2,
                  "personal_mandatory_fields": null,
                  "business_mandatory_fields": null,
                  "service_description_required": true,
                  "restriction_message": "Japanese Local DID End User registration requirements:\r\n\r\n* For personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* Company incorporation certificate copy\r\n\r\nFor address verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.\r\n\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process."
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/country",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "eb89ebf7-2c8c-4e7d-9aea-89cddeced3c8"
                    }
                  },
                  "did_group_type": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/did_group_type",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/did_group_type"
                    },
                    "data": {
                      "type": "did_group_types",
                      "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                    }
                  },
                  "personal_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_permanent_document",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_permanent_document"
                    },
                    "data": null
                  },
                  "business_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_permanent_document",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_permanent_document"
                    },
                    "data": null
                  },
                  "personal_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_onetime_document",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_onetime_document"
                    }
                  },
                  "business_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_onetime_document",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_onetime_document"
                    }
                  },
                  "personal_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_proof_types",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_proof_types"
                    },
                    "data": []
                  },
                  "business_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_proof_types",
                      "related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_proof_types"
                    }
                  },
                }
              }
            ],
            "included": [
              {
                "id": "7549be3c-1077-433d-9a77-25416373660d",
                "type": "countries",
                "attributes": {
                  "name": "Sweden",
                  "prefix": "46",
                  "iso": "SE"
                },
              },
              {
                "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                "type": "countries",
                "attributes": {
                  "name": "Canada",
                  "prefix": "1",
                  "iso": "CA"
                },
              },
              {
                "id": "fccd5be9-41dc-4daf-8894-234ecc916731",
                "type": "countries",
                "attributes": {
                  "name": "China",
                  "prefix": "86",
                  "iso": "CN"
                },
              },
              {
                "id": "6bba60f1-e724-4d12-9ea4-a3a64705800f",
                "type": "did_group_types",
                "attributes": { "name": "Mobile" }
              },
              {
                "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
                "type": "did_group_types",
                "attributes": { "name": "Local" }
              },
              {
                "id": "2c165e9d-c6f5-4fe1-ad0e-bacf5bab3d86",
                "type": "did_group_types",
                "attributes": { "name": "National" }
              },
              {
                "id": "d6530a8c-924c-469a-98c0-9525602e6192",
                "type": "did_group_types",
                "attributes": { "name": "Global" }
              },
              {
                "id": "ec95e831-fc36-489a-a531-0fd1984ab6e8",
                "type": "did_group_types",
                "attributes": { "name": "Toll-free" }
              },
              {
                "id": "eb810289-8620-44e1-982d-13e6cee70404",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Document Template 1",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/owwqi77007ks4qx198b7su3eukg6?response-content-disposition=attachment%3B+filename%3D%22TestPermanDoc.png%22"
                }
              },
              {
                "id": "f65149c1-b551-4444-97d7-22939445c42a",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Document Template 2",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/txm3ftmuhyhypm6553b2874iuljg?response-content-disposition=attachment%3B+filename%3D%22TestDoc4.pdf%22"
                }
              },
              {
                "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Belgium Registration Form",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra?response-content-disposition=attachment%3B+filename%3D%22Belgium+Registration+Form.pdf%22"
                }
              },
              {
                "id": "4199435f-646e-4e9d-a143-8f3b972b10c5",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Germany Special Registration Form",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/4rghqnqtba0fa7mbdgig086xej1e?response-content-disposition=attachment%3B+filename%3D%22Germany+Special+Registration+Form.pdf%22"
                }
              }
            ],
            "meta": {
              "total_records": 52,
              "api_version": "2022-05-10"
            }
          }

      .. tip::
          In the UI, filter the returned requirements by the selected
          ``country.id`` and ``did_group_type.id``. Once a match is found, display
          its ``restriction_message`` and provide download links for any included
          supporting document templates.

Registration requirement field reference
----------------------------------------

Use the requirement attributes and relationships to decide what to create in the
next steps.

.. list-table::
   :widths: 13 15 45
   :header-rows: 1

   * - Category
     - API fields
     - How to interpret and apply them

   * - **Identity type**
     - ``identity_type``
     - Defines which identity types are allowed:

       - ``Any``: personal and business identities are allowed.
       - ``Personal``: only a personal identity is allowed.
       - ``Business``: only a business identity is allowed.

       The identity you create **must match** this value.

   * - **Identity restrictions**
     - ``personal_area_level``, |br| ``business_area_level``
     - Defines geographic restrictions for the identity:

       - ``WorldWide``: the identity can belong to any country.
       - ``Country``: the identity country must match the DID country.

       When ``Country`` is required, set the identity country using the
       ``relationships.country`` relationship when creating the identity.

   * - **Address restrictions**
     - ``address_area_level``
     - Defines where the address must be located:

       - ``WorldWide``: any country is allowed.
       - ``Country``: address must match the DID country.
       - ``Area`` or ``City``: address must match the DID area or city.

       Address relationships and attributes (such as ``country``,
       ``city_name``) must comply with these restrictions.

   * - **Mandatory identity fields**
     - ``personal_mandatory_fields``, |br| ``business_mandatory_fields``
     - Lists identity fields that must be provided when creating the identity.

   * - **Proof quantity requirements**
     - ``personal_proof_qty``, |br| ``business_proof_qty``, |br|
       ``address_proof_qty``
     - Specifies how many proofs must be submitted:

       - ``business_proof_qty = 1`` means exactly one business proof is required.
       - ``address_proof_qty = 0`` means no address proof is required.

   * - **Accepted proof types**
     - ``relationships.personal_proof_types``, |br|
       ``relationships.business_proof_types``, |br|
       ``relationships.address_proof_types``
     - Defines which proof types are accepted for each entity.

       Save the corresponding ``proof_type.id`` for use when creating proofs.

   * - **Supporting documents**
     - ``personal_permanent_document``, |br|
       ``business_permanent_document``, |br|
       ``personal_onetime_document``, |br|
       ``business_onetime_document``
     - Defines whether permanent or one-time supporting documents are required.

       - Permanent documents can be reused for future verifications.
       - One-time documents must be submitted with the verification task.

   * - **Service description**
     - ``service_description_required``
     - Indicates whether a service description must be provided during
       verification.

   * - **Restriction message**
     - ``restriction_message``
     - Provides a human-readable summary of regulatory requirements for the DID
       area.

   * - **Supporting document templates**
     - ``included[].type = supporting_document_templates``
     - Defines required supporting documents when
       ``personal_permanent_document`` or ``business_permanent_document`` is present.

       Each template includes:

       - ``name`` – the document name displayed to the end user
       - ``permanent`` – whether the document can be reused for future verifications
       - ``url`` – a downloadable template that must be completed, encrypted,
         and uploaded

       Example: ``Belgium Registration Form`` is a permanent document.

   * - **Proof type definitions**
     - ``included[].type = proof_types``
     - Describes the proof types accepted for identity or address verification.

       Each proof type includes:

       - ``name`` – the document type (e.g. Passport)
       - ``entity_type`` – whether it applies to ``Personal`` or ``Business`` identities

       Use these entries together with the corresponding
       ``relationships.proof_types`` to select the correct proof when creating
       identity or address proofs.

.. note::
   Registration requirements vary by DID Group, country, and identity type.
   Retrieve and follow the requirement linked to your DID Group.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step7-v33:

Step 7: Create an Identity
==========================

Collect the required information from the end user purchasing the DID. This
includes selecting the identity type (**personal** or **business**) and
providing all mandatory fields defined by the applicable regulatory
requirements, such as name, contact details, and country information.

Create an identity that will later be assigned to the DID when creating the
verification task in
:ref:`Step 13 <user-panel-api-examples-v33-verification-v33-step1-v333-v33>`. From the response,
save the ``identity.id``, which is required to create an address for the identity
in the next step.

Ensure the identity complies with the regulatory requirements retrieved in
:ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`, including the
allowed identity type (personal or business), mandatory fields, applicable
country restrictions, and the number and type of proofs required for the DID
number.

For more information, see the :ref:`Identity <identities_v33>` resource documentation.

.. note::
   - Identity attributes depend on the registration requirement and the selected identity type. Always include any fields listed under ``personal_mandatory_fields`` or ``business_mandatory_fields`` from :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`.
   - If the requirement restricts the identity to a specific country (``personal_area_level = country`` or ``business_area_level = country``), set the identity country using the ``relationships.country`` relationship.
   - For business identities, ``first_name`` and ``last_name`` typically represent the authorized contact person.
   - Identities may be reused for multiple DID verifications, provided they continue to meet the applicable requirements.

.. http:example:: curl

    POST /v3/identities HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
        "data": {
            "type": "identities",
            "attributes": {
                "identity_type": "Business",
                "company_name": "Example Company Ltd",
                "first_name": "John",
                "last_name": "Smith",
                "phone_number": "3233461122",
                "vat_id": "BE0123456789"
            },
            "relationships": {
                "country": {
                    "data": {
                        "type": "countries",
                        "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
                    }
                }
            }
        }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
            "type": "identities",
            "attributes": {
                "first_name": "John",
                "last_name": "Smith",
                "phone_number": "3233461122",
                "company_name": "Example Company Ltd",
                "vat_id": "BE0123456789",
                "identity_type": "Business",
                "verified": false
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

.. tip::
   Before continuing, you can validate whether the created **identity** meets the
   regulatory requirements by validating it against the ``requirement.id``
   (see :ref:`Step 12 <user-panel-api-examples-v33-verification-v33-step1-v332-v33>`).

   This allows you to detect issues (such as an invalid identity type or missing
   mandatory fields) early, before assigning the identity to the DID. If the
   identity complies with the requirement, the validation request succeeds
   without errors.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step8-v33:

Step 8: Create an Address
=========================

Collect the required address information from the end user purchasing the DID.
This typically includes street address, city, postal code, and country, based on
the applicable regulatory requirements.

Create an address that will later be assigned to the DID in
:ref:`Step 13 <user-panel-api-examples-v33-verification-v33-step1-v333-v33>`, and link it to the
identity created in
:ref:`Step 7 <user-panel-api-examples-v33-verification-v33-step7-v33>`.

Ensure it complies with the regulatory requirements retrieved in
:ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`, including the
acceptable geographic scope (for example, ``address_area_level = country``) and
any other applicable requirements.

From the response, save the ``address.id``. This value is required only if the
registration requirement specifies an address proof (``address_proof_qty > 0``).
Address proofs are linked to the address (not the identity), and the proof type must be one of the accepted proof types listed under
``relationships.address_proof_types`` in the requirement response (:ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`).

For more information, see the :ref:`Addresses <addresses_v33>` resource documentation.

.. http:example:: curl

    POST /v3/addresses HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "addresses",
        "attributes": {
          "address": "10 Example Street",
          "city_name": "Antwerp",
          "postal_code": "2000",
          "description": "Business registration address"
        },
        "relationships": {
          "identity": {
            "data": {
              "type": "identities",
              "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
            }
          },
          "country": {
            "data": {
              "type": "countries",
              "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
            }
          }
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "04072428-07e4-4026-9d11-b49a770a95a8",
            "type": "addresses",
            "attributes": {
                "address": "10 Example Street",
                "city_name": "Antwerp",
                "postal_code": "2000",
                "description": "Business registration address",
                "verified": false,
                "created_at": "2026-01-09T09:22:23.066Z"
            },
            "relationships": {
                "identity": {
                    "data": {
                        "type": "identities",
                        "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                    }
                },
                "country": {
                    "data": {
                        "type": "countries",
                        "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
                    }
                }
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

.. tip::
   Before continuing, you can validate the **address** or both the **identity**
   and **address** together against the ``requirement.id`` to ensure they meet
   the regulatory requirements (see
   :ref:`Step 12 <user-panel-api-examples-v33-verification-v33-step1-v332-v33>`).

   This helps detect issues early—such as an invalid identity type or missing
   mandatory fields—before assigning the identity or address to the DID. If the
   submitted data complies with the requirement, the validation request
   completes successfully without errors.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step9-v33:

Step 9: Encrypt and Upload Documents
====================================

After reviewing the registration requirements in
:ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>` and collecting the
required identity and address information, your application may need to request
supporting documents from the end user.

Depending on the requirement, this can include identity proofs (for example,
a passport or national ID) and/or address proofs (such as a utility bill).
These documents are provided by the user based on the accepted proof types and
supporting document rules defined in the registration requirement.

If a registration requirement specifies identity proofs or supporting documents,
those documents must be encrypted before upload. All documents submitted to the
DIDWW API require encryption to ensure secure handling.

Document encryption protects sensitive personal and business information during
transmission and storage. It ensures that identity and address documents remain
confidential.

Encryption always produces a file with the ``.enc`` suffix. Only encrypted files
are accepted by the ``/v3/encrypted_files`` endpoint.

Encrypt the document
--------------------

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Browser-based encryption*

      Encrypt the document in the browser using the DIDWW encryption
      library. This approach is commonly used in web applications.

      Encryption library:
          - `@didww/encrypt <https://github.com/didww/didww-encrypt>`_

      Encryption steps:
          1. Select the original document (for example, ``passport.pdf``).
          2. Encrypt the file using the library.
          3. Save the encrypted output with the ``.enc`` suffix
             (for example, ``passport.pdf.enc``).

      The result of this process is a ready-to-use encrypted file that can be uploaded to the API in the next step.

   .. tab-item:: *Server-side encryption*

      Encrypt the document on the server using one of the supported SDKs.
      This approach is commonly used in backend services.

      .. grid:: 1 1 1 3
           :gutter: 4
           :padding: 0

           .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Gem**
              :link: https://github.com/didww/didww-v3-ruby/blob/master/lib/didww/encrypt.rb
              :link-type: url
              :text-align: left

              Use the APIv3 Ruby gem to perform file encryption on the server side.

           .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
              :link: https://github.com/didww/didww-api-3-php-sdk/blob/master/src/Encrypt.php
              :link-type: url
              :text-align: left

              Use the official PHP SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
              :link: https://github.com/didww/didww-api-3-java-sdk/blob/main/src/main/java/com/didww/sdk/Encrypt.java
              :link-type: url
              :text-align: left

              Use the official Java SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
              :link: https://github.com/didww/didww-api-3-python-sdk/blob/main/src/didww/encrypt.py
              :link-type: url
              :text-align: left

              Use the official Python SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
              :link: https://github.com/didww/didww-api-3-typescript-sdk/blob/main/src/encrypt.ts
              :link-type: url
              :text-align: left

              Use the official TypeScript SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`logos:go` **Go Encryption Sample**
              :link: https://github.com/didww/go-encrypt-sample
              :link-type: url
              :text-align: left

               Use the Go sample project to implement server-side file encryption compatible with DIDWW API v3.

           .. grid-item-card:: :iconify:`devicon:dot-net` **.NET Encryption Sample**
              :link: https://github.com/didww/didww-api-3-dotnet-sdk/blob/main/src/Didww.Api3/Encrypt.cs
              :link-type: url
              :text-align: left

              Use the .NET sample implementation to add server-side file encryption compatible with DIDWW API v3.

      Encryption steps:
          1. Load the original document on the server.
          2. Encrypt the file using one of the supported libraries.
          3. Save the encrypted output with the ``.enc`` suffix.

      The result of this process is a ready-to-use encrypted file.

Upload the encrypted file
-------------------------

.. note::
   - Uploaded encrypted files expire after **24 hours**
   - Accepted file formats: **.pdf**, **.jpg**, **.png**
   - Up to **5 encrypted files** may be uploaded in a single request
   - Each file must not exceed **20 MB**

Upload the encrypted ``.enc`` files using the ``/v3/encrypted_files`` endpoint. This endpoint uses ``Content-Type: multipart/form-data`` and does **not** accept
JSON request bodies.

Each uploaded encrypted file is stored securely and results in a unique **encrypted file ID**. Returned IDs are provided in the ``ids`` array, where each
value represents an ``encrypted_file.id``.

..

Save these ``encrypted_file.id`` values, as they are required in later steps when:

- creating identity or address proofs (see :ref:`Step 10: Create Identity and Address Proofs <user-panel-api-examples-v33-verification-v33-step1-v330-v33>`)
- attaching permanent supporting documents, if required (see :ref:`Step 11: Create a Permanent Supporting Document <user-panel-api-examples-v33-verification-v33-step1-v331-v33>`)
- attaching one-time supporting documents, if required (see :ref:`Step 13: Assign End-User Details and Start DID Verification <user-panel-api-examples-v33-verification-v33-step1-v333-v33>`)

For more details, see the :ref:`Encrypted Files <encrypted_files_v33>` resource documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Upload a single encrypted file*

      Use this approach when uploading **one document** (for example,
      a passport used as an identity proof).

      .. tab-set::
         :class: my-tabs

         .. tab-item:: curl

            .. code-block:: bash

               curl --location 'https://api.didww.com/v3/encrypted_files' \
                 --header 'Accept: application/vnd.api+json' \
                 --header 'Content-Type: multipart/form-data' \
                 --header 'Api-Key: [API token]' \
                 --form 'encrypted_files[encryption_fingerprint]={{encryption_fingerprint}}' \
                 --form 'encrypted_files[items][][description]=passport' \
                 --form 'encrypted_files[items][][file]=@"/path/to/passport.pdf.enc"'

         .. tab-item:: Response

            .. code-block:: json

               {
                   "ids": [
                       "66df7731-fcf9-4bf3-a03f-2881bd44fe9c"
                   ]
               }

   .. tab-item:: *Upload multiple encrypted files*

      Use this approach when uploading **multiple documents at once**,
      such as an identity proof and a permanent supporting document.

      .. tab-set::
         :class: my-tabs

         .. tab-item:: curl

            .. code-block:: bash

               curl --location 'https://api.didww.com/v3/encrypted_files' \
                 --header 'Accept: application/vnd.api+json' \
                 --header 'Content-Type: multipart/form-data' \
                 --header 'Api-Key: [API token]' \
                 --form 'encrypted_files[encryption_fingerprint]={{encryption_fingerprint}}' \
                 --form 'encrypted_files[items][][description]=passport' \
                 --form 'encrypted_files[items][][file]=@"/path/to/passport.pdf.enc"' \
                 --form 'encrypted_files[items][][description]=belgium-registration-form' \
                 --form 'encrypted_files[items][][file]=@"/path/to/belgium_registration_form.pdf.enc"'

         .. tab-item:: Response

            .. code-block:: json

               {
                   "ids": [
                       "66df7731-fcf9-4bf3-a03f-2881bd44fe9c",
                       "e5686c72-76fd-461e-bcfa-66c19be680f5"
                   ]
               }

.. note::
   To upload additional encrypted files in the same request, repeat the following
   form field pair for each additional file:

   - ``encrypted_files[items][][description]``
   - ``encrypted_files[items][][file]``

   The order of IDs in the response corresponds to the order of files provided in the multipart form fields.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step1-v330-v33:

Step 10: Create Identity and Address Proofs
===========================================

After the required documents have been encrypted and uploaded
(:ref:`Step 9 <user-panel-api-examples-v33-verification-v33-step9-v33>`), they must be
associated with the appropriate identity or address as **proofs**.

Proof records represent the relationship between an uploaded document and the
entity it validates. Depending on the registration requirement, proofs may be
required for an identity (personal or business), an address, or both.

If the registration requirement specifies that proofs are required, create proof
records and link them to the corresponding entities involved in the verification
process. Each proof references an encrypted document, an accepted proof type,
and the entity it applies to.

These proof records are evaluated later in
:ref:`Step 12 <user-panel-api-examples-v33-verification-v33-step1-v332-v33>`, where the identity
and address are validated against the registration requirement

.. note::
   Proofs are required only when the corresponding quantity
   (``business_proof_qty``, ``personal_proof_qty``, or ``address_proof_qty``)
   is greater than ``0`` in the registration requirement.

Each proof requires:

    - an ``encrypted_file.id`` obtained in :ref:`Step 9 <user-panel-api-examples-v33-verification-v33-step9-v33>` where the user uploads a document, the application encrypts it, and the encrypted file is submitted to the API
    - a ``proof_type.id`` accepted by the registration requirement retrieved in :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`
    - an ``entity`` the proof applies to (use ``identities.id`` for identity proofs or ``addresses.id`` for address proofs)

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Create an identity proof*

      Use this approach when the registration requirement specifies
      ``business_proof_qty`` or ``personal_proof_qty`` greater than ``0``.

      .. note::
           The ``proof_type.id`` **must** be selected from the accepted proof types
           defined in the registration requirement retrieved in
           :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`:

           - use ``relationships.personal_proof_types.data[].id`` for **personal** identities
           - use ``relationships.business_proof_types.data[].id`` for **business** identities

      .. http:example:: curl

         POST /v3/proofs HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "proofs",
                 "relationships": {
                     "files": {
                         "data": [
                             {
                                 "type": "encrypted_files",
                                 "id": "66df7731-fcf9-4bf3-a03f-2881bd44fe9c"
                             }
                         ]
                     },
                     "proof_type": {
                         "data": {
                             "type": "proof_types",
                             "id": "80253913-cd8b-4ce2-91a9-9299587ac409"
                         }
                     },
                     "entity": {
                         "data": {
                             "type": "identities",
                             "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "f03ec8b2-535e-46a4-a951-60922203a48c",
                 "type": "proofs",
                 "attributes": {
                     "created_at": "2026-01-09T13:20:09.232Z",
                     "expires_at": null
                 }
             },
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

   .. tab-item:: *Create an address proof*

      Use this approach **only if** the registration requirement specifies
      ``address_proof_qty`` greater than ``0``.

      .. note::
           The proof type **must** be one of the accepted proof types listed under
           ``address_proof_types`` in the registration requirement retrieved in
           :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`.
           Link the proof to the address by setting ``entity.type`` to ``addresses`` and
           ``entity.id`` to your ``address.id``.

      .. http:example:: curl

         POST /v3/proofs HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "proofs",
                 "relationships": {
                     "files": {
                         "data": [
                             {
                                 "type": "encrypted_files",
                                 "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                             }
                         ]
                     },
                     "proof_type": {
                         "data": {
                             "type": "proof_types",
                             "id": "ffffffff-1111-2222-3333-444444444444"
                         }
                     },
                     "entity": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "f03ec8b2-535e-46a4-a951-60922203a48d",
                 "type": "proofs",
                 "attributes": {
                     "created_at": "2026-01-09T13:20:09.232Z",
                     "expires_at": null
                 }
             },
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step1-v331-v33:

Step 11: Create a Permanent Supporting Document (If Required)
=============================================================

Some registration requirements mandate a **permanent supporting document**
(template-based document) to be submitted together with the **identity**.

A permanent supporting document is required when the registration requirement
contains one of the following:

- ``business_permanent_document`` (for business identities)
- ``personal_permanent_document`` (for personal identities)

.. note::
   If both ``business_permanent_document`` and ``personal_permanent_document`` are
   ``null`` in the requirement response, no permanent supporting document is
   required and this step can be skipped.

Each permanent supporting document requires:

- an ``encrypted_file.id`` obtained in
  :ref:`Step 9 <user-panel-api-examples-v33-verification-v33-step9-v33>` after the user
  uploads the completed document and it is encrypted by the application
- a ``supporting_document_template.id`` defined by the registration requirement
  retrieved in :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>`
- an ``identity.id`` corresponding to the personal or business identity created in
  :ref:`Step 7 <user-panel-api-examples-v33-verification-v33-step7-v33>`

For additional details, see the
:ref:`Permanent Supporting Documents <create_permanent_supporting_document_v33>`
resource documentation.

.. http:example:: curl

    POST /v3/permanent_supporting_documents HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
        "data": {
            "type": "permanent_supporting_documents",
            "relationships": {
                "files": {
                    "data": [
                        {
                            "type": "encrypted_files",
                            "id": "e5686c72-76fd-461e-bcfa-66c19be680f5"
                        }
                    ]
                },
                "template": {
                    "data": {
                        "type": "supporting_document_templates",
                        "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                    }
                },
                "identity": {
                    "data": {
                        "type": "identities",
                        "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                    }
                }
            }
        }
    }

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "363abdd4-2286-4b53-ab42-9726d61adc77",
            "type": "permanent_supporting_documents",
            "attributes": {
                "created_at": "2026-01-12T08:55:57.553Z"
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step1-v332-v33:

Step 12: Validate Identity and Address Against Requirements
===========================================================

Validate the identity, address, and all submitted proofs against the
registration requirement **before** starting the DID verification task.

This validation confirms that all regulatory conditions have been met and allows you
to detect missing or invalid data early, such as incomplete identity fields,
missing proofs, unsupported proof types, or address scope mismatches.

.. note::
    Validation is required only when the DID Group has a registration requirement
    (``needs_registration = true``).

The validation checks that:

- all mandatory identity fields are present
- the required number and type of proofs and supporting documents have been submitted
- the address meets the geographic restrictions defined by the requirement

If the validation succeeds, the identity and address are considered compliant
and can be safely assigned to the DID in the next step to start verification.

For additional details about requirement validation, see :ref:`Validate <requirement_validations_v33>`.

.. http:example:: curl

    POST /v3/requirement_validations HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
        "data": {
            "type": "requirement_validations",
            "relationships": {
                "requirement": {
                    "data": {
                        "type": "requirements",
                        "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7"
                    }
                },
                "identity": {
                    "data": {
                        "type": "identities",
                        "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                    }
                },
                "address": {
                    "data": {
                        "type": "addresses",
                        "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                    }
                }
            }
        }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "e67bc7f0-71c1-451b-978e-d9188bcd39fa",
            "type": "requirement_validations"
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

.. note::

    If the validation request is rejected, review the error details and adjust
    the identity, address, proofs, or supporting documents accordingly.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-verification-v33-step1-v333-v33:

Step 13: Assign End-User Details and Start DID Verification
===========================================================

Create the verification task that assigns the validated **identity and address** to the DID and initiates the regulatory verification process.

.. note:: This step should be performed **only after** the identity, address, proofs, and documents have been successfully validated in :ref:`Step 12 <user-panel-api-examples-v33-verification-v33-step1-v332-v33>`.

The verification task evaluates all previously submitted data, including:

- the identity
- the address
- identity and address proofs (if required)
- permanent supporting documents (if required)
- one-time supporting documents (if required)

For more information, see :ref:`Address Verifications <address_verifications_v33>`.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Basic verification*

      Use this structure when the registration requirement does **not**
      specify a one-time supporting document.

      .. http:example:: curl

         POST /v3/address_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "address_verifications",
                 "attributes": {
                     "callback_url": "https://example.com/callback",
                     "callback_method": "POST"
                 },
                 "relationships": {
                     "dids": {
                         "data": [
                             {
                                 "type": "dids",
                                 "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
                             }
                         ]
                     },
                     "address": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "066395a4-7904-4a68-97d2-a2fc007d0634",
                 "type": "address_verifications",
                 "attributes": {
                     "service_description": null,
                     "callback_url": "https://example.com/callback",
                     "callback_method": "POST",
                     "status": "Pending",
                     "reject_reasons": null,
                     "reference": "SVA-822866",
                     "created_at": "2026-01-12T09:46:19.214Z"
                 }
             },
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

   .. tab-item:: *Verification with one-time document*

      Use this structure **only** when the registration requirement retrieved in :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>` defines a
      **one-time supporting document** under ``personal_onetime_document`` or ``business_onetime_document``.

      .. http:example:: curl

         POST /v3/address_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "address_verifications",
                 "attributes": {
                     "callback_url": "https://example.com/callback",
                     "callback_method": "POST"
                 },
                 "relationships": {
                     "onetime_files": {
                         "data": [
                             {
                                 "type": "encrypted_files",
                                 "id": "11111111-2222-3333-4444-555555555555"
                             }
                         ]
                     },
                     "dids": {
                         "data": [
                             {
                                 "type": "dids",
                                 "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
                             }
                         ]
                     },
                     "address": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "066395a4-7904-4a68-97d2-a2fc007d0634",
                 "type": "address_verifications",
                 "attributes": {
                     "service_description": null,
                     "callback_url": "https://example.com/callback",
                     "callback_method": "POST",
                     "status": "Pending",
                     "reject_reasons": null,
                     "reference": "SVA-822866",
                     "created_at": "2026-01-12T09:46:19.214Z"
                 }
             },
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

   .. tab-item:: *Verification with service description*

      Use this structure when the registration requirement retrieved in
      :ref:`Step 6 <user-panel-api-examples-v33-verification-v33-step6-v33>` allows or requires
      providing a **service description** (``service_description_required = true``).

      The service description explains the intended use of the DID number
      (for example, customer support, outbound sales, or application notifications)
      and is evaluated as part of the regulatory verification process.

      .. http:example:: curl

         POST /v3/address_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "address_verifications",
                 "attributes": {
                     "callback_url": "https://example.com/callback",
                     "callback_method": "POST",
                     "service_description": "Inbound customer support calls for a SaaS platform"
                 },
                 "relationships": {
                     "dids": {
                         "data": [
                             {
                                 "type": "dids",
                                 "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
                             }
                         ]
                     },
                     "address": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "066395a4-7904-4a68-97d2-a2fc007d0634",
                 "type": "address_verifications",
                 "attributes": {
                     "service_description": "Inbound customer support calls for a SaaS platform",
                     "callback_url": "https://example.com/callback",
                     "callback_method": "POST",
                     "status": "Pending",
                     "reject_reasons": null,
                     "reference": "SVA-822866",
                     "created_at": "2026-01-12T09:46:19.214Z"
                 }
             },
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

Monitor the verification process until it becomes **Approved** or
**Rejected** by retrieving the verification status from the
``GET /v3/address_verifications`` endpoint.

The verification status indicates whether the submitted identity, address,
proofs, and supporting documents have been approved or rejected. If the
verification is rejected, the response includes a rejection reason that
explains what must be corrected before resubmitting.

.. note::
   A ``callback_url`` and ``callback_method`` can be configured for address
   verifications to receive HTTP callbacks when the verification status
   changes. |br|
   Callback events are sent when the verification is **approved** or
   **rejected**. The payload includes the verification ID, resource type
   (``address_verifications``), the current status, and a rejection reason when
   applicable.

   See :ref:`Callback configuration <callbacks_details_v33>` for more
   information.


.. |br| raw:: html

   <br />

.. _user-panel-api-examples-v33-available-dids-v33:
.. _api-examples-select-reserve-and-buy-available-dids-v33:

==========================================================
Select, Reserve & Buy Available DID Number(s)
==========================================================

This example shows the **end-to-end process for purchasing a specific DID number**
from DID inventory by selecting it from the list of currently available numbers
and reserving it before placing the order.

This flow is used when your account has access to ``GET /v3/available_dids`` and you
want to provide users with the option to browse and select a full DID number
from the list of available numbers. This is useful when a user wants to choose
a preferred number, such as a memorable, recognizable, or visually appealing
number, instead of ordering any available DID that matches only general
inventory criteria.

Unlike a regular DID purchase, where the order is created using only the
selected inventory criteria or ``sku.id``, purchasing a specific DID number
requires an additional reservation step before the order is placed.

Because the selected DID number is a specific inventory item, you must first
retrieve the list of available DID numbers and allow the user to select a
number.

After the number is selected, you must create a **DID reservation** before
placing the order. The reservation temporarily holds the selected number for
your account so that another customer cannot purchase it while the order is
being completed.

DID reservations expire after a limited time. Check the ``expire_at`` field in
the reservation response to determine when the reservation ends. If the selected
number is not purchased before the reservation expires, it is released back to inventory
and becomes available for other customers to purchase.

To buy a specific available number from DID inventory, follow these steps:

- :ref:`Step 1: Find the Country ID <user-panel-api-examples-v33-available-dids-v33_step1-v33>`
- :ref:`Step 2: Find the City ID <user-panel-api-examples-v33-available-dids-v33_step2-v33>`
- :ref:`Step 3: Retrieve DID Availability, Pricing, and Number Selection Status <user-panel-api-examples-v33-available-dids-v33_step3-v33>`
- :ref:`Step 4: Retrieve Available DIDs and Select a Number <user-panel-api-examples-v33-available-dids-v33_step4-v33>`
- :ref:`Step 5: Create a DID Reservation <user-panel-api-examples-v33-available-dids-v33_step5-v33>`
- :ref:`Step 6: Create the Order <user-panel-api-examples-v33-available-dids-v33_step6-v33>`

.. important::

   - The ``GET /v3/available_dids`` feature is not enabled by default. To enable it, contact sales@didww.com.
   - Number selection availability may vary by country and city.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-available-dids-v33_step1-v33:

Step 1: Find the Country ID
===========================

Retrieve the unique ID for the target country using the ``/countries`` endpoint.
From the response, save the ``country.id`` for use in later steps when
retrieving cities and DID Groups.

For more information, see the :ref:`/v3/countries <countries_v33_get_countries>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Find a country by ISO code*

      Use this approach when your application already knows the target country
      (for example, from a stored customer selection or a predefined checkout flow).
      Filter by ISO code to retrieve the matching country and its ``country.id``.

      .. http:example:: curl

         GET /v3/countries?filter[iso]=US HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

      .. note::
         This example filters by country ISO code. Adjust filters as needed to match
         your use case.

   .. tab-item:: *List countries available for purchase*

      Use this approach when building a **country dropdown** for end users.
      This request returns countries that have DID Groups in coverage and DID numbers
      available for purchase. You can sort the results by name and use each item’s
      ``attributes.name`` for display and ``id`` as the selected ``country.id`` for
      later steps.

      ``filter[is_available]`` is a boolean filter:

      - When ``true``, returns countries with DID numbers available for purchase.
      - When ``false``, returns countries that exist in coverage but currently have no
        DID numbers available for purchase.

      .. http:example:: curl

         GET /v3/countries?filter[is_available]=true&sort=name HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                     "type": "countries",
                     "attributes": {
                         "name": "Canada",
                         "prefix": "1",
                         "iso": "CA"
                     }
                 },
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2022-05-10"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-available-dids-v33_step2-v33:

Step 2: Find the City ID
========================

Depending on your application flow, selecting a city may be optional or required.
If your application allows users to narrow DID availability by **city** (for
example, when displaying a coverage list for local numbers), you should retrieve
and store the corresponding ``city.id``.

If your application does **not** differentiate availability by city (for example,
when listing all cities within a country or purchasing non–city-specific DIDs),
this step can be skipped.

Use the saved ``country.id`` to retrieve the city where the DID will be
purchased. From the response, save the ``city.id`` for use in later steps when
retrieving DID Groups that support number selection.

For more information, see the :ref:`/v3/cities <cities_v33_get_cities>` endpoint documentation.

.. http:example:: curl

    GET /v3/cities?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[name]=Los%20Angeles HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "f6672960-da2b-48a4-9f30-0065a8c54182",
                "type": "cities",
                "attributes": {
                    "name": "Los Angeles"
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2022-05-10"
        }
    }

.. note::

   This example filters the response by a single city name. Adjust the request
   parameters as needed to match your use case.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-available-dids-v33_step3-v33:

Step 3: Retrieve DID Availability, Pricing, and Number Selection Status
=======================================================================

Use the ``/did_groups`` endpoint, which is the **primary source for
building DID number coverage and availability** in your application.

It lets you present DID inventory for the selected location, including
available DID Groups, pricing, included channel options, and whether a DID
Group supports **number selection**.

When the DID Group returns ``available_dids_enabled = true``, your application
can offer number selection for that DID Group and retrieve specific available
numbers in the :ref:`next step <user-panel-api-examples-v33-available-dids-v33_step4-v33>`..

From the ``GET /did_groups`` response, save the following values as needed:

- ``did_group.id`` – Required to retrieve the list of available DID numbers in :ref:`Step 4 <user-panel-api-examples-v33-available-dids-v33_step4-v33>`.
- ``stock_keeping_units.id`` – Used to display pricing options, allow the user to choose the preferred channel amount, and :ref:`create the order <user-panel-api-examples-v33-available-dids-v33_step6-v33>`.

For more information, see the :ref:`/v3/did_groups <did_groups_v33_get_did_groups>` endpoint documentation.

.. http:example:: curl

    GET /v3/did_groups?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[city.id]=f6672960-da2b-48a4-9f30-0065a8c54182&filter[available_dids_enabled]=true HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
                "type": "did_groups",
                "attributes": {
                    "prefix": "213",
                    "features": [
                        "voice_in"
                    ],
                    "is_metered": false,
                    "area_name": "Los Angeles",
                    "allow_additional_channels": true
                },
                "meta": {
                    "available_dids_enabled": true,
                    "needs_registration": false,
                    "is_available": true,
                    "total_count": 2369
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2022-05-10"
        }
    }

.. important::

   Only DID Groups with ``available_dids_enabled = true`` support retrieving
   specific numbers using the ``/available_dids`` endpoint.

   - If the DID Group does **not** support this feature, use :ref:`Buy a DID Number from DID Inventory <user-panel-api-examples-v33-did-group-v33>`.
   - If the DID requires **verification** before activation, follow :ref:`Buy a DID Number that Requires Verification <user-panel-api-examples-v33-verification-v33>`.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-available-dids-v33_step4-v33:

Step 4: Retrieve Available DIDs and Select a Number
=====================================================

Use the ``/available_dids`` endpoint to retrieve specific DID numbers that are currently available for purchase.

Call ``GET /v3/available_dids`` with ``include=did_group.stock_keeping_units`` to
retrieve available numbers together with their pricing options.

You may also filter by ``[filter]did_group.id`` to narrow the results to a specific DID
Group selected in :ref:`Step 3 <user-panel-api-examples-v33-available-dids-v33_step3-v33>`.

From the ``GET /available_dids`` response, save the following values:

- ``available_dids.id`` – Required to create a DID reservation for the selected number in :ref:`Step 5 <user-panel-api-examples-v33-available-dids-v33_step5-v33>`.
- ``stock_keeping_units.id`` – Required later when creating the order for the reserved DID number.

For more information, see the :ref:`/v3/available_dids <available_dids_v33_get_available_dids>` endpoint documentation.

.. http:example:: curl

    GET /v3/available_dids?include=did_group.stock_keeping_units&filter[did_group.id]=7fa8ba67-0622-4ac3-8ade-4aadf92566c5 HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
      "data": [
        {
          "id": "ea9884ee-887e-4c20-befb-286db7cf55da",
          "type": "available_dids",
          "attributes": {
            "number": "12132933575"
          },
          "relationships": {
            "did_group": {
              "links": {
                "self": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/relationships/did_group",
                "related": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/did_group"
              },
              "data": {
                "type": "did_groups",
                "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5"
              }
            },
            "nanpa_prefix": {
              "links": {
                "self": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/relationships/nanpa_prefix",
                "related": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/nanpa_prefix"
              }
            }
          }
        }
      ],
      "included": [
        {
          "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
          "type": "did_groups",
          "attributes": {
            "prefix": "213",
            "features": [
              "voice_in"
            ],
            "is_metered": false,
            "area_name": "Los Angeles",
            "allow_additional_channels": true,
            "service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
          },
          "relationships": {
            "country": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/country",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/country"
              }
            },
            "city": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/city",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/city"
              }
            },
            "did_group_type": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/did_group_type",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/did_group_type"
              }
            },
            "region": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/region",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/region"
              }
            },
            "stock_keeping_units": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/stock_keeping_units",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/stock_keeping_units"
              },
              "data": [
                {
                  "type": "stock_keeping_units",
                  "id": "72f3a8a8-cd1e-41fc-8d4c-829e4fb8cdea"
                },
                {
                  "type": "stock_keeping_units",
                  "id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393"
                }
              ]
            },
            "requirement": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/requirement",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/requirement"
              }
            }
          },
          "meta": {
            "available_dids_enabled": true,
            "needs_registration": false,
            "is_available": true,
            "total_count": 2371
          }
        },
        {
          "id": "72f3a8a8-cd1e-41fc-8d4c-829e4fb8cdea",
          "type": "stock_keeping_units",
          "attributes": {
            "setup_price": "0.0",
            "monthly_price": "0.09",
            "channels_included_count": 0
          }
        },
        {
          "id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393",
          "type": "stock_keeping_units",
          "attributes": {
            "setup_price": "4.0",
            "monthly_price": "4.0",
            "channels_included_count": 2
          }
        }
      ],
      "meta": {
        "total_count": 2368,
        "api_version": "2022-05-10"
      }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-available-dids-v33_step5-v33:

Step 5: Create a DID Reservation
================================

Reserve the selected number before creating the order. This temporarily locks
the DID for your account and prevents other users from purchasing it while the
order is being created.

Create the reservation using the ``available_dids.id`` value obtained in the
previous step.

The reservation remains active until the time shown in ``expire_at``. If you
need to extend the reservation, resend the ``POST /v3/did_reservations``
request for the same available DID before the reservation expires.

From the response, save the ``did_reservations.id`` and check ``expire_at`` to
see when the reservation expires.

For more information, see :ref:`Create DID Reservation <create_did_reservation_v33>`.

.. http:example:: curl

    POST /v3/did_reservations HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "did_reservations",
        "attributes": {
          "description": "Reserved for customer"
        },
        "relationships": {
          "available_did": {
            "data": {
              "type": "available_dids",
              "id": "4048d28a-6cab-46c9-98e9-d69d2466c131"
            }
          }
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6",
            "type": "did_reservations",
            "attributes": {
                "expire_at": "2026-03-19T11:38:15.074Z",
                "created_at": "2026-03-19T11:37:15.079Z",
                "description": "Reserved for customer"
            },
            "relationships": {
                "available_did": {
                    "data": {
                        "type": "available_dids",
                        "id": "4048d28a-6cab-46c9-98e9-d69d2466c131"
                    }
                }
            }
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-v33-available-dids-v33_step6-v33:

Step 6: Create the Order
========================

Create the order using the selected ``stock_keeping_units.id`` and the saved
``did_reservations.id``.

This ensures the order is created for the **exact reserved DID number** selected
in the previous steps.

For more information, see the :ref:`/v3/orders <orders_v33_create_order>` endpoint documentation.

.. note::

   - A positive prepaid balance is required to successfully create the order.
   - For simplicity, detailed item attributes are not included in this response example.

.. http:example:: curl

    POST /v3/orders HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "orders",
        "attributes": {
          "allow_back_ordering": false,
          "items": [
            {
              "type": "did_order_items",
              "attributes": {
                "sku_id": "7a2d041e-0f08-4f61-a59b-f2eca3af23f9",
                "did_reservation_id": "af7677ea-819c-4fc0-b0a6-588be5d434b2"
              }
            }
          ]
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "0f2dd6a8-7539-444a-b7c1-e89b3fe7d170",
            "type": "orders",
            "attributes": {
                "amount": "8.0",
                "status": "Pending",
                "created_at": "2026-03-19T12:08:23.567Z",
                "description": "DID",
                "reference": "ZME-571778",
                "items": [
                    {
                        "type": "did_order_items",
                        "attributes": {
                            "qty": 1,
                            "nrc": "4.0",
                            "mrc": "4.0",
                            "prorated_mrc": false,
                            "billed_from": null,
                            "billed_to": null,
                            "setup_price": "4.0",
                            "monthly_price": "4.0",
                            "did_group_id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5"
                        }
                    }
                ],
                "callback_method": null,
                "callback_url": null
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }



.. |br| raw:: html

    <br/>

.. _user-panel-api-examples-v33:

=================
Use Case Examples
=================

Follow step-by-step examples for common DID number purchase flows. Use these
examples when you need to buy numbers based on different selection methods,
such as location, prefix, verification requirements, or specific number
availability. Each use case shows which API endpoints to call, which values to
save, and how to move through the ordering flow.

.. note::

   These examples apply to API version **2022-05-10**.
   For the latest version, see :ref:`2026-04-16 (latest) <user-panel-api-examples>`.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item-card:: **Buy DID Number(s) that Requires Verification**
      :link: api-examples-buy-a-did-that-requires-verification-v33
      :link-type: ref
      :text-align: center

      Learn how to purchase and verify a DID number when regulatory requirements apply.

   .. grid-item-card:: **Buy Available DID Number(s)**
      :link: api-examples-buy-available-dids-v33
      :link-type: ref
      :text-align: center

      Learn how to filter DID inventory and order a matching number using API v3.

   .. grid-item-card:: **Select, Reserve & Buy Available DID Number(s)**
      :link: api-examples-select-reserve-and-buy-available-dids-v33
      :link-type: ref
      :text-align: center

      Learn how to retrieve available DID numbers, reserve a selected number, and complete the purchase using API v3.

.. toctree::
  :maxdepth: 1
  :hidden:

    Buy DID Number(s) that Requires Verification <buy-dids-with-verification.rst>
    Buy Available DID Number(s) <buy-dids.rst>
    Select, Reserve & Buy Available DID Number(s) <buy-reserved-dids.rst>



=============
Create Export
=============

.. attention::

    Please note that the Inbound/Outbound CDR export is available for current + 2 last months.

Creates a single Export. DIDWW performs deletion of CDR Export in 1 month after completion.

Forming Request
===============

Request Method: ``POST``

Request Path: ``/v3/exports``

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "filters", ":ref:`CDR Export Filters Object <export_filters_object_v33>`", "False", "Yes", "Filters"
   "callback_url", "``string``", "True", "No", "The HTTP or HTTPS endpoint to where events related to export will be delivered."
   "callback_method", "``string``", "True", "No", "The HTTP Method used for export events. **POST**, **GET** are supported methods."

See :ref:`Callback details <callbacks_details_v33>` for information about **callback_url** and **callback_method**.

Export Type Attributes:

.. tabs::

   .. tab:: cdr_in

	.. csv-table::
		:header: "Name", "Type", "Is Required?", "Description"

		"year", "``integer``", "Yes", "Year of the CDR timestamp."
		"month", "``integer``", "Yes", "Month of the CDR timestamp."
		"did_number", "``string``", "No", "CDR export for a specified DID number. If the 'did_number' parameter is not used, CDRs are exported for all owned DID numbers."

   .. tab:: cdr_out

	.. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "year", "``integer``", "Yes", "Year of the CDR timestamp."
	   "month", "``integer``", "Yes", "Month of the CDR timestamp."
	   "day", "``integer``", "Yes", "Day of the CDR timestamp."
	   "voice_out_trunk.id", "``string``", "No", "ID of voice out trunk."

Example
=======

.. tabs::

    .. tab:: Inbound CDR Example

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "export_type": "cdr_in",
                  "filters": {
                    "year": "2021",
                    "month": "12",
                    "did_number": "123456789"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "33bdfff7-4de3-4c58-8c90-b99930fb984a",
                "type": "exports",
                "attributes": {
                  "status": "Pending",
                  "created_at": "2021-12-16T06:39:44.465Z",
                  "url": null,
                  "callback_url": null,
                  "callback_method": null,
                  "export_type": "cdr_in"
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

    .. tab:: Inbound CDR Example with Callback

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "GET",
                  "export_type": "cdr_in",
                  "filters": {
                    "year": "2021",
                    "month": "12",
                    "did_number": "123456789"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "d4f37476-8ece-4add-bbcb-cc72a7908fe2",
                "type": "exports",
                "attributes": {
                  "status": "Pending",
                  "created_at": "2021-12-16T06:54:30.122Z",
                  "url": null,
                  "callback_url": "http://example.com",
                  "callback_method": "GET",
                  "export_type": "cdr_in"
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

    .. tab:: Outbound CDR Example

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "export_type": "cdr_out",
                  "filters": {
                    "year": "2021",
                    "month": "12",
                    "day": "12",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "88a29a27-11fe-4db0-a508-eca1d7cf0b68",
                "type": "exports",
                "attributes": {
                  "status": "Pending",
                  "created_at": "2021-12-21T07:37:13.085Z",
                  "url": null,
                  "callback_url": null,
                  "callback_method": null,
                  "export_type": "cdr_out"
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

    .. tab:: Outbound CDR Example with Callback

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "export_type": "cdr_out",
                  "callback_url": "http://example.com",
                  "callback_method": "GET",
                  "filters": {
                    "year": "2021",
                    "month": "12",
                    "day": "12",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "67e4f27f-d5eb-4b80-8924-39486aee6ed4",
                "type": "exports",
                "attributes": {
                  "status": "Pending",
                  "created_at": "2021-12-21T07:42:02.546Z",
                  "url": null,
                  "callback_url": "http://example.com",
                  "callback_method": "GET",
                  "export_type": "cdr_out"
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

    .. tab:: Outbound CDR Month Export

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                    "export_type": "cdr_out",
                  "filters": {
                    "year": "2021",
                    "month": "12",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
               "data":    {
                  "id": "88a29a27-11fe-4db0-a508-eca1d7cf0b68",
                  "type": "exports",
                  "attributes":       {
                     "status": "Pending",
                     "created_at": "2021-12-21T07:37:13.085Z",
                     "url": null,
                     "callback_url": null,
                     "callback_method": null,
                     "export_type": "cdr_out"
                  }
               },
               "meta": {"api_version": "2022-05-10"}
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "422", "No", ":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"

.. _export_filters_object_v33:

=====================
Export Filters Object
=====================

Export Filters keys.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Nullable", "Description"

   "year", "``integer``", "False", "Year of the CDR timestamp."
   "month", "``integer``", "False", "Month of the CDR timestamp."
   "day", "``integer``", "False", "Day of the CDR timestamp."
   "did_number", "``string``", "False", "Filters CDRs by DID number."
   "voice_out_trunk.id", "``string``", "False", "Filters CDRs by Outbound Trunk."

.. _cdr_export_filters_object_v33:

=============
Export Object
=============

Export attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Nullable", "Description"

   "status", "``string``", "False", "Status can be “Pending”, “Processing”, or “Completed”."
   "created_at", "``DateTime``", "False", "Timestamp when export request was created."
   "url", "``string``", "True", "The URL of the CSV file for downloading. Available only when status is “Completed”."
   "callback_url", "``string``", "True", "The HTTP or HTTPS endpoint to where events related to export will be delivered."
   "callback_method", "``string``", "True", "The HTTP Method used for export events. **POST**, **GET** are supported methods."
   "export_type", "``string``", "False", "Defines CDR export type."


======================
Get CSV File of Export
======================

Returns a single .csv.gz file for corresponding Export.

.. attention::

    | Please note that the file is available for Download Only! It can not be read as in previous versions due to .csv file being Archived as .gz format archive for compression of space.
    | To receive the CDR export file, a query should be sent to /v3/exports/{filename}.csv.gz, and the {filename} can be obtained from the response of :ref:`Get Exports <get_exports_v33>` URL attribute or :ref:`Get Export <get_export_v33>` following by export ID.

Forming Request
===============

Request Method: ``GET``

Request Path: ``/v3/exports/``

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filename", "``string``", "Yes", "Unique filename of completed CDR Export."
   
Example
=======

.. http:example:: curl

	GET /v3/exports/a4f6b765-f20c-45c7-98d2-80c2f3a41517.csv.gz HTTP/1.1
	Host: api.didww.com
	Api-Key: [API token]
	

	
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", "Not Found (without body)"
   "401", "No", ":ref:`Unauthorized <api_key>`"

.. _get_export_v33:

==========
Get Export
==========

Returns a single Export.

Forming Request
===============

Request Method: ``GET``

Request Path: ``/v3/exports/``

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of CDR Export."

Example
=======

.. http:example:: curl

	GET /v3/exports/77ebb57f-7b01-4178-bc84-9d1a8d2ae850 HTTP/1.1
	Host: api.didww.com
	Content-Type: application/vnd.api+json
	Accept: application/vnd.api+json
	Api-Key: [API token]
	
	
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	
        {
           "data":    {
              "id": "77ebb57f-7b01-4178-bc84-9d1a8d2ae850",
              "type": "exports",
              "attributes":       {
                 "status": "Completed",
                 "created_at": "2022-02-23T17:21:32.591Z",
                 "url": "https://api.didww.com/v3/exports/baf6d4cf-e6e8-4920-b15f-b2abc6cb4a7d.csv.gz",
                 "callback_url": "http://example.com",
                 "callback_method": "POST",
                 "export_type": "cdr_out"
              }
           },
           "meta": {"api_version": "2022-05-10"}
        }
	
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _get_exports_v33:

===========
Get Exports
===========

Returns a collection of Exports.

Forming Request
===============

Request Method: ``GET``

Request Path: ``/v3/exports``

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Sorting
-------

.. csv-table::
   :header: "Value", "Description"

   "status", "The ``status`` field."
   "created_at", "The ``created_at`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Description"

   "filters", "The ``filters`` attribute."
   "status", "The ``status`` attribute."
   "created_at", "The ``created_at`` attribute."
   "url", "The ``url`` attribute."
   "callback_url", "The ``callback_url`` attribute."
   "callback_method", "The ``callback_method`` attribute."

Example
=======

.. http:example:: curl

	GET /v3/exports HTTP/1.1
	Host: api.didww.com
	Content-Type: application/vnd.api+json
	Accept: application/vnd.api+json
	Api-Key: [API token]
	
	
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	
        {
          "data": [
            {
              "id": "6fee87b1-5f86-470c-80ca-9c3922653de9",
              "type": "exports",
              "attributes": {
                "status": "Processing",
                "created_at": "2021-12-13T20:02:07.798Z",
                "url": null,
                "callback_url": null,
                "callback_method": null,
                "export_type": "cdr_in"
              }
            },
            {
              "id": "33bdfff7-4de3-4c58-8c90-b99930fb984a",
              "type": "exports",
              "attributes": {
                "status": "Processing",
                "created_at": "2021-12-16T06:39:44.465Z",
                "url": null,
                "callback_url": null,
                "callback_method": null,
                "export_type": "cdr_in"
              }
            },
            {
              "id": "d4f37476-8ece-4add-bbcb-cc72a7908fe2",
              "type": "exports",
              "attributes": {
                "status": "Processing",
                "created_at": "2021-12-16T06:54:30.122Z",
                "url": null,
                "callback_url": "http://example.com",
                "callback_method": "GET",
                "export_type": "cdr_in"
              }
            },
            {
              "id": "88a29a27-11fe-4db0-a508-eca1d7cf0b68",
              "type": "exports",
              "attributes": {
                "status": "Completed",
                "created_at": "2021-12-21T07:37:13.085Z",
                "url": "https://api.didww.com/v3/exports/a8bf7c0e-0c08-44ca-b0e2-db34a1d2006a.csv.gz",
                "callback_url": null,
                "callback_method": null,
                "export_type": "cdr_out"
              }
            },
            {
              "id": "67e4f27f-d5eb-4b80-8924-39486aee6ed4",
              "type": "exports",
              "attributes": {
                "status": "Completed",
                "created_at": "2021-12-21T07:42:02.546Z",
                "url": "https://api.didww.com/v3/exports/b15d6a4b-3c99-4bee-af6b-f5f37ce30511.csv.gz",
                "callback_url": "http://example.com",
                "callback_method": "GET",
                "export_type": "cdr_out"
              }
            },
            {
              "id": "77165c85-0a37-43d1-b3f8-c76d2eb50315",
              "type": "exports",
              "attributes": {
                "status": "Completed",
                "created_at": "2021-12-21T07:54:35.789Z",
                "url": "https://api.didww.com/v3/exports/94593896-818a-4a00-b89b-e4d825f4c0d5.csv.gz",
                "callback_url": "http://example.com",
                "callback_method": "GET",
                "export_type": "cdr_out"
              }
            }
          ],
          "meta": {
            "total_records": 6,
            "api_version": "2022-05-10"
          },
          "links": {
            "first": "https://api.didww.com/v3/exports?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/exports?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
	
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"

.. _export_v33:

======
Export
======

DIDWW API v3 Export functionality allows to create and download non-realtime .csv files with Call Detail Records (CDRs). Deletion of created CDR Export is done in 1 month after completion.

.. note::
   Real-time CDR mechanism for repetitive CDRs data transfer is available :ref:`here <cdr_streaming>`.

Supported methods: ``GET``, ``POST``.

.. toctree:: 
  :titlesonly:
  	
  get-export.rst
  get-exports.rst
  get-csv-file-of-export.rst
  create-export.rst
  export-object.rst
  export-filters-object.rst



.. _resources_summary_v33:

.. _didww_api_20220510:

:orphan:

=================================
API Resources Summary v2022-05-10
=================================

.. note::

   You are viewing an older version of the API reference.

   For the latest version guidance, see the :doc:`latest API3 documentation <../2026-04-16/index>`.

.. raw:: html

    <div class="postman-run-button"
    data-postman-action="collection/fork"
    data-postman-var-1="23329000-7178161d-b951-44a7-a75f-9dcd15b970f5"
    data-postman-collection-url="entityId=23329000-7178161d-b951-44a7-a75f-9dcd15b970f5&entityType=collection&workspaceId=c7e9c67d-ac71-4c91-a5ef-b12f6619f415"
    data-postman-param="env%5BDIDWW%20Sandbox%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoieW91ckRpZHd3QXBpS2V5IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoieW91ckRpZHd3QXBpS2V5Iiwic2Vzc2lvbkluZGV4IjoxfV0=">
    </div>
    <p></p>
    <script type="text/javascript">
    (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
    (n = o.createElement("script")),
    (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
    }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
    </script>

The DIDWW API allows you to perform an extensive set of actions such as querying the DID coverage and inventory, ordering and configuring phone numbers and services, setting capacity and creating SIP trunks by using the following methods:


 * **GET** - Fetch data, where the data can be a collection or resources or an individual resource
 * **POST** - Create a new resource
 * **PATCH** - Update an existing resource
 * **DELETE** - Remove an existing resource


.. csv-table::
   :header: "API Call", "Method/s", "Details"

   ":ref:`balance <balance_v33>`","GET", "Returns the prepaid balance as well as the available credit on the account."
   ":ref:`cities <cities_v33>`", "GET", "Returns a list of cities included in the current DIDWW inventory, or returns the details of a specific city."
   ":ref:`countries <countries_v33>`","GET","Returns a list of countries included in the current DIDWW inventory, or return the details of a specific country."
   ":ref:`dids <dids_v33>`","GET, PATCH","Returns a list of all of the DIDs owned by an account or the details for a single DID, or modify the settings for a single DID owned by an account."
   ":ref:`did_groups <did_groups_v33>`","GET","Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code."
   ":ref:`did_group_types <did_group_types_v33>`", "GET","Returns a list of the various types of DIDs supported by DIDWW (for example, mobile, toll-free, SMS)."
   ":ref:`capacity_pools <capacity_pools_v33>`","GET, PATCH","Returns a list of the Capacity Pools which include information about channels quantity, supported Countries, Shared Capacity Groups."
   ":ref:`shared_capacity_groups <shared_capacity_groups_v33>`","GET, POST, PATCH, DELETE","Returns a list of the Capacity Groups assigned to Capacity Pool."
   ":ref:`export <export_v33>`","GET, POST","Returns a call detail records (CDRs) or create a CDR for export."
   ":ref:`orders <orders_v33>`","GET, POST, DELETE","Returns a list of the orders previously placed in this account, create a new order, or delete an order."
   ":ref:`regions <regions_v33>`","GET","Returns a list of regions (for example, states within the USA) included in the current DIDWW inventory."
   ":ref:`voice_in_trunks <voice_in_trunks_v33>`","GET, POST, PATCH, DELETE","Returns a list of all of the voice in trunks configured by this account, create a new trunk, modify the settings of an existing trunk, or delete a trunk."
   ":ref:`voice_out_trunks <voice_out_trunks_v33>`","GET, POST, PATCH, DELETE","Returns a list of all voice out trunks configured by this account, create a new trunk, modify the existing trunk, or delete a trunk."
   ":ref:`voice_in_trunk_groups <voice_in_trunk_groups_v33>`","GET, POST, PATCH, DELETE","Returns the details of a voice in trunk group, create a new trunk group, modify trunk group settings, or delete a trunk group."
   ":ref:`available_dids <available_dids_v33>`","GET","Returns a list of available DID numbers in the current DIDWW coverage."
   ":ref:`did_reservation <did_reservation_v33>`","GET, POST, DELETE","Returns a list or a single DID reservations for the account."
   ":ref:`address_verifications <address_verifications_v33>`","GET, POST","Returns a list or a single address verifications for the account."
   ":ref:`addresses <addresses_v33>`","GET, POST, PATCH, DELETE","Returns the details of a address, create a new address, modify address settings, or delete an address."
   ":ref:`encrypted_files <encrypted_files_v33>`","GET, POST, DELETE","Returns the details of a encrypted file, create a new encrypted file, or delete an encrypted file."
   ":ref:`identities <identities_v33>`","GET, POST, PATCH, DELETE","Returns the details of a identity, create a new identity, modify identity settings, or delete an identity."
   ":ref:`permanent_supporting_documents <permanent_documents_v33>`","POST, DELETE","Create a new permanent supporting document, or delete a permanent supporting document."
   ":ref:`proof_types <proof_types_v33>`","GET","Returns a list or a single proof_types for the account."
   ":ref:`proofs <proofs_v33>`","POST, DELETE","Create a new proof, or delete a proof."
   ":ref:`requirements <requirements_v33>`","GET","Returns a list or a single requirements for the account."
   ":ref:`supporting_document_templates <supporting_document_template_v33>`","GET","Returns a list or a single supporting document templates for the account."
   ":ref:`areas <areas_v33>`","GET","Returns a list or a single regulatory area."
   ":ref:`nanpa_prefixes <nanpa_prefixes_v33>`","GET","Returns a list NANPA prefixes or a single NANPA prefix."


.. toctree::
  :hidden:
  :maxdepth: 1
  :caption: API Documentation v2022-05-10

  Overview <overview>
  Use Case Examples <examples/index.rst>
  coverage-resources/index.rst
  inventory-resources/index.rst
  regulation-resources/index.rst
  export/index.rst
  common-definitions/index.rst
  callbacks-details.rst
  changelog.rst

:orphan:

=================================
API Resources Summary v2022-05-10
=================================

.. note::

   You are viewing an older version of the API reference.

   For the latest version guidance, see the :doc:`latest API3 documentation <../2026-04-16/index>`.

.. raw:: html

    <div class="postman-run-button"
    data-postman-action="collection/fork"
    data-postman-var-1="23329000-7178161d-b951-44a7-a75f-9dcd15b970f5"
    data-postman-collection-url="entityId=23329000-7178161d-b951-44a7-a75f-9dcd15b970f5&entityType=collection&workspaceId=c7e9c67d-ac71-4c91-a5ef-b12f6619f415"
    data-postman-param="env%5BDIDWW%20Sandbox%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoieW91ckRpZHd3QXBpS2V5IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoieW91ckRpZHd3QXBpS2V5Iiwic2Vzc2lvbkluZGV4IjoxfV0=">
    </div>
    <p></p>
    <script type="text/javascript">
    (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
    (n = o.createElement("script")),
    (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
    }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
    </script>

The DIDWW API allows you to perform an extensive set of actions such as querying the DID coverage and inventory, ordering and configuring phone numbers and services, setting capacity and creating SIP trunks by using the following methods:


 * **GET** - Fetch data, where the data can be a collection or resources or an individual resource
 * **POST** - Create a new resource
 * **PATCH** - Update an existing resource
 * **DELETE** - Remove an existing resource


.. csv-table::
   :header: "API Call", "Method/s", "Details"

   ":ref:`balance <balance_v33>`","GET", "Returns the prepaid balance as well as the available credit on the account."
   ":ref:`cities <cities_v33>`", "GET", "Returns a list of cities included in the current DIDWW inventory, or returns the details of a specific city."
   ":ref:`countries <countries_v33>`","GET","Returns a list of countries included in the current DIDWW inventory, or return the details of a specific country."
   ":ref:`dids <dids_v33>`","GET, PATCH","Returns a list of all of the DIDs owned by an account or the details for a single DID, or modify the settings for a single DID owned by an account."
   ":ref:`did_groups <did_groups_v33>`","GET","Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code."
   ":ref:`did_group_types <did_group_types_v33>`", "GET","Returns a list of the various types of DIDs supported by DIDWW (for example, mobile, toll-free, SMS)."
   ":ref:`capacity_pools <capacity_pools_v33>`","GET, PATCH","Returns a list of the Capacity Pools which include information about channels quantity, supported Countries, Shared Capacity Groups."
   ":ref:`shared_capacity_groups <shared_capacity_groups_v33>`","GET, POST, PATCH, DELETE","Returns a list of the Capacity Groups assigned to Capacity Pool."
   ":ref:`export <export_v33>`","GET, POST","Returns a call detail records (CDRs) or create a CDR for export."
   ":ref:`orders <orders_v33>`","GET, POST, DELETE","Returns a list of the orders previously placed in this account, create a new order, or delete an order."
   ":ref:`regions <regions_v33>`","GET","Returns a list of regions (for example, states within the USA) included in the current DIDWW inventory."
   ":ref:`voice_in_trunks <voice_in_trunks_v33>`","GET, POST, PATCH, DELETE","Returns a list of all of the voice in trunks configured by this account, create a new trunk, modify the settings of an existing trunk, or delete a trunk."
   ":ref:`voice_out_trunks <voice_out_trunks_v33>`","GET, POST, PATCH, DELETE","Returns a list of all voice out trunks configured by this account, create a new trunk, modify the existing trunk, or delete a trunk."
   ":ref:`voice_in_trunk_groups <voice_in_trunk_groups_v33>`","GET, POST, PATCH, DELETE","Returns the details of a voice in trunk group, create a new trunk group, modify trunk group settings, or delete a trunk group."
   ":ref:`available_dids <available_dids_v33>`","GET","Returns a list of available DID numbers in the current DIDWW coverage."
   ":ref:`did_reservation <did_reservation_v33>`","GET, POST, DELETE","Returns a list or a single DID reservations for the account."
   ":ref:`address_verifications <address_verifications_v33>`","GET, POST","Returns a list or a single address verifications for the account."
   ":ref:`addresses <addresses_v33>`","GET, POST, PATCH, DELETE","Returns the details of a address, create a new address, modify address settings, or delete an address."
   ":ref:`encrypted_files <encrypted_files_v33>`","GET, POST, DELETE","Returns the details of a encrypted file, create a new encrypted file, or delete an encrypted file."
   ":ref:`identities <identities_v33>`","GET, POST, PATCH, DELETE","Returns the details of a identity, create a new identity, modify identity settings, or delete an identity."
   ":ref:`permanent_supporting_documents <permanent_documents_v33>`","POST, DELETE","Create a new permanent supporting document, or delete a permanent supporting document."
   ":ref:`proof_types <proof_types_v33>`","GET","Returns a list or a single proof_types for the account."
   ":ref:`proofs <proofs_v33>`","POST, DELETE","Create a new proof, or delete a proof."
   ":ref:`requirements <requirements_v33>`","GET","Returns a list or a single requirements for the account."
   ":ref:`supporting_document_templates <supporting_document_template_v33>`","GET","Returns a list or a single supporting document templates for the account."
   ":ref:`areas <areas_v33>`","GET","Returns a list or a single regulatory area."
   ":ref:`nanpa_prefixes <nanpa_prefixes_v33>`","GET","Returns a list NANPA prefixes or a single NANPA prefix."


.. |br| raw:: html

   <br />

===================
Inventory Resources
===================

The following requests allows you to retrieve resources and services related to your DIDWW account.

 .. toctree::
 	:maxdepth: 2

 	balance/index
 	order/index
 	did/index
 	voice-in-trunks/index
 	voice-in-trunk-groups/index
 	voice-out-trunks/index
 	capacity-pool/index
 	shared-capacity-group/index


.. |br| raw:: html

   <br />

.. _balance_v33:

=======
Balance
=======

Returns the prepaid balance as well as the available credit on your account. 

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-balance.rst
  balance-object.rst
  
  



===========
Get Balance
===========

Returns the prepaid balance as well as the available credit on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/balance``

Example
=======

.. http:example:: curl

    GET /v3/balance HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
      "data": {
        "id": "94441ce5-86fa-47bd-8ce7-b5e267d0603a",
        "type": "balances",
        "attributes": {
          "balance": "50.00",
          "credit": "10.00",
          "total_balance": "60.00"
        }
      }
    }
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _balance_object_v33:

==============
Balance Object
==============

JSONAPI object that represents the user’s balance and has following attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"
   
   "balance","``string``","Prepaid balance" 
   "credit","``string``","Available credit   " 
   "total_balance","``string``","The net balance (balance+credit)." 

   
   
   
   
   

   



.. |br| raw:: html

   <br />

.. _orders_v33:

======
Orders
======

Returns a single or a list of orders placed in this account. Allows you to create a new order or delete an existing one. 

Supported methods: ``GET``, ``POST``, ``DELETE``. 

.. toctree::
  :maxdepth: 1
  
  get-order.rst
  get-orders.rst
  create-order.rst
  cancel-order.rst
  order-object.rst
  
  
  



=========
Get Order
=========

Returns a single Order.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/orders/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Order."

Example
=======

.. http:example:: curl

    GET /v3/orders/f1d36d01-ce9d-4bec-a307-52aa405d20ae HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "ebf12efb-3cd5-4c1a-a044-284749259a94",
            "type": "orders",
            "attributes": {
                "amount": "0.35",
                "status": "Completed",
                "created_at": "2021-03-15T05:45:02.141Z",
                "description": "DID",
                "reference": "CZF-274626",
                "items": [
                    {
                        "type": "did_order_items",
                        "attributes": {
                            "qty": 1,
                            "nrc": "0.0",
                            "mrc": "0.35",
                            "prorated_mrc": false,
                            "billed_from": "2021-03-15",
                            "billed_to": "2021-04-15",
                            "setup_price": "0.0",
                            "monthly_price": "0.35",
                            "did_group_id": "0a265a8c-50fc-4ab3-ae16-9811bc17c241"
                        }
                    }
                ],
                "callback_method": null,
                "callback_url": null
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




============
Cancel Order
============

Cancels Pending Order on DIDWW side. It is used to Cancel an Order that has not yet been Completed and is in Pending status. It will also remove DID numbers in this Order.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/orders/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id","``string``", "Yes", "Unique ID identifier of the Order."

Example
=======

.. http:example:: curl

    DELETE /v3/orders/1b3ac4b7-315c-4416-afb8-24d8e7c4ec0c HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _orders_v33_create_order:

.. |br| raw:: html

   <br />

============
Create Order
============

Creates a new DID Order to purchase phone numbers (DIDs) based on availability, reservations, or predefined stock-keeping units (SKUs). This request allows to order specific available DIDs, reserve numbers from a particular region, or request multiple DIDs in bulk.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/orders``

Body
====

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "allow_back_ordering", "``boolean``", "No", "Specifies whether back-ordering is allowed. If true, the system allows ordering DIDs that are not currently available. If false, only currently available DIDs can be ordered."
   "items", "``Array<CreateOrderItem>``", "Yes", "Array of items to be ordered. Each item must contain one of the valid order item attributes."
   "callback_url", "``string``", "No", "The HTTP or HTTPS endpoint to which order related events will be delivered."
   "callback_method", "``string``", "No", "The HTTP method used for order events. Supported methods: POST, GET."

.. note::
  - allow_back_ordering = ``true``: Proceeds with the order when items are not in stock.
  - allow_back_ordering = ``false``: Does not proceed with the order when items are not in stock.

See :ref:`Callback details <callbacks_details_v33>` for information about **callback_url** and **callback_method**.

Order Item
----------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "type","``string``","No","Item object type: ``did_order_items`` for DIDs and ``capacity_order_items`` for Channels."
   "attributes","One of :ref:`DID Order Item Attributes <20210322_did_order_item_attributes_v33>`, |br| :ref:`Capacity Order Item Attributes <20210322_capacity_order_item_attributes_v33>`","No","Order Item Attributes object."

.. _20210322_did_order_item_attributes_v33:

.. _20210322_capacity_order_item_attributes_v33:

Order Item Attributes
---------------------

.. tabs::

   .. tab:: DID

		.. csv-table::
		   :header: "Name", "Type", "Is Required?", "Description"

		   "sku_id", "``string``", "Yes", "The Stock Keeping Unit (SKU) ID representing the DID product being ordered. Must be used with one of the optional parameters: ``qty``, ``available_did_id`` or ``did_reservation_id``."
		   "qty", "``integer``", "Conditional", "The quantity of DIDs to be ordered. Required when ordering multiple DIDs in bulk. Not needed if ordering a specific available_did_id or did_reservation_id."
		   "did_reservation_id", "``string``", "No", "The ID of a previously reserved DID. Use this to complete the purchase of a reserved DID."
		   "nanpa_prefix_id", "``string``", "No", "The ID representing a North American Numbering Plan (NANPA) prefix (NPA-NXX group). Used for ordering numbers from a specific region."
		   "billing_cycles_count", "``integer``", "No", "The number of billing cycles that this DID will automatically renew before expiration."
		   "available_did_id", "``string``", "No", "The ID of a specific available DID to be ordered. Used when ordering a known available number."
		   "prorate_days_qty", "``integer``", "No", "The number of service days to be included in the order, if prorated billing is applicable."

   .. tab:: Capacity

		.. csv-table::
		   :header: "Name", "Type", "Is Required?", "Description"

		   "qty", "``integer``", "No", "Quantity of DIDs."
		   "capacity_pool_id", "``string``", "Yes", "Capacity Pool ID."

.. attention::
    Please note that the ``prorate_days_qty`` attribute will be ignored if prorated billing is not enabled for your DIDWW account. To enable this billing option, please contact the Sales department via email at `sales@didww.com <mailto:sales@didww.com>`_.

Examples
========

.. tabs::

   .. tab:: Simple request

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": true,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "sku_id": "a78bb6d8-b05e-4e12-afe6-ad84ac979088"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "9eeaab6c-b758-41b8-af86-8978a86603a2",
            "type": "orders",
            "attributes": {
              "reference": "FZH-374899",
              "amount": "79.2",
              "status": "Pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 15,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "d01704b0-6522-47d5-8865-3398c417ed1d"
                  }
                }
              ]
            }
          }
        }

   .. tab:: allow_back_ordering = false

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 15,
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "79.2",
              "status": "Pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 15,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }

   .. tab:: Available DID ID

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "available_did_id": "7f44285d-20ef-4773-953f-ba012adafed3",
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "10.0",
              "status": "Pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }

   .. tab:: DID Reservation ID

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "did_reservation_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3",
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "10.0",
              "status": "Pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }
        
   .. tab:: Callback Example

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": true,
              "callback_url": "http://example.com",
              "callback_method": "GET",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "76b20d6b-f9a8-47bf-8715-bc5fbfd59f55",
                "type": "orders",
                "attributes": {
                    "amount": "0.5",
                    "status": "Pending",
                    "created_at": "2021-09-06T16:54:28.659Z",
                    "description": "DID",
                    "reference": "TQR-660582",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "0.5",
                                "prorated_mrc": false,
                                "billed_from": null,
                                "billed_to": null,
                                "setup_price": "0.0",
                                "monthly_price": "0.5",
                                "did_group_id": "fce19421-b6b4-4f31-99f4-699bc0300bbc"
                            }
                        }
                    ],
                    "callback_method": "GET",
                    "callback_url": "http://example.com"
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }

   .. tab:: Purchasing Capacity

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "items": [
                {
                  "type": "capacity_order_items",
                  "attributes": {
                    "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228",
                    "qty": 1
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "21.33",
              "status": "Completed",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "Capacity",
              "reference": "NXH-560588",
              "items": [
                {
                  "type": "capacity_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "20.0",
                    "mrc": "1.33",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228"
                  }
                }
              ]
            }
          }
        }

   .. tab:: nanpa_prefix_id

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "nanpa_prefix_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3",
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "10.0",
              "status": "Pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }
        
   .. tab:: Available DID with prorate_days_qty

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "available_did_id": "6c82282c-8193-43ca-9876-8ddef1ade253",
                    "sku_id": "644c2449-0e23-4a67-9f81-565ad5137bb6",
                    "prorate_days_qty": 10
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

                {
            "data": {
                "id": "3276e7e6-559a-4344-95d8-1a83657f46ba",
                "type": "orders",
                "attributes": {
                    "amount": "0.03",
                    "status": "Pending",
                    "created_at": "2022-03-04T07:45:24.471Z",
                    "description": "DID",
                    "reference": "EHF-778400",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "0.03",
                                "prorated_mrc": true,
                                "billed_from": null,
                                "billed_to": null,
                                "setup_price": "0.0",
                                "monthly_price": "0.03",
                                "did_group_id": "239e74ad-9da1-4802-90dd-e1ce148da19e"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

==========
Get Orders
==========

Returns a collection of Orders.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/orders``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``, ``DateTime`` ", "No", ":ref:`Filtering <api_filters>`"
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Order ``id`` field."
   "status", "``Array[String]``", "Yes", "Yes", "Order ``status`` field. |br| Possible values: |br| ``Pending`` |br| ``Canceled`` |br| ``Completed``"
   "created_at_gteq", "``DateTime``", "No", "No", "The ``created_at_gteq`` field."
   "created_at_lteq", "``DateTime``", "No", "No", "The ``created_at_lteq`` field."
   "reference", "``Array[String]``", "No", "Yes", "Order ``reference`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "status", "The ``status`` field. |br| Possible values: |br| ``Pending`` |br| ``Canceled`` |br| ``Completed``"
   "amount", "The ``amount`` field."
   "created_at", "The ``created_at`` field."
   "description", "The ``description`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "status", "The ``status`` attribute. |br| Possible values: |br| ``Pending`` |br| ``Canceled`` |br| ``Completed``"
   "amount", "The ``amount`` attribute."
   "created_at", "The ``created_at`` attribute."
   "description", "The ``description`` attribute."
   "reference", "The ``reference`` attribute."

Example
=======

.. http:example:: curl

    GET /v3/orders HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "889b91ce-93be-4913-a32e-8415d5914f0f",
                "type": "orders",
                "attributes": {
                    "amount": "0.7",
                    "status": "Completed",
                    "created_at": "2020-09-14T07:35:07.038Z",
                    "description": "DID",
                    "reference": "BUV-544694",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.35",
                                "mrc": "0.35",
                                "prorated_mrc": false,
                                "billed_from": "2020-09-14",
                                "billed_to": "2020-10-14",
                                "setup_price": "0.35",
                                "monthly_price": "0.35",
                                "did_group_id": "0a265a8c-50fc-4ab3-ae16-9811bc17c241"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            {
                "id": "cd1e48e8-94e8-4ba5-9ba6-7f87e4aa61c5",
                "type": "orders",
                "attributes": {
                    "amount": "0.7",
                    "status": "Completed",
                    "created_at": "2020-09-14T07:49:40.747Z",
                    "description": "DID",
                    "reference": "VSB-352655",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.35",
                                "mrc": "0.35",
                                "prorated_mrc": false,
                                "billed_from": "2020-09-14",
                                "billed_to": "2020-10-14",
                                "setup_price": "0.35",
                                "monthly_price": "0.35",
                                "did_group_id": "0a265a8c-50fc-4ab3-ae16-9811bc17c241"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            {
                "id": "fac8671b-9515-46c1-bcdb-ce8115557b0b",
                "type": "orders",
                "attributes": {
                    "amount": "0.7",
                    "status": "Completed",
                    "created_at": "2020-09-14T07:50:23.443Z",
                    "description": "DID",
                    "reference": "TDE-247766",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.35",
                                "mrc": "0.35",
                                "prorated_mrc": false,
                                "billed_from": "2020-09-14",
                                "billed_to": "2020-10-14",
                                "setup_price": "0.35",
                                "monthly_price": "0.35",
                                "did_group_id": "d6c199be-dba8-4f87-ae58-29e7a8263e7a"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            }
        ],
        "meta": {
            "total_records": 54,
            "api_version": "2022-05-10"
        },
        "links": {
            "first": "https://api.didww.com/v3/orders?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "next": "https://api.didww.com/v3/orders?page%5Bnumber%5D=2&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/orders?page%5Bnumber%5D=2&page%5Bsize%5D=50"
        }
    }
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

.. _order_object_v33:

============
Order Object
============

Order Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "reference", "``string``", "Order Reference number."
   "amount", "``string``", "Total order amount."
   "status", "``enum``", "Status of the Order. |br| Possible values: |br| ``Pending`` |br| ``Canceled`` |br| ``Completed``"
   "description", "``string``", "Description of the Order."
   "created_at", "``DateTime``", "Date and time of Order creation."
   "items", "``Array<OrderItem>``", "Ordered items array."
   "callback_url", "``string``", "The HTTP or HTTPS endpoint to where events related to order will be delivered."
   "callback_method", "``string``", "The HTTP Method used for order events. **POST**, **GET** are supported methods."

Order Item
----------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "type", "``string``", "No", "Item object type: did_order_items for DIDs and capacity_order_items for Channels."
   "attributes", "One of :ref:`DID Order Item Attributes <did_order_item_attributes_v33>`, |br| :ref:`Capacity Order Item Attributes <capacity_order_item_attributes_v33>`", "No", "Order Item Attributes object. "

.. _did_order_item_attributes_v33:

.. _capacity_order_item_attributes_v33:

Order Item Attributes
---------------------

.. tabs::

   .. tab:: DID

		.. csv-table::
		   :header: "Name", "Type", "Description"

		   "qty", "``integer``", "Quantity of services."
		   "nrc", "``string``", "One-time activation fee (Non Recurring Cost)."
		   "mrc", "``string``", "Ongoing monthly fees (Monthly Recurring Cost)."
		   "prorated_mrc", "``boolean``", "If true, MRC will be charged prorated amount for the services acquired in the middle of the billing cycle. |br| If false, MRC will be charged full amount for the full billing cycle."
		   "billed_from", "``date``", "Billing cycle start date."
		   "billed_to", "``date``", "Billing cycle end date."
		   "did_group_id", "``string``", "DID Group ID."

   .. tab:: Channel

		.. csv-table::
		   :header: "Name", "Type", "Description"

		   "qty", "``integer``", "Quantity of services."
		   "nrc", "``string``", "One-time activation fee (Non Recurring Cost)."
		   "mrc", "``string``", "Ongoing monthly fees (Monthly Recurring Cost)."
		   "prorated_mrc", "``boolean``", "If true, MRC will be charged prorated amount for the services acquired in the middle of the billing cycle. |br| If false, MRC will be charged full amount for the full billing cycle."
		   "billed_from", "``date``", "Billing cycle start date."
		   "billed_to", "``date``", "Billing cycle end date."
		   "capacity_pool_id", "``string``", "Capacity Pool ID."


.. |br| raw:: html

   <br />

.. _dids_v33:

===
DID
===

Returns a single or a list of DID Numbers owned by the account. Allows modifying the settings of a single DID. 

Supported methods: ``GET``, ``PATCH``.

.. toctree::
  :maxdepth: 1
  
  get-did.rst
  get-dids.rst
  update-did.rst
  did-object.rst
  
  
  



=======
Get DID
=======

Returns a single DID owned by your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/dids/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id","``string``", "Yes", "Unique ID identifier of the Order."
   "include", "``string``", "No", "Related resources to include in the response. See :ref:`Inclusion <api_includes>`."

Includes
--------

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "order", ":ref:`Order Object <order_object_v33>`"
   "voice_in_trunk", ":ref:`Trunk Object <voice_in_trunk_object_v33>`"
   "voice_in_trunk.voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v33>`"
   "voice_in_trunk.pop", ":ref:`POP Object <pop_object_v33>`"
   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v33>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v33>`"
   "shared_capacity_group", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v33>`"
   "did_group", ":ref:`DID Group Object <did_group_object_v33>`"
   "did_group.country", ":ref:`Country Object <country_object_v33>`"
   "did_group.city", ":ref:`City Object <city_object_v33>`"
   "did_group.region", ":ref:`Region Object <region_object_v33>`"
   "did_group.did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/dids/44957076-778a-4802-b60c-d22db0cda284 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "9c55ccc7-8b8e-4684-beaa-9f81462dcfdb",
                "type": "dids",
                "attributes": {
                    "blocked": false,
                    "capacity_limit": 1,
                    "description": "description",
                    "terminated": false,
                    "awaiting_registration": false,
                    "created_at": "2020-09-14T07:35:07.198Z",
                    "billing_cycles_count": null,
                    "number": "35314403952",
                    "expires_at": "2021-05-14T07:36:06.443Z",
                    "channels_included_count": 0,
                    "dedicated_channels_count": 0
                },
                "relationships": {
                    "did_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/did_group",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/did_group"
                        }
                    },
                    "order": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/order",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/order"
                        }
                    },
                    "voice_in_trunk": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/voice_in_trunk",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/voice_in_trunk"
                        }
                    },
                    "voice_in_trunk_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/voice_in_trunk_group",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/voice_in_trunk_group"
                        }
                    },
                    "capacity_pool": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/capacity_pool",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/capacity_pool"
                        }
                    },
                    "shared_capacity_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/shared_capacity_group",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/shared_capacity_group"
                        }
                    },
                    "address_verification": {
                        "links": {
                            "self": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/relationships/address_verification",
                            "related": "https://api.didww.com/v3/dids/9c55ccc7-8b8e-4684-beaa-9f81462dcfdb/address_verification"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }

   .. tab:: Request with did_group Include

    .. http:example:: curl

        GET /v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d?include=did_group HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "id": "2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d",
            "type": "dids",
            "attributes": {
              "blocked": false,
              "capacity_limit": 1,
              "description": "string",
              "terminated": false,
              "awaiting_registration": false,
              "number": "437xxxxxxxxx",
              "expires_at": "2017-06-25T08:21:41.795Z",
              "channels_included_count": 2,
              "created_at": "2017-06-25T08:21:41.795Z",
              "dedicated_channels_count": 0
            },
            "relationships": {
              "did_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/did_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/did_group"
                },
                "data": {
                  "type": "did_groups",
                  "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca"
                }
              },
              "order": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/order",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/order"
                }
              },
              "voice_in_trunk": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk"
                }
              },
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk_group"
                }
              },
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/capacity_pool"
                }
              },
              "shared_capacity_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/shared_capacity_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/shared_capacity_group"
                }
              }
            }
          },
          "included": [
            {
              "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca",
              "type": "did_groups",
              "links": {
                "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca"
              },
              "attributes": {
                "prefix": "721",
                "local_prefix": "",
                "features": [
                  "voice"
                ],
                "is_metered": false,
                "area_name": "National",
                "allow_additional_channels": true
              },
              "relationships": {
                "country": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/country",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/country"
                  }
                },
                "city": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/city",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/city"
                  }
                },
                "did_group_type": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/did_group_type",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/did_group_type"
                  }
                },
                "region": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/region",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/region"
                  }
                },
                "stock_keeping_units": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/stock_keeping_units",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/stock_keeping_units"
                  }
                }
              }
            }
          ]
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"



.. _did_object_v33:

==========
DID Object
==========

DID Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "blocked", "``boolean``", "Identifier for a blocked DID. Blocked DIDs are numbers that have expired, have been cancelled or have been suspended by DIDWW."
   "awaiting_registration", "``boolean``", "Identifier for a DID that is awaiting registration."
   "terminated", "``boolean``", "Identifier for terminated DIDs that will be removed from service at the end of the billing cycle."
   "description", "``string``", "Custom DID description for customers reference."
   "number", "``string``", "The actual DID number in the format [country code][area code][subscriber number]."
   "capacity_limit", "``integer``", "The capacity limit (maximum number of simultaneous calls) for this DID."
   "channels_included_count", "``integer``", "The number of channels included with this DID."
   "dedicated_channels_count", "``integer``", "The number of channels from Capacity Pool."
   "expires_at", "``DateTime``", "DateTime when the DID expired or will expire. DateTime is in the ISO 8601 format 'yyyy-MM-dd'T'HH:mm:ss.SSS'Z', where 'SSS' are milliseconds and 'Z' denotes Zulu time (UTC)"
   "created_at", "``DateTime``", "DID created at DateTime."
   "billing_cycles_count", "``integer``", "Specifies how many renewal cycles remain before the DID expires. A value of **null** indicates unlimited automatic renewals; setting it to **0** disables auto‑renewal. Each billing period decrements this count by one (max value: 999)."




========
Get DIDs
========

Returns a list of DIDs owned by your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/dids``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "filter[<filter_name>]","``string``, ``boolean``","No",":ref:`Filtering <api_filters>`"
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "order", ":ref:`Order Object <order_object_v33>`"
   "voice_in_trunk", ":ref:`Trunk Object <voice_in_trunk_object_v33>`"
   "voice_in_trunk.voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v33>`"
   "voice_in_trunk.pop", ":ref:`POP Object <pop_object_v33>`"
   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v33>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v33>`"
   "shared_capacity_group", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v33>`"
   "did_group", ":ref:`DID Group Object <did_group_object_v33>`"
   "did_group.country", ":ref:`Country Object <country_object_v33>`"
   "did_group.city", ":ref:`City Object <city_object_v33>`"
   "did_group.region", ":ref:`Region Object <region_object_v33>`"
   "did_group.did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "number", "``string``", "Yes", "Yes", "The DID ``number`` field."
   "description", "``string``", "Yes", "Yes", "The ``description`` field."
   "terminated", "``boolean``", "No", "No", "The ``terminated`` field."
   "awaiting_registration", "``boolean``", "No", "No", "The ``awaiting_registration`` field."
   "pending_removal", "``boolean``", "No", "No", "The ``awaiting_registration`` field."
   "blocked", "``boolean``", "No", "No", "The ``blocked`` field."
   "billing_cycles_count", "``integer``", "Yes", "No", "The ``billing_cycles_count`` field."
   "did_group.id", "``string``", "Yes", "Yes", "The ID field of ``did_group`` relationship."
   "country.id", "``string``", "Yes", "Yes", "The ID field of ``country`` relationship."
   "region.id", "``string``", "Yes", "Yes", "The ID field of ``region`` relationship."
   "city.id", "``string``", "Yes", "Yes", "The ID field of ``city`` relationship."
   "order.id", "``string``", "Yes", "Yes", "The ID field of ``order`` relationship."
   "voice_in_trunk.id", "``string``", "Yes", "Yes", "The ID field of ``voice_in_trunk`` relationship."
   "voice_in_trunk_group.id", "``string``", "Yes", "Yes", "The ID field of ``voice_in_trunk_group`` relationship."
   "shared_capacity_group.id", "``string``", "Yes", "Yes", "The ID field of ``shared_capacity_group`` relationship."
   "capacity_pool.id", "``string``", "Yes", "Yes", "The ID field of ``capacity_pool`` relationship."
   "order.reference", "``string``", "No", "Yes", "The reference field of ``order`` relationship."
   "did_group.features", "``string``", "No", "Yes", "DID Group ``features`` field."
   "address_verification.id", "``string``", "Yes", "Yes", "The ID field of ``address_verification`` relationship."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "blocked", "Blocked status"
   "awaiting_registration", "Awaiting registration status"
   "terminated", "Termination status"
   "capacity_limit", "Capacity limit"
   "billing_cycles_count", "Billing cycles count"
   "description", "Description text"
   "number", "DID number"
   "expires_at", "Expiration timestamp"
   "channels_included_count", "Included channels count"
   "dedicated_channels_count", "Dedicated channels count"
   "created_at", "Creation timestamp"

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "blocked", "The ``blocked`` attribute"
   "awaiting_registration", "The ``awaiting_registration`` attribute"
   "terminated", "The ``terminated`` attribute"
   "capacity_limit", "The ``capacity_limit`` attribute"
   "billing_cycles_count", "The ``billing_cycles_count`` attribute"
   "description", "The ``description`` attribute"
   "number", "The ``number`` attribute"
   "expires_at", "The ``expires_at`` attribute"
   "channels_included_count", "The ``channels_included_count`` attribute"
   "dedicated_channels_count", "The ``dedicated_channels_count`` attribute"
   "created_at", "The ``created_at`` attribute"

Examples
========

.. tabs::

  .. tab:: Simple Request

  .. http:example:: curl

      GET /v3/dids HTTP/1.1
      Host: api.didww.com
      Content-Type: application/vnd.api+json
      Accept: application/vnd.api+json
      Api-Key: [API token]

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json

        {
          "data": [
            {
              "id": "ac40fb08-ac14-4a6c-8f20-fe650870c266",
              "type": "dids",
              "attributes": {
                "blocked": false,
                "capacity_limit": 1,
                "description": "string",
                "terminated": false,
                "awaiting_registration": false,
                "number": "437xxxxxxxxx",
                "expires_at": "2017-06-25T08:21:41.795Z",
                "channels_included_count": 2,
                "created_at": "2017-06-25T08:21:41.795Z",
                "dedicated_channels_count": 0
              },
              "relationships": {
                "did_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/did_group",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/did_group"
                  }
                },
                "order": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/order",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/order"
                  }
                },
                "voice_in_trunk": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk"
                  }
                },
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk_group"
                  }
                },
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/capacity_pool"
                  }
                },
                "shared_capacity_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/shared_capacity_group",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/shared_capacity_group"
                  }
                },
                "address_verification": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/address_verification",
                    "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/address_verification"
                  }
                }
              }
            },
            {
              "id": "b37f0fcf-24d0-4799-8e81-a69bcc889f2e",
              "type": "dids",
              "attributes": {
                "blocked": false,
                "capacity_limit": 1,
                "description": "string",
                "terminated": false,
                "awaiting_registration": false,
                "number": "437xxxxxxxxx",
                "expires_at": "2017-06-25T08:21:41.795Z",
                "channels_included_count": 2,
                "created_at": "2017-06-25T08:21:41.795Z",
                "dedicated_channels_count": 0
              },
              "relationships": {
                "did_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/did_group",
                    "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/did_group"
                  }
                },
                "order": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/order",
                    "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/order"
                  }
                },
                "voice_in_trunk": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/voice_in_trunk",
                    "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/voice_in_trunk"
                  }
                },
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/voice_in_trunk_group"
                  }
                },
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/capacity_pool"
                  }
                },
                "shared_capacity_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/shared_capacity_group",
                    "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/shared_capacity_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/dids&page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/dids&page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }

  .. tab:: Request with did_group Include

    .. http:example:: curl

        GET /v3/dids?include=did_group HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d",
            "type": "dids",
            "attributes": {
              "blocked": false,
              "capacity_limit": 1,
              "description": "string",
              "terminated": false,
              "awaiting_registration": false,
              "number": "437xxxxxxxxx",
              "expires_at": "2017-06-25T08:21:41.795Z",
              "channels_included_count": 2,
              "created_at": "2017-06-25T08:21:41.795Z",
              "dedicated_channels_count": 0
            },
            "relationships": {
              "did_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/did_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/did_group"
                },
                "data": {
                  "type": "did_groups",
                  "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca"
                }
              },
              "order": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/order",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/order"
                }
              },
              "voice_in_trunk": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk"
                }
              },
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk_group"
                }
              },
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/capacity_pool"
                }
              },
              "shared_capacity_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/shared_capacity_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/shared_capacity_group"
                }
              }
            }
          },
          "included": [
            {
              "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca",
              "type": "did_groups",
              "links": {
                "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca"
              },
              "attributes": {
                "prefix": "721",
                "local_prefix": "",
                "features": [
                  "voice"
                ],
                "is_metered": false,
                "area_name": "National",
                "allow_additional_channels": true
              },
              "relationships": {
                "country": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/country",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/country"
                  }
                },
                "city": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/city",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/city"
                  }
                },
                "did_group_type": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/did_group_type",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/did_group_type"
                  }
                },
                "region": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/region",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/region"
                  }
                },
                "stock_keeping_units": {
                  "links": {
                    "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/relationships/stock_keeping_units",
                    "related": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca/stock_keeping_units"
                  }
                }
              }
            }
          ]
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 



.. |br| raw:: html

   <br />

==========
Update DID
==========

Update the settings of a single DID owned by your account. Using this endpoint you can cancel, restore or renew DID. 

To cancel a DID, attribute ``terminated`` must be ``true``, to renew or restore DID attribute ``terminated`` must be ``false``.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/dids/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id","``string``", "Yes", "Unique ID number allocated to this DID"
   "include","``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Name","Description"

   "voice_in_trunk",":ref:`Trunk Object <voice_in_trunk_object_v33>`"

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "terminated", "``boolean``", "Optional", "If set to ``true``, it will cancel a DID number. To renew or restore a DID number, the attribute must be set to ``false``."
   "description", "``string``", "Optional", "A DID number description."
   "billing_cycles_count", "``integer``", "Optional", "The number of Billing Cycles that this DID Number will renew until expiration. |br|  If set to ``0``, then DID will not be renewed. |br|  If set to ``null``, then DID will be renewed infinitely. |br|  After each renew value will be decreased by 1 if it is set. |br|  Maximum value of ``billing_cycles_count`` is 999."
   "dedicated_channels_count", "``integer``", "Optional", "Amount of dedicated channels to assign."
   "capacity_limit", "``integer``", "Optional", "Limits incoming capacity per DID number according to entered value. If set as ``null``, assigned capacity is not limited."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch
   
     .. http:example:: curl

			PATCH /v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
			{
			  "data": {
			    "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
			    "type": "dids",
			    "attributes": {
			      "terminated": false,
			      "description": "string",
			      "capacity_limit": 1
			    }
			  }
			}       
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			  "data": {
			    "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": 1,
			      "description": "string",
			      "terminated": false,
			      "awaiting_registration": false,
			      "number": "437xxxxxxxxx",
			      "expires_at": "2017-06-25T08:21:41.795Z",
			      "channels_included_count": 2,
			      "created_at": "2017-06-25T08:21:41.795Z",
			      "dedicated_channels_count": 0
			    }
			  },
			  "relationships": {
			    "did_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/did_group",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/did_group"
			      }
			    },
			    "order": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/order",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/order"
			      }
			    },
			    "voice_in_trunk": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/voice_in_trunk",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/voice_in_trunk"
			      }
			    },
			    "voice_in_trunk_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/voice_in_trunk_group",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/voice_in_trunk_group"
			      }
			    },
			    "capacity_pool": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/capacity_pool",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/capacity_pool"
			      }
			    },
			    "shared_capacity_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/shared_capacity_group",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/shared_capacity_group"
			      }
			    }
			  }
			}
        

   .. tab:: Assign Voice IN Trunk
   
    .. http:example:: curl

			PATCH /v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
			
			{
			  "data": {
			    "id": "3505b18a-3019-47bc-95d1-0f9ec7766fd5",
			    "type": "dids",
			    "relationships": {
			      "voice_in_trunk": {
			        "data": {
			          "type": "voice_in_trunks",
			          "id": "c80d096a-c8cf-4449-aa6d-8bac39130fe0"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "3505b18a-3019-47bc-95d1-0f9ec7766fd5",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": 1,
			      "description": "string",
			      "terminated": false,
			      "awaiting_registration": false,
			      "number": "437xxxxxxxxx",
			      "expires_at": "2017-06-25T08:21:41.795Z",
			      "channels_included_count": 2,
			      "created_at": "2017-06-25T08:21:41.795Z",
			      "dedicated_channels_count": 0
			    },
			    "relationships": {
			      "did_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/did_group",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/did_group"
			        }
			      },
			      "order": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/order",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/order"
			        }
			      },
			      "voice_in_trunk": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/voice_in_trunk",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/voice_in_trunk"
			        }
			      },
			      "voice_in_trunk_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/voice_in_trunk_group",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/voice_in_trunk_group"
			        }
			      },
			      "capacity_pool": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/capacity_pool",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/capacity_pool"
			        }
			      },
			      "shared_capacity_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/shared_capacity_group",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/shared_capacity_group"
			        }
			      }
			    }
			  }
			}
	
			
   .. tab:: Assign Voice IN Trunk Group
   
    .. http:example:: curl

			PATCH /v3/dids/3e3f57ec-0541-473a-af63-103216d19db3 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "id": "3e3f57ec-0541-473a-af63-103216d19db3",
			    "type": "dids",
			    "relationships": {
			      "voice_in_trunk_group": {
			        "data": {
			          "type": "voice_in_trunk_groups",
			          "id": "1dc6e448-d9d8-4da8-a34b-21459b03112f"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "3e3f57ec-0541-473a-af63-103216d19db3",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": 1,
			      "description": "string",
			      "terminated": false,
			      "awaiting_registration": false,
			      "number": "437xxxxxxxxx",
			      "expires_at": "2017-06-25T08:21:41.795Z",
			      "channels_included_count": 2,
			      "created_at": "2017-06-25T08:21:41.795Z",
			      "dedicated_channels_count": 0
			    }
			  },
			  "relationships": {
			    "did_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/did_group",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/did_group"
			      }
			    },
			    "order": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/order",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/order"
			      }
			    },
			    "voice_in_trunk": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/voice_in_trunk",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/voice_in_trunk"
			      }
			    },
			    "voice_in_trunk_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/voice_in_trunk_group",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/voice_in_trunk_group"
			      }
			    },
			    "capacity_pool": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/capacity_pool",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/capacity_pool"
			      }
			    },
			    "shared_capacity_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/shared_capacity_group",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/shared_capacity_group"
			      }
			    }
			  }
			}

   .. tab:: Assign Dedicated Capacity
   
    .. http:example:: curl

			PATCH /v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "attributes": {
			      "dedicated_channels_count": 2
			    },
			    "relationships": {
			      "capacity_pool": {
			        "data": {
			          "type": "capacity_pools",
			          "id": "1eb75a47-38b6-4ec2-8990-fe249ffd7b92"
			        }
			      }
			    }
			  }
			}			
			
			
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2019-05-21T08:25:02.223Z",
			      "number": "4474183XXXXX",
			      "expires_at": "2019-06-21T08:25:13.367Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 2
			    },
			    "relationships": {
			      "did_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/did_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/did_group"
			        }
			      },
			      "order": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/order",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/order"
			        }
			      },
			      "voice_in_trunk": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk"
			        }
			      },
			      "voice_in_trunk_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk_group"
			        }
			      },
			      "capacity_pool": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/capacity_pool",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/capacity_pool"
			        }
			      },
			      "shared_capacity_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/shared_capacity_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/shared_capacity_group"
			        }
			      }
			    }
			  }
			}
			
   .. tab:: Assign Shared Capacity
   
    .. http:example:: curl		
			
			PATCH /v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "relationships": {
			      "shared_capacity_group": {
			        "data": {
			          "type": "shared_capacity_groups",
			          "id": "8a581244-de83-4c46-ac0a-32659279169e"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2019-05-21T08:25:02.223Z",
			      "number": "4474183XXXXX",
			      "expires_at": "2019-06-21T08:25:13.367Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 2
			    },
			    "relationships": {
			      "did_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/did_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/did_group"
			        }
			      },
			      "order": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/order",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/order"
			        }
			      },
			      "voice_in_trunk": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk"
			        }
			      },
			      "voice_in_trunk_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk_group"
			        }
			      },
			      "capacity_pool": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/capacity_pool",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/capacity_pool"
			        }
			      },
			      "shared_capacity_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/shared_capacity_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/shared_capacity_group"
			        }
			      }
			    }
			  }
			}

   .. tab:: Remove Trunk
   
    .. http:example:: curl	
    
			PATCH /v3/dids/1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "dids",
			    "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
			    "relationships": {
			      "voice_in_trunk": {
			        "data": null
			      }
			    }
			  }
			}
			
			
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

   .. tab:: Remove Identity

    .. http:example:: curl

			PATCH /v3/dids/1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "dids",
			    "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
			    "relationships": {
			      "address_verification": {
			        "data": null
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			  "data": {
			    "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2019-05-21T08:25:02.223Z",
			      "number": "4474183XXXXX",
			      "expires_at": "2019-06-21T08:25:13.367Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 2
			    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 

   
   
   
   
   

   



.. |br| raw:: html

   <br />

.. _voice_in_trunks_v33:

===============
Voice IN Trunks
===============

Returns a list of all of the voice in trunks configured by the account. Allows create, edit or delete a trunk. 

This section also includes, available POPs, Codecs and Disconnect codes supported by DIDWW. 

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  get-voice-in-trunk.rst
  get-voice-in-trunks.rst
  create-voice-in-trunk.rst
  update-voice-in-trunk.rst
  delete-voice-in-trunk.rst
  voice-in-trunk-object.rst
  get-pops.rst
  pop-object.rst
  codecs.rst
  rerouting-disconnect-codes.rst
  
  
  
  



==================
Get Voice IN Trunk
==================

Returns trunks owned by the account. Several type of trunks can be retrieved: SIP, PSTN.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunks/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Name","Description"

   "voice_in_trunk_group",":ref:`Trunk Group Object <voice_in_trunk_group_object_v33>`"
   "pop",":ref:`POP Object <pop_object_v33>`"

Examples
========

.. tabs::

   .. tab:: SIP Trunk

    .. http:example:: curl

        GET /v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "df78e081-b7d1-4769-80ce-f349af4f612e",
            "type": "voice_in_trunks",
            "attributes": {
              "priority": 1,
              "capacity_limit": 10,
              "weight": 2,
              "name": "Office",
              "cli_format": "e164",
              "cli_prefix": "+",
              "description": null,
              "ringing_timeout": 30,
              "created_at": "2017-06-25T08:21:41.795Z",
              "configuration": {
                "type": "sip_configurations",
                "attributes": {
                  "username": "username",
                  "host": "example.com",
                  "port": null,
                  "codec_ids": [
                    9,
                    7
                  ],
                  "rx_dtmf_format_id": 1,
                  "tx_dtmf_format_id": 1,
                  "resolve_ruri": true,
                  "auth_enabled": true,
                  "auth_user": "username",
                  "auth_password": "password",
                  "auth_from_user": "Office",
                  "auth_from_domain": "example.com",
                  "sst_enabled": false,
                  "sst_min_timer": 600,
                  "sst_max_timer": 900,
                  "sst_accept_501": true,
                  "sip_timer_b": 8000,
                  "dns_srv_failover_timer": 2000,
                  "rtp_ping": false,
                  "rtp_timeout": 30,
                  "force_symmetric_rtp": false,
                  "symmetric_rtp_ignore_rtcp": false,
                  "rerouting_disconnect_code_ids": [
                    58,
                    59,
                    1505
                  ],
                  "sst_session_expires": null,
                  "sst_refresh_method_id": 1,
                  "transport_protocol_id": 1,
                  "max_transfers": 5,
                  "max_30x_redirects": 0,
                  "media_encryption_mode": "disabled",
                  "stir_shaken_mode": "disabled",
                  "allowed_rtp_ips": null
                }
              }
            },
            "relationships": {
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/voice_in_trunk_group"
                }
              },
              "pop": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/relationships/pop",
                  "related": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/pop"
                }
              }
            }
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }

   .. tab:: PSTN

    .. http:example:: curl

        GET /v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "84746865-b1c0-414d-86c7-62c85c22fd69",
            "type": "voice_in_trunks",
            "attributes": {
              "priority": 1,
              "capacity_limit": 5,
              "weight": 65535,
              "name": "Office Mobile",
              "cli_format": "e164",
              "cli_prefix": null,
              "description": null,
              "ringing_timeout": null,
              "created_at": "2017-06-25T08:21:41.795Z",
              "configuration": {
                "type": "pstn_configurations",
                "attributes": {
                  "dst": "1xxxxxxxxx"
                }
              }
            },
            "relationships": {
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/voice_in_trunk_group"
                }
              },
              "pop": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/relationships/pop",
                  "related": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/pop"
                }
              }
            }
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



.. _trunk_codecs_v33:

======
Codecs
======

.. csv-table::
   :header: "Codec ID", "Codec Name"

   "6", "telephone-event "
   "7", "G723"
   "8", "G729"
   "9", "PCMU"
   "10", "PCMA"
   "12", "speex"
   "13", "GSM"
   "14", "G726-32"
   "15", "G721"
   "16", "G726-24"
   "17", "G726-40"
   "18", "G726-16"
   "19", "L16"


.. |br| raw:: html

   <br />
   
=====================
Create Voice IN Trunk
=====================

You can create several type of trunks: SIP, PSTN.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_in_trunks``

Body Parameters
---------------

.. csv-table::
   :header: "Name", "Type","Nullable", "Is Required?", "Description"

   "type", "``string``", "No","Yes", "Trunks "
   "attributes", "``object``","No", "Yes", "Trunk configuration complex object."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "priority", "``integer``", "No", "Yes", "The priority of this target host. |br| DIDWW will attempt to contact the target trunk with the lowest-numbered priority; |br| target trunk with the same priority will be tried in an order defined by the weight field. |br| The range is 0-65535. See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "weight", "``integer``", "No", "Yes", "A trunk selection mechanism. |br| The weight field specifies a relative weight for entries with the same priority. |br| Larger weights will be given a proportionately higher probability of being selected. |br| The range of this number is 0-65535. |br| In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. |br| See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "capacity_limit", "``integer``", "No", "No", "Maximum number of simultaneous calls for the trunk."
   "ringing_timeout", "``integer``", "No", "No", "Ring time in seconds. Supported values are integers from 1 to 32. If ``null``, the timeout is undefined. |br| If the call is not connected within this time, the transaction is ended with the disconnect code **Ringing timeout**."
   "name", "``string``", "No", "Yes", "Friendly name of the trunk."
   "cli_format", "``string``", "No", "No", "**RAW** - Do not alter CLI (default). |br| **E164** - Attempt to convert CLI to E.164 format. |br| **Local** - Attempt to convert CLI to Localized format. |br| **CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID**."
   "cli_prefix", "``string``", "No", "No", "You may prefix the CLI with an optional ``+`` sign followed by up to 6 characters, including digits and ``#``."
   "description", "``string``", "No", "No", "Optional description of the trunk."
   "configuration", "One of :ref:`sip_configurations <trunk_attributes_v33>`, |br| :ref:`pstn_configurations <trunk_attributes_v33>`", "N/A", "Yes", "Trunk configuration complex object."

.. _trunk_attributes_v33:

Attributes Configuration
------------------------

.. tabs::

   .. tab:: SIP
   
	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``sip_configurations``", "No","Yes", "SIP configuration complex object. "
	   "attributes", ":ref:`sip_configuration_attributes <trunk_attributes_v33>`","No", "Yes", "SIP configuration attributes object."
      
   .. tab:: PSTN

	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``pstn_configurations``", "No","Yes", "PSTN configuration complex object."
	   "attributes", ":ref:`pstn_configuration_attributes <trunk_attributes_v33>`","No", "Yes", "PSTN configuration attributes object."

Configuration Attributes
------------------------

.. tabs::

   .. tab:: SIP

	.. csv-table::
	   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

	   "username", "``string``", "No", "Yes", "User part of R-URI in INVITE request. |br| You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. |br| For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format"
	   "host", "``string``", "No", "Yes", "Host part of R-URI in INVITE request."
	   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_, `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
	   "stir_shaken_mode", "``string``", "No", "No", "Stir/Shaken mode. |br| See :ref:`STIR/SHAKEN <service_did_stir_shaken>`  for more details. |br| Possible Values: |br| 'disabled' - Do not send identity |br| 'original' - Transit Identity header as is |br| 'pai' - Add PAI, P-Attestation-Indicator, P-Origination-ID |br| 'original_pai' - Transit Identity Header as is + Add PAI, P-Attestation Indicator, P-Origination-ID |br| 'verstat' - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID"
	   "auth_user", "``string``", "No", "No", "Optional authorization user for the SIP server."
	   "auth_password", "``string``", "No", "No", "Optional authorization password for the SIP server."
	   "auth_from_user", "``string``", "No", "No", "Specify user in a **from** field instead of CallerID (overrides CallerID). |br| Some equipment require **from**; to be equivalent to **Auth user**."
	   "auth_from_domain", "``string``", "No", "No", "Sets default **from** domain in SIP messages. Some equipment may require specific **From** Domain."
	   "sst_refresh_method_id", "``integer``", "No", "No", "SIP method which will be used for session update. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details. |br| Possible values: |br| 1 - Invite |br| 2 - Update |br| 3 - Update fallback Invite"
	   "sip_timer_b", "``integer``", "No", "No", "INVITE transaction timeout (Default 8000ms). |br| See `RFC 3261 Section 17.1.1.2 <https://tools.ietf.org/html/rfc3261#section-17.1.1.2>`_ for more details."
	   "dns_srv_failover_timer", "``integer``", "No", "No", "Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms)."
	   "rtp_ping", "``boolean``", "No", "No", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."
	   "rtp_timeout", "``integer``", "No", "No", "Disconnect the call if the RTP packets do not arrive within the specified time."
	   "allowed_rtp_ips", "Array of ``strings``", "No", "No", "The allowed RTP IPs. Array from 0 to 10 items: IPv4 or IPv6, single or subnet."
	   "sst_min_timer", "``integer``", "No", "No", "Minimal SIP Session timer value (Default 600 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_max_timer", "``integer``", "No", "No", "Maximal SIP Session timer value (Default 900 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_session_expires", "``integer``", "No", "No", "Session-Expires header value. Optional, should be in range with **sst_min_timer** and **sst_max_timer**. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "port", "``integer``", "No", "No", "Port part of R-URI in INVITE request (is not mandatory). |br| If port is null, SRV record will be resolved (or A record if SRV is unavailable)."
	   "rx_dtmf_format_id", "``integer``", "No", "No", "The method id for receiving DTMF signals from customers equipment. |br| Possible values: |br| 1 - RFC 2833 |br| 2 - SIP INFO application/dtmf-relay OR application/dtmf |br| 3 - RFC 2833 OR SIP INFO"
	   "tx_dtmf_format_id", "``integer``", "No", "No", "The method of sending DTMF signals to customers equipment. |br| Possible values: |br| 1 - Disable sending |br| 2 - RFC 2833 |br| 3 - SIP INFO application/dtmf-relay |br| 4 - SIP INFO application/dtmf"
	   "force_symmetric_rtp", "``boolean``", "No", "No", "Forced to work in Symmetric RTP / COMEDIA mode."
	   "symmetric_rtp_ignore_rtcp", "``boolean``", "No", "No", "Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. |br| Only RTP packets will be considered."
	   "sst_enabled", "``boolean``", "No", "No", "Enable SIP Session timers customization. |br| SIP session timers are used to make sure that a session (dialog) is still alive, |br| even though there may have been a long time since the last in-dialog message. |br| If the other end is not responding, the dialog will be hung up automatically. |br| SIP session timers need to be supported by all end points for it to work. |br| It’s a SIP extension, standardized by the IETF. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_accept_501", "``boolean``", "No", "No", "Do not drop the call after receiving SIP 501 response for non-critical messages."
	   "auth_enabled", "``boolean``", "No", "No", "Enable authorization for the SIP server."
	   "resolve_ruri", "``boolean``", "No", "No", "Replace host part of the R-URI by resolved IP address."
	   "rerouting_disconnect_code_ids", "``array``", "No", "No", ":ref:`Rerouting disconnect codes <disconnect_codes_v33>`."
	   "codec_ids", "``array``", "No", "No", ":ref:`Codecs <trunk_codecs_v33>`."
	   "transport_protocol_id", "``integer``", "No", "No", "The transport layer that will be responsible for the actual transmission of SIP requests and responses: |br| 1 - UDP |br| 2 - TCP |br| 3 - TLS."
	   "max_transfers", "``integer``", "No", "No", "Max count of the **REFER** requests."
	   "max_30x_redirects", "``integer``", "No", "No", "Max count of 301/302 redirects."

   .. tab:: PSTN
	
	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "dst", "``string``", "No","Yes", "Phone number's."

Examples
========

.. tabs::

    .. tab:: SIP
   
        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
        
            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": "1",
                  "weight": "2",
                  "capacity_limit": 10,
                  "ringing_timeout": 30,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": "true",
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": "false",
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_refresh_method_id": 1,
                      "sst_accept_501": "true",
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": "false",
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": "false",
                      "symmetric_rtp_ignore_rtcp": "false",
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "port": 5060,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "f36d1d17-bd16-42b9-af42-0cfe166bf3ec",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/pop"
                    }
                  }
                }
              }
            }
      
            
    .. tab:: PSTN
   
        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
            
            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "name": "Office Mobile",
                  "capacity_limit": 5,
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "1xxxxxxxxx"
                    }
                  }
                }
              }
            }
            
            
            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "28b360b9-0d35-4c94-bbfd-1c33a7680b34",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 5,
                  "weight": 65535,
                  "name": "Office Mobile",
                  "cli_format": "e164",
                  "cli_prefix": null,
                  "description": null,
                  "ringing_timeout": null,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "1xxxxxxxxx"
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/pop"
                    }
                  }
                }
              }
            }

    .. tab:: SIP with POP
   
        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]             
            
            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "name": "Office SIP",
                  "capacity_limit": 18,
                  "cli_format": "e164",
                  "cli_prefix": "+1",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": "true",
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": "false",
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_refresh_method_id": 1,
                      "sst_accept_501": "true",
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": "false",
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": "false",
                      "symmetric_rtp_ignore_rtcp": "false",
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "port": 5060,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "pop": {
                    "data": {
                      "type": "pops",
                      "id": "240416e4-aeb2-4ca5-9df2-f37f01e930cf"
                    }
                  }
                }
              }
            }      
            
            
            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "7adfab4e-83bc-45e2-84e6-60342a505713",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 18,
                  "weight": 65535,
                  "name": "Office SIP",
                  "cli_format": "e164",
                  "cli_prefix": "+1",
                  "description": null,
                  "ringing_timeout": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/pop"
                    },
                    "data": {
                      "type": "pops",
                      "id": "240416e4-aeb2-4ca5-9df2-f37f01e930cf"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "240416e4-aeb2-4ca5-9df2-f37f01e930cf",
                  "type": "pops",
                  "links": {
                    "self": "https://api.didww.com/v3/pops/240416e4-aeb2-4ca5-9df2-f37f01e930cf"
                  },
                  "attributes": {
                    "name": "USA, NY"
                  }
                }
              ]
            }    
            
            
Other Responses
===============
            
.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


=====================
Delete Voice IN Trunk
=====================

Deletes the Trunk without possibility to retrieve.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/voice_in_trunks/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."

Example
=======

.. http:example:: curl

    DELETE /v3/voice_in_trunks/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    




========
Get POPs
========

Returns a list of PoPs (Points of Presence). Each PoP has a unique identification number. Pagination is disabled.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/pops``

Example
=======

.. http:example:: curl

    GET /v3/pops HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "id": "f5ffe21a-7b8f-4404-928f-88522d9bf153",
          "type": "pops",
          "attributes": {
            "name": "USA, NY"
          }
        },
        {
          "id": "c4c214f5-5f70-4f8d-8ebe-2aa203bfdd0b",
          "type": "pops",
          "attributes": {
            "name": "DE, FRA"
          }
        }
      ],
      "meta": {
        "total_records": 2
      },
      "links": {
        "first": "https://api.didww.com/v3/pops?&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
        "next": "https://api.didww.com/v3/pops?&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
      }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 





===================
Get Voice IN Trunks
===================

Returns the collection of Trunks.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunks``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``, ``DateTime`` ", "No", ":ref:`Filtering <api_filters>`"
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Trunk ``id`` field. "
   "name", "``string``", "Yes", "Yes", "Trunk ``name`` field.  "
   "configuration.type", "``string``", "Yes", "Yes", "The type of configuration (SIP, PSTN, etc)"

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "The ``name`` field."
   "priority", "The ``priority`` field."
   "capacity_limit", "The ``capacity_limit`` field."
   "weight", "The ``weight`` field."
   "cli_format", "The ``cli_format`` field."
   "cli_prefix", "The ``cli_prefix`` field."
   "description", "The ``description`` field."
   "ringing_timeout", "The ``ringing_timeout`` field."
   "created_at", "The ``created_at`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "name", "The ``name`` attribute."
   "priority", "The ``priority`` attribute."
   "capacity_limit", "The ``capacity_limit`` attribute."
   "weight", "The ``weight`` attribute."
   "cli_format", "The ``cli_format`` attribute."
   "cli_prefix", "The ``cli_prefix`` attribute."
   "description", "The ``description`` attribute."
   "ringing_timeout", "The ``ringing_timeout`` attribute."
   "created_at", "The ``created_at`` attribute."

Example
=======

.. http:example:: curl

        GET /v3/voice_in_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
    
    
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "2d7f943f-07c4-4b27-8792-e85806368218",
              "type": "voice_in_trunks",
              "attributes": {
                "priority": 1,
                "capacity_limit": 10,
                "weight": 2,
                "name": "Office",
                "cli_format": "e164",
                "cli_prefix": "+",
                "description": null,
                "ringing_timeout": 30,
                "created_at": "2017-06-25T08:21:41.795Z",
                "configuration": {
                  "type": "sip_configurations",
                  "attributes": {
                    "username": "username",
                    "host": "example.com",
                    "port": null,
                    "codec_ids": [
                      9,
                      7
                    ],
                    "rx_dtmf_format_id": 1,
                    "tx_dtmf_format_id": 1,
                    "resolve_ruri": true,
                    "auth_enabled": true,
                    "auth_user": "username",
                    "auth_password": "password",
                    "auth_from_user": "Office",
                    "auth_from_domain": "example.com",
                    "sst_enabled": false,
                    "sst_min_timer": 600,
                    "sst_max_timer": 900,
                    "sst_accept_501": true,
                    "sip_timer_b": 8000,
                    "dns_srv_failover_timer": 2000,
                    "rtp_ping": false,
                    "rtp_timeout": 30,
                    "force_symmetric_rtp": false,
                    "symmetric_rtp_ignore_rtcp": false,
                    "rerouting_disconnect_code_ids": [
                      58,
                      59,
                      1505
                    ],
                    "sst_session_expires": null,
                    "sst_refresh_method_id": 1,
                    "transport_protocol_id": 1,
                    "max_transfers": 5,
                    "max_30x_redirects": 7,
                    "media_encryption_mode": "disabled",
                    "stir_shaken_mode": "disabled",
                    "allowed_rtp_ips": null
                  }
                }
              },
              "relationships": {
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunks/2d7f943f-07c4-4b27-8792-e85806368218/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/voice_in_trunks/2d7f943f-07c4-4b27-8792-e85806368218/voice_in_trunk_group"
                  }
                }
              }
            },
            {
              "id": "34b95e8c-9b78-4e64-aea8-9e5764d8f16f",
              "type": "voice_in_trunks",
              "attributes": {
                "priority": 1,
                "capacity_limit": 5,
                "weight": 65535,
                "name": "Office Mobile",
                "cli_format": "e164",
                "cli_prefix": null,
                "description": null,
                "ringing_timeout": null,
                "created_at": "2017-06-25T08:21:41.795Z",
                "configuration": {
                  "type": "pstn_configurations",
                  "attributes": {
                    "dst": "1xxxxxxxxx"
                  }
                }
              },
              "relationships": {
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunks/34b95e8c-9b78-4e64-aea8-9e5764d8f16f/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/voice_in_trunks/34b95e8c-9b78-4e64-aea8-9e5764d8f16f/voice_in_trunk_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/voice_in_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/voice_in_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }



.. _pop_object_v33:

==========
POP Object
==========

POP Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "POP name "



.. _disconnect_codes_v33:

==========================
Rerouting Disconnect Codes
==========================

.. csv-table::
   :header: "ID", "Code", "Description"

   "56", "400", "Bad Request"
   "57", "401", "Unauthorized"
   "58", "402", "Payment Required"
   "59", "403", "Forbidden"
   "60", "404", "Not Found"
   "64", "408", "Request Timeout"
   "65", "409", "Conflict"
   "66", "410", "Gone"
   "67", "412", "Conditional Request Failed"
   "68", "413", "Request Entity Too Large"
   "69", "414", "Request-URI Too Long"
   "70", "415", "Unsupported Media Type"
   "71", "416", "Unsupported URI Scheme"
   "72", "417", "Unknown Resource-Priority"
   "73", "420", "Bad Extension"
   "74", "421", "Extension Required"
   "75", "422", "Session Interval Too Small"
   "76", "423", "Interval Too Brief"
   "77", "424", "Bad Location Information"
   "78", "428", "Use Identity Header"
   "79", "429", "Provide Referrer Identity"
   "80", "433", "Anonymity Disallowed"
   "81", "436", "Bad Identity-Info"
   "82", "437", "Unsupported Certificate"
   "83", "438", "Invalid Identity Header"
   "84", "480", "Temporarily Unavailable"
   "86", "482", "Loop Detected"
   "87", "483", "Too Many Hops"
   "88", "484", "Address Incomplete"
   "89", "485", "Ambiguous"
   "90", "486", "Busy Here"
   "91", "487", "Request Terminated"
   "92", "488", "Not Acceptable Here"
   "96", "494", "Security Agreement Required"
   "97", "500", "Server Internal Error"
   "98", "501", "Not Implemented"
   "99", "502", "Bad Gateway"
   "100", "503", "Service Unavailable"
   "101", "504", "Server Time-out"
   "102", "505", "Version Not Supported"
   "103", "513", "Message Too Large"
   "104", "580", "Precondition Failure"
   "105", "600", "Busy Everywhere"
   "106", "603", "Decline"
   "107", "604", "Does Not Exist Anywhere"
   "108", "606", "Not Acceptable"
   "1505", "", "Ringing timeout"


.. |br| raw:: html

   <br />

=====================
Update Voice IN Trunk
=====================

Updates a Trunk.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/voice_in_trunks/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``","Yes", "Unique ID identifier of Trunk. "

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "priority", "``integer``", "No", "Yes", "The priority of this target host. |br| DIDWW will attempt to contact the target trunk with the lowest-numbered priority; |br| target trunk with the same priority will be tried in an order defined by the weight field. |br| The range is 0-65535. See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "weight", "``integer``", "No", "Yes", "A trunk selection mechanism. |br| The weight field specifies a relative weight for entries with the same priority. |br| Larger weights will be given a proportionately higher probability of being selected. |br| The range of this number is 0-65535. |br| In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. |br| See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "capacity_limit", "``integer``", "No", "No", "Maximum number of simultaneous calls for the trunk."
   "ringing_timeout", "``integer``", "No", "No", "Ring time in seconds. Supported values are integers from 1 to 32. If ``null``, the timeout is undefined. |br| If the call is not connected within this time, the transaction is ended with the disconnect code **Ringing timeout**."
   "name", "``string``", "No", "Yes", "Friendly name of the trunk."
   "cli_format", "``string``", "No", "No", "**RAW** - Do not alter CLI (default). |br| **E164** - Attempt to convert CLI to E.164 format. |br| **Local** - Attempt to convert CLI to Localized format. |br| **CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID**."
   "cli_prefix", "``string``", "No", "No", "You may prefix the CLI with an optional ``+`` sign followed by up to 6 characters, including digits and ``#``."
   "description", "``string``", "No", "No", "Optional description of the trunk."
   "configuration", "One of :ref:`sip_configurations <trunk_attributes_v33>`, |br| :ref:`pstn_configurations <trunk_attributes_v33>`", "N/A", "Yes", "Trunk configuration complex object."

.. _trunk_attrs_updt_v33:

Attributes Configuration
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``sip_configurations``", "No","Yes", "SIP configuration complex object. "
	   "attributes", ":ref:`sip_configuration_attributes <trunk_attributes_v33>`","No", "Yes", "SIP configuration attributes object."
    
   .. tab:: PSTN

	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``pstn_configurations``", "No","Yes", "PSTN configuration complex object."
	   "attributes", ":ref:`pstn_configuration_attributes <trunk_attributes_v33>`","No", "Yes", "PSTN configuration attributes object."

Configuration Attributes
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

	   "username", "``string``", "No", "Yes", "User part of R-URI in INVITE request. |br| You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. |br| For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format"
	   "host", "``string``", "No", "Yes", "Host part of R-URI in INVITE request."
	   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_, `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
	   "stir_shaken_mode", "``string``", "No", "No", "Stir/Shaken mode. |br| See :ref:`STIR/SHAKEN <service_did_stir_shaken>`  for more details. |br| Possible Values: |br| 'disabled' - Do not send identity |br| 'original' - Transit Identity header as is |br| 'pai' - Add PAI, P-Attestation-Indicator, P-Origination-ID |br| 'original_pai' - Transit Identity Header as is + Add PAI, P-Attestation Indicator, P-Origination-ID |br| 'verstat' - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID"
	   "auth_user", "``string``", "No", "No", "Optional authorization user for the SIP server."
	   "auth_password", "``string``", "No", "No", "Optional authorization password for the SIP server."
	   "auth_from_user", "``string``", "No", "No", "Specify user in a **from** field instead of CallerID (overrides CallerID). |br| Some equipment require **from**; to be equivalent to **Auth user**."
	   "auth_from_domain", "``string``", "No", "No", "Sets default **from** domain in SIP messages. Some equipment may require specific **From** Domain."
	   "sst_refresh_method_id", "``integer``", "No", "No", "SIP method which will be used for session update. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details. |br| Possible values: |br| 1 - Invite |br| 2 - Update |br| 3 - Update fallback Invite"
	   "sip_timer_b", "``integer``", "No", "No", "INVITE transaction timeout (Default 8000ms). |br| See `RFC 3261 Section 17.1.1.2 <https://tools.ietf.org/html/rfc3261#section-17.1.1.2>`_ for more details."
	   "dns_srv_failover_timer", "``integer``", "No", "No", "Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms)."
	   "rtp_ping", "``boolean``", "No", "No", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."
	   "rtp_timeout", "``integer``", "No", "No", "Disconnect the call if the RTP packets do not arrive within the specified time."
	   "allowed_rtp_ips", "Array of ``strings``", "No", "No", "The allowed RTP IPs. Array from 0 to 10 items: IPv4 or IPv6, single or subnet."
	   "sst_min_timer", "``integer``", "No", "No", "Minimal SIP Session timer value (Default 600 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_max_timer", "``integer``", "No", "No", "Maximal SIP Session timer value (Default 900 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_session_expires", "``integer``", "No", "No", "Session-Expires header value. Optional, should be in range with **sst_min_timer** and **sst_max_timer**. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "port", "``integer``", "No", "No", "Port part of R-URI in INVITE request (is not mandatory). |br| If port is null, SRV record will be resolved (or A record if SRV is unavailable)."
	   "rx_dtmf_format_id", "``integer``", "No", "No", "The method id for receiving DTMF signals from customers equipment. |br| Possible values: |br| 1 - RFC 2833 |br| 2 - SIP INFO application/dtmf-relay OR application/dtmf |br| 3 - RFC 2833 OR SIP INFO"
	   "tx_dtmf_format_id", "``integer``", "No", "No", "The method of sending DTMF signals to customers equipment. |br| Possible values: |br| 1 - Disable sending |br| 2 - RFC 2833 |br| 3 - SIP INFO application/dtmf-relay |br| 4 - SIP INFO application/dtmf"
	   "force_symmetric_rtp", "``boolean``", "No", "No", "Forced to work in Symmetric RTP / COMEDIA mode."
	   "symmetric_rtp_ignore_rtcp", "``boolean``", "No", "No", "Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. |br| Only RTP packets will be considered."
	   "sst_enabled", "``boolean``", "No", "No", "Enable SIP Session timers customization. |br| SIP session timers are used to make sure that a session (dialog) is still alive, |br| even though there may have been a long time since the last in-dialog message. |br| If the other end is not responding, the dialog will be hung up automatically. |br| SIP session timers need to be supported by all end points for it to work. |br| It’s a SIP extension, standardized by the IETF. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_accept_501", "``boolean``", "No", "No", "Do not drop the call after receiving SIP 501 response for non-critical messages."
	   "auth_enabled", "``boolean``", "No", "No", "Enable authorization for the SIP server."
	   "resolve_ruri", "``boolean``", "No", "No", "Replace host part of the R-URI by resolved IP address."
	   "rerouting_disconnect_code_ids", "``array``", "No", "No", ":ref:`Rerouting disconnect codes <disconnect_codes_v33>`."
	   "codec_ids", "``array``", "No", "No", ":ref:`Codecs <trunk_codecs_v33>`."
	   "transport_protocol_id", "``integer``", "No", "No", "The transport layer that will be responsible for the actual transmission of SIP requests and responses: |br| 1 - UDP |br| 2 - TCP |br| 3 - TLS."
	   "max_transfers", "``integer``", "No", "No", "Max count of the **REFER** requests."
	   "max_30x_redirects", "``integer``", "No", "No", "Max count of 301/302 redirects."

   .. tab:: PSTN

        .. csv-table::
            :header: "Name", "Type","Nullable", "Is Required?", "Description"

            "dst", "``string``", "No","Yes", "Phone number's."

Examples
========

.. tabs::

    .. tab:: SIP
   
        .. http:example:: curl

            PATCH /v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
        
            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "voice_in_trunks",
                "attributes": {
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "new_username"
                    }
                  }
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "new_username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/pop"
                    }
                  }
                }
              }
            }      
            
    .. tab:: PSTN
   
        .. http:example:: curl

            PATCH /v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
            
            {
              "data": {
                "id": "989d8259-9c4f-4449-97b7-a3480b1cffff",
                "type": "voice_in_trunks",
                "attributes": {
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "7xxxxxxxx"
                    }
                  }
                }
              }
            }
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "989d8259-9c4f-4449-97b7-a3480b1cffff",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 5,
                  "weight": 65535,
                  "name": "Office Mobile",
                  "cli_format": "e164",
                  "cli_prefix": null,
                  "description": null,
                  "ringing_timeout": null,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "7xxxxxxxx"
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/vocie_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/pop"
                    }
                  }
                }
              }
            }

            
    .. tab:: SIP with POP
   
        .. http:example:: curl

            PATCH /v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d?include=pop HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]             
            
            {
              "data": {
                "id": "081ad751-d790-4e70-9c92-7c18f6b50a6d",
                "type": "voice_in_trunks",
                "attributes": {
                  "name": "New trunk"
                },
                "relationships": {
                  "pop": {
                    "data": {
                      "type": "pops",
                      "id": "cb5ea690-e3a3-4781-a4f3-3bd0123284dd"
                    }
                  }
                }
              }
            }
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "081ad751-d790-4e70-9c92-7c18f6b50a6d",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "New trunk",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/pop"
                    },
                    "data": {
                      "type": "pops",
                      "id": "cb5ea690-e3a3-4781-a4f3-3bd0123284dd"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "cb5ea690-e3a3-4781-a4f3-3bd0123284dd",
                  "type": "pops",
                  "attributes": {
                    "name": "US, NY"
                  }
                }
              ]
            }

    .. tab:: SIP with all rerouting disconnect codes

        .. http:example:: curl

            PATCH /v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "trunks",
                "attributes": {
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "rerouting_disconnect_code_ids": [
                        56,
                        57,
                        58,
                        59,
                        60,
                        64,
                        65,
                        66,
                        67,
                        68,
                        69,
                        70,
                        71,
                        72,
                        73,
                        74,
                        75,
                        76,
                        77,
                        78,
                        79,
                        80,
                        81,
                        82,
                        83,
                        84,
                        86,
                        87,
                        88,
                        89,
                        90,
                        91,
                        92,
                        96,
                        97,
                        98,
                        99,
                        100,
                        101,
                        102,
                        103,
                        104,
                        105,
                        106,
                        107,
                        108,
                        1505
                      ]
                    }
                  }
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "new_username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        56,
                        57,
                        58,
                        59,
                        60,
                        64,
                        65,
                        66,
                        67,
                        68,
                        69,
                        70,
                        71,
                        72,
                        73,
                        74,
                        75,
                        76,
                        77,
                        78,
                        79,
                        80,
                        81,
                        82,
                        83,
                        84,
                        86,
                        87,
                        88,
                        89,
                        90,
                        91,
                        92,
                        96,
                        97,
                        98,
                        99,
                        100,
                        101,
                        102,
                        103,
                        104,
                        105,
                        106,
                        107,
                        108,
                        1505
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0
                    }
                  }
                },
                "relationships": {
                  "trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/trunk_group",
                      "related": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/pop",
                      "related": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/pop"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }
            
Other Responses
===============
            
.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 
            
            
            


.. |br| raw:: html

   <br />

.. _voice_in_trunk_object_v33:

=====================
Voice IN Trunk Object
=====================

Json API object with type ``voice_in_trunks``. You can get several type of trunks: SIP, PSTN.

Request
=======

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "priority","``integer``","The priority of this target host. |br| DIDWW will attempt to contact the target trunk with the lowest-numbered priority; |br| target trunk with the same priority will be tried in an order defined by the weight field. |br| The range is 0-65535. See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "weight","``integer``","A trunk selection mechanism. |br| The weight field specifies a relative weight for entries with the same priority. |br| Larger weights will be given a proportionately higher probability of being selected. |br| The range of this number is 0-65535. |br| In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. |br| See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "capacity_limit", "``integer``","Maximum number of simultaneous calls for the trunk."
   "ringing_timeout", "``integer``","After which it will be end transaction with internal disconnect code **Ringing timeout** if the call was not connected."
   "name", "``string``","Friendly name of the trunk."
   "cli_format", "``string``","**raw** - Do not alter CLI (default). |br| **e164** - Attempt to convert CLI to E.164 format. |br| **local** - Attempt to convert CLI to Localized format. |br| **CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID**."
   "cli_prefix", "``string``","You may prefix the CLI with an optional ``+`` sign followed by up to 6 characters, including digits and ``#``."
   "description", "``string``","Optional description of the trunk."
   "configuration", "One of :ref:`sip_configurations <trunk_attributes_v33>`, |br| :ref:`pstn_configurations <trunk_attributes_v33>`","Trunk configuration complex object."
   "created_at","DateTime","Trunk created at DateTime"

.. _trunk_attrs_objc_v33:

Attributes Configuration
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``sip_configurations``", "No","Yes", "SIP configuration complex object. "
	   "attributes", ":ref:`sip_configuration_attributes <trunk_attributes_v33>`","No", "Yes", "SIP configuration attributes object."
    
   .. tab:: PSTN

	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``pstn_configurations``", "No","Yes", "PSTN configuration complex object."
	   "attributes", ":ref:`pstn_configuration_attributes <trunk_attributes_v33>`","No", "Yes", "PSTN configuration attributes object."

Configuration Attributes
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

	   "username", "``string``", "No", "Yes", "User part of R-URI in INVITE request. |br| You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. |br| For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format"
	   "host", "``string``", "No", "Yes", "Host part of R-URI in INVITE request."
	   "transport_protocol_id", "``integer``", "No", "No", "Transport protocol ID. Possible values: |br| 1 - UDP |br| 2 - TCP |br| 3 - TLS"
	   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_, `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
	   "stir_shaken_mode", "``string``", "No", "No", "Stir/Shaken mode. |br| See :ref:`STIR/SHAKEN <service_did_stir_shaken>`  for more details. |br| Possible Values: |br| 'disabled' - Do not send identity |br| 'original' - Transit Identity header as is |br| 'pai' - Add PAI, P-Attestation-Indicator, P-Origination-ID |br| 'original_pai' - Transit Identity Header as is + Add PAI, P-Attestation Indicator, P-Origination-ID |br| 'verstat' - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID"
	   "auth_user", "``string``", "No", "No", "Optional authorization user for the SIP server."
	   "auth_password", "``string``", "No", "No", "Optional authorization password for the SIP server."
	   "auth_from_user", "``string``", "No", "No", "Specify user in a **from** field instead of CallerID (overrides CallerID). |br| Some equipment require **from**; to be equivalent to **Auth user**."
	   "auth_from_domain", "``string``", "No", "No", "Sets default **from** domain in SIP messages. Some equipment may require specific **From** Domain."
	   "sst_refresh_method_id", "``integer``", "No", "No", "SIP method which will be used for session update. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details. |br| Possible values: |br| 1 - Invite |br| 2 - Update |br| 3 - Update fallback Invite"
	   "sip_timer_b", "``integer``", "No", "No", "INVITE transaction timeout (Default 8000ms). |br| See `RFC 3261 Section 17.1.1.2 <https://tools.ietf.org/html/rfc3261#section-17.1.1.2>`_ for more details."
	   "dns_srv_failover_timer", "``integer``", "No", "No", "Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms)."
	   "rtp_ping", "``boolean``", "No", "No", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."
	   "rtp_timeout", "``boolean``", "No", "No", "Disconnect the call if the RTP packets do not arrive within the specified time."
	   "allowed_rtp_ips", "Array of ``strings``", "No", "No", "The allowed RTP IPs. Array from 0 to 10 items: IPv4 or IPv6, single or subnet."
	   "sst_min_timer", "``integer``", "No", "No", "Minimal SIP Session timer value (Default 600 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_max_timer", "``integer``", "No", "No", "Maximal SIP Session timer value (Default 900 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_session_expires", "``integer``", "No", "No", "Session-Expires header value. Optional, should be in range with **sst_min_timer** and **sst_max_timer**. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "port", "``integer``", "No", "No", "Port part of R-URI in INVITE request (is not mandatory). |br| If port is null, SRV record will be resolved (or A record if SRV is unavailable)."
	   "rx_dtmf_format_id", "``integer``", "No", "No", "The method id for receiving DTMF signals from customers equipment. |br| Possible values: |br| 1 - RFC 2833 |br| 2 - SIP INFO application/dtmf-relay OR application/dtmf |br| 3 - RFC 2833 OR SIP INFO"
	   "tx_dtmf_format_id", "``integer``", "No", "No", "The method of sending DTMF signals to customers equipment. |br| Possible values: |br| 1 - Disable sending |br| 2 - RFC 2833 |br| 3 - SIP INFO application/dtmf-relay |br| 4 - SIP INFO application/dtmf"
	   "force_symmetric_rtp", "``boolean``", "No", "No", "Forced to work in Symmetric RTP / COMEDIA mode."
	   "symmetric_rtp_ignore_rtcp", "``boolean``", "No", "No", "Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. |br| Only RTP packets will be considered."
	   "sst_enabled", "``boolean``", "No", "No", "Enable SIP Session timers customization. |br| SIP session timers are used to make sure that a session (dialog) is still alive, |br| even though there may have been a long time since the last in-dialog message. |br| If the other end is not responding, the dialog will be hung up automatically. |br| SIP session timers need to be supported by all end points for it to work. |br| It’s a SIP extension, standardized by the IETF. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_accept_501", "``boolean``", "No", "No", "Do not drop the call after receiving SIP 501 response for non-critical messages."
	   "auth_enabled", "``boolean``", "No", "No", "Enable authorization for the SIP server."
	   "resolve_ruri", "``boolean``", "No", "No", "Replace host part of the R-URI by resolved IP address."
	   "rerouting_disconnect_code_ids", "``array``", "No", "No", ":ref:`Rerouting disconnect codes <disconnect_codes_v33>`."
	   "codec_ids", "``array``", "No", "No", ":ref:`Codecs <trunk_codecs_v33>`"
	   "transport_protocol_id", "``integer``", "No", "No", "The transport layer that will be responsible for the actual transmission of SIP requests and responses (1 - UDP, 2 - TCP)."
	   "max_transfers", "``integer``", "No", "No", "Max count of the **REFER** requests."
	   "max_30x_redirects", "``integer``", "No", "No", "Max count of 301/302 redirects."
	   
   .. tab:: PSTN

	.. csv-table::
		:header: "Name", "Type","Nullable", "Is Required?", "Description"
		
		"dst", "``string``", "No","Yes", "Phone number's."



.. |br| raw:: html

   <br />

.. _voice_in_trunk_groups_v33:

====================
Voice IN Trunk Group
====================

Returns the details of a trunk group. Allows create, edit or delete a trunk group. 

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``. 

.. toctree::
  :maxdepth: 1
  
  get-trunk-group.rst
  get-trunk-groups.rst
  create-trunk-group.rst
  update-trunk-group.rst
  delete-trunk-group.rst
  trunk-group-object.rst
  
  
  




========================
Get Voice IN Trunk Group
========================

Returns a single Voice IN Trunk Group.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunk_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk Group."
   "include","``string``","No",":ref:`Inclusion <api_includes>`. "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunks", ":ref:`List of Trunk Objects <voice_in_trunk_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
      
   
            GET /v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
               
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "418fe352-04b8-4e03-a7ce-cb57efd8c664",
                "type": "voice_in_trunk_groups",
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664"
                },
                "attributes": {
                  "created_at": "2017-06-25T14:56:31.513Z",
                  "name": "Common Group",
                  "capacity_limit": 69
                },
                "relationships": {
                  "voice_in_trunks": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664/relationships/voice_in_trunks",
                      "related": "https://api.didww.com/v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664/voice_in_trunks"
                    }
                  }
                },
                "meta": {
                  "trunks_count": 1
                }
              }
            }
        
   .. tab:: Included Trunks
     
      .. http:example:: curl
   
            GET /v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae?include=voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "465b059a-b4a2-4c8e-ab3b-33dc60e096ae",
                "type": "voice_in_trunk_groups",
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae"
                },
                "attributes": {
                  "created_at": "2017-06-25T14:56:31.513Z",
                  "name": "Common Group",
                  "capacity_limit": 69
                },
                "relationships": {
                  "voice_in_trunks": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae/relationships/voice_in_trunks",
                      "related": "https://api.didww.com/v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae/voice_in_trunks"
                    },
                    "data": [
                      {
                        "type": "voice_in_trunks",
                        "id": "87133f4d-4a88-436b-b74b-b63e79318426"
                      }
                    ]
                  }
                },
                "meta": {
                  "trunks_count": 1
                }
              },
              "included": [
                {
                  "id": "87133f4d-4a88-436b-b74b-b63e79318426",
                  "type": "voice_in_trunks",
                  "attributes": {
                    "priority": 1,
                    "capacity_limit": 5,
                    "weight": 65535,
                    "name": "Office Mobile",
                    "cli_format": "e164",
                    "cli_prefix": null,
                    "description": null,
                    "ringing_timeout": null,
                    "configuration": {
                      "type": "pstn_configurations",
                      "attributes": {
                        "dst": "1xxxxxxxxx"
                      }
                    }
                  },
                  "relationships": {
                    "voice_in_trunk_group": {
                      "links": {
                        "self": "https://api.didww.com/v3/voice_in_trunks/87133f4d-4a88-436b-b74b-b63e79318426/relationships/voice_in_trunk_group",
                        "related": "https://api.didww.com/v3/voice_in_trunks/87133f4d-4a88-436b-b74b-b63e79318426/voice_in_trunk_group"
                      }
                    }
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




===========================
Create Voice IN Trunk Group
===========================

Creates a Trunk Group.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_in_trunk_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "include","``string``","No",":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
	:header: "Name", "Type","Nullable", "Is Required?", "Description"

	"name", "``string``", "No","Yes", "Unique name of the Trunk Group."
	"capacity_limit", "``integer``", "No","No", "Maximum number of simultaneous calls for the Trunk Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_in_trunks", ":ref:`To many <api_relationships>`", "Linkage for included trunks."

Examples
========

.. tabs::

   .. tab:: Simple Create
   
     .. http:example:: curl
   
        POST /v3/voice_in_trunk_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        {
          "data": {
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Main group",
              "capacity_limit": 100
            }
          }
        }
        
        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "a6370df6-86db-4a1a-9a54-3742f1d8615c",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/a6370df6-86db-4a1a-9a54-3742f1d8615c"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/a6370df6-86db-4a1a-9a54-3742f1d8615c/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/a6370df6-86db-4a1a-9a54-3742f1d8615c/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 0
            }
          }
        }        
        
        
   .. tab:: Create and Assign Trunks
   
     .. http:example:: curl
   
        POST /v3/voice_in_trunk_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "data": [
                  {
                    "type": "voice_in_trunks",
                    "id": "b7a9d1ce-6a89-4071-bc0d-486ee223787d"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "7ca415f8-8342-427a-bbfc-171b995f75d6"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "46aa9cac-a8dd-4a06-82db-cb0731e53ba0"
                  }
                ]
              }
            }
          }
        }        
        
        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "faea735d-ba77-40ef-bf13-f4dfc0f43a68",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/faea735d-ba77-40ef-bf13-f4dfc0f43a68"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/faea735d-ba77-40ef-bf13-f4dfc0f43a68/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/faea735d-ba77-40ef-bf13-f4dfc0f43a68/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 3
            }
          }
        }
        
   .. tab:: Create and Assign Trunk + Include Trunks in Response
   
     .. http:example:: curl
   
        POST /v3/voice_in_trunk_groups?include=voice_in_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        {
          "data": {
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "data": [
                  {
                    "type": "voice_in_trunks",
                    "id": "1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "c606cd05-a19f-4d3c-9362-3857a79a6e1d"
                  }
                ]
              }
            }
          }
        }
        
        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "3b49216d-ccb0-4376-b9fa-a43ffcb48c35",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/3b49216d-ccb0-4376-b9fa-a43ffcb48c35"
            },
            "attributes": {
              "created_at": "2017-08-16T14:04:36.013Z",
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/3b49216d-ccb0-4376-b9fa-a43ffcb48c35/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/3b49216d-ccb0-4376-b9fa-a43ffcb48c35/voice_in_trunks"
                },
                "data": [
                  {
                    "type": "voice_in_trunks",
                    "id": "1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "c606cd05-a19f-4d3c-9362-3857a79a6e1d"
                  }
                ]
              }
            },
            "meta": {
              "trunks_count": 2
            }
          },
          "included": [
            {
              "data": {
                "id": "1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7",
                "type": "voice_in_trunks",
            "attributes": {
                "priority": 1,
                "capacity_limit": 2,
                "weight": 65535,
                "name": "Office PSTN",
                "cli_format": "e164",
                "cli_prefix": null,
                "description": null,
                "ringing_timeout": null,
                "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                        "dst": "18337249999"
                      ]
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7/voice_in_trunk_group"
                    }
                  }
                }
              }
            },
            {
              "data": {
                "id": "c606cd05-a19f-4d3c-9362-3857a79a6e1d",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 18,
                  "weight": 65535,
                  "name": "Office sip",
                  "cli_format": "e164",
                  "cli_prefix": "+1",
                  "description": null,
                  "ringing_timeout": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "dst": "1xxxxxxxxx",
                      "host": "example.com",
                      "port": null,
                      "codec_ids": [
                        9,
                        6
                      ]
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/c606cd05-a19f-4d3c-9362-3857a79a6e1d/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/c606cd05-a19f-4d3c-9362-3857a79a6e1d/voice_in_trunk_group"
                    }
                  }
                }
              }
            }
          ]
        } 

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>` "
   "401","No",":ref:`Unauthorized <api_key>`" 




===========================
Delete Voice IN Trunk Group
===========================

Deletes a Trunk Group.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/voice_in_trunk_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk Group."

Example
=======

.. http:example:: curl

    DELETE https://api.didww.com/v3/voice_in_trunk_groups/1156df17-bcea-4c9a-9c1d-29320e288c03 HTTP/1.1
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 





=========================
Get Voice IN Trunk Groups
=========================

Returns a collection of Trunk Groups.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunk_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>` "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunks", ":ref:`Trunk Object <voice_in_trunk_object_v33>`"

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by: "

   "name", "The ``name`` field. "
   "created_at", "The ``created_at`` field. "
   "capacity_limit", "The ``capacity_limit`` field. "

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns: "

   "name", "The ``name`` attribute. "
   "created_at", "The ``created_at`` attribute. "
   "capacity_limit", "The ``capacity_limit`` attribute. "
   

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/voice_in_trunk_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "65b401cb-42f5-4911-877d-dc317a46b478",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/65b401cb-42f5-4911-877d-dc317a46b478"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "name": "Common Group",
                "capacity_limit": 69
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/65b401cb-42f5-4911-877d-dc317a46b478/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/65b401cb-42f5-4911-877d-dc317a46b478/voice_in_trunks"
                  }
                }
              },
              "meta": {
                "trunks_count": 1
              }
            },
            {
              "id": "72a60b4a-affb-46c7-8a8a-7e042c7611e8",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/72a60b4a-affb-46c7-8a8a-7e042c7611e8"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "name": "Custom Group",
                "capacity_limit": 50
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/72a60b4a-affb-46c7-8a8a-7e042c7611e8/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/72a60b4a-affb-46c7-8a8a-7e042c7611e8/voice_in_trunks"
                  }
                }
              },
              "meta": {
                "trunks_count": 0
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/voice_in_trunk_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/voice_in_trunk_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Included Trunks
   
    .. http:example:: curl
   
        GET /v3/voice_in_trunk_groups?include=voice_in_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "a8176983-61c4-4768-b699-10d5f3245d90",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/a8176983-61c4-4768-b699-10d5f3245d90"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "name": "Common Group",
                "capacity_limit": 69
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/a8176983-61c4-4768-b699-10d5f3245d90/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/a8176983-61c4-4768-b699-10d5f3245d90/voice_in_trunks"
                  },
                  "data": [
                    {
                      "type": "voice_in_trunks",
                      "id": "5aa0b0ea-2bda-4424-a93c-104829d72c06"
                    }
                  ]
                }
              },
              "meta": {
                "trunks_count": 1
              }
            },
            {
              "id": "def3b7b1-ce76-420d-9684-8dbdb69e17c1",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/def3b7b1-ce76-420d-9684-8dbdb69e17c1"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "name": "Custom Group",
                "capacity_limit": 50
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/def3b7b1-ce76-420d-9684-8dbdb69e17c1/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/def3b7b1-ce76-420d-9684-8dbdb69e17c1/voice_in_trunks"
                  },
                  "data": [
        
                  ]
                }
              },
              "meta": {
                "trunks_count": 0
              }
            }
          ],
          "included": [
            {
              "id": "5aa0b0ea-2bda-4424-a93c-104829d72c06",
              "type": "voice_in_trunks",
              "attributes": {
                "priority": 1,
                "capacity_limit": 5,
                "weight": 65535,
                "name": "Office Mobile",
                "cli_format": "e164",
                "cli_prefix": null,
                "description": null,
                "ringing_timeout": null,
                "configuration": {
                  "type": "pstn_configurations",
                  "attributes": {
                    "dst": "1xxxxxxxxx"
                  }
                }
              },
              "relationships": {
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunks/5aa0b0ea-2bda-4424-a93c-104829d72c06/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/voice_in_trunks/5aa0b0ea-2bda-4424-a93c-104829d72c06/voice_in_trunk_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/voice_in_trunk_groups?include=voice_in_trunks&page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/voice_in_trunk_groups?include=voice_in_trunks&page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 



.. _voice_in_trunk_group_object_v33:

===========================
Voice IN Trunk Group Object
===========================

Trunk Group Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Trunk Group name."
   "capacity_limit", "``integer``", "Maximum number of simultaneous calls for the Trunk Group."
   "created_at", "``DateTime``", "Trunk Group creation date and time."




===========================
Update Voice IN Trunk Group
===========================

Updates a Trunk Group.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/voice_in_trunk_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk Group."
   "include","``string``","No",":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
	:header: "Name", "Type","Nullable", "Is Required?", "Description"

	"name", "``string``", "No","Yes", "Unique name of the Trunk Group."
	"capacity_limit", "``integer``", "No","No", "Maximum number of simultaneous calls for the Trunk Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_in_trunks", ":ref:`To many <api_relationships>`", "Linkage for included trunks."

Examples
========

.. tabs::

   .. tab:: Simple Update
   
     .. http:example:: curl
   
        PATCH /v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        {
          "data": {
            "id": "43deb3aa-674a-465e-ac16-fb3084325ec7",
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Renamed group",
              "capacity_limit": 1
            }
          }
        }
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "43deb3aa-674a-465e-ac16-fb3084325ec7",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "name": "Renamed group",
              "capacity_limit": 1
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 1
            }
          }
        }
        
   .. tab:: Remove Voice IN Trunks from the Group
   
     .. http:example:: curl
   
        PATCH /v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a",
            "type": "voice_in_trunk_groups",
            "relationships": {
              "voice_in_trunks": {
                "data": [
        
                ]
              }
            }
          }
        }        
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "name": "Common Group",
              "capacity_limit": 69
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 0
            }
          }
        }
        

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>` "
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _voice_out_trunks_v33:

================
Voice OUT Trunks
================

Returns a list of all of the voice out trunks configured by the account. Allows create, edit or delete a trunk. 

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. note:: Voice out trunk management via API is not enabled by default. For more information, please contact our sales team at sales@didww.com.

.. toctree::
  :maxdepth: 1
  
  get-voice-out-trunk.rst
  get-voice-out-trunks.rst
  create-voice-out-trunk.rst
  update-voice-out-trunk.rst
  delete-voice-out-trunk.rst
  voice-out-trunk-object.rst
  voice-out-trunk-regenerate-credentials.rst
  
  
  
  
  
  



===================
Get Voice OUT Trunk
===================

Returns a single Voice Out trunk owned by the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_out_trunks/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."
   "include","``string``","No",":ref:`Inclusion <api_includes>`. "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "DID", ":ref:`DIDs <did_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Fetch Outbound trunk

    .. http:example:: curl

        GET /v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
            "type": "voice_out_trunks",
            "attributes": {
              "allowed_sip_ips": [
                "0.0.0.0/0"
              ],
              "allowed_rtp_ips": [
                "0.0.0.0/0"
              ],
              "allow_any_did_as_cli": true,
              "status": "active",
              "on_cli_mismatch_action": "send_original_cli",
              "name": "Outbound trunk 1",
              "capacity_limit": 100,
              "username": "671******",
              "password": "3k0******",
              "created_at": "2022-05-10T18:59:28.875Z",
              "threshold_reached": false,
              "threshold_amount": "10000.0",
              "media_encryption_mode": "disabled",
              "default_dst_action": "allow_all",
              "dst_prefixes": [],
              "force_symmetric_rtp": false,
              "rtp_ping": false,
              "callback_url": null
            },
            "relationships": {
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753/relationships/dids",
                  "related": "https://api.didww.com/v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753/dids"
                }
              }
            },
            "meta": {
              "spent_amount": "0.0"
            }
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

======================
Create Voice OUT Trunk
======================

Creates a voice out trunk. 

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_out_trunks``

Body Parameters
---------------

.. csv-table::
   :header: "Name", "Type","Nullable", "Is Required?", "Description"

   "type", "``string``", "No","Yes", "Trunks "
   "attributes", "``object``","No", "Yes", "Trunk configuration complex object."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "No", "Yes", "The voice out trunk name."
   "allowed_sip_ips", "Array of ``strings``", "No", "Yes", "The allowed originating IPs. Array from 0 to 60 items: IP v4/v6 single or subnet."
   "allowed_rtp_ips", "Array of ``strings``", "Yes", "No", "The allowed RTP IPs. Array from 0 to 60 items: IP v4/v6 single or subnet."
   "on_cli_mismatch_action", "``string``", "No", "Yes", "Possible values are: send_original_cli - the system will pass the ``FROM`` header value to the termination gateway. reject_call - the system will reject the call if the ``FROM`` header value does not match any of the allowed DIDs. replace_cli - the system will replace the CLI with one of the allowed DIDs."
   "capacity_limit", "``integer``", "Yes", "No", "The capacity limit of the voice out trunk. Allowed values from 0 to 32767."
   "allow_any_did_as_cli", "``boolean``", "No", "No", "When set to ``True``, passed than DIDs relationship can not be set to explicit DIDs. if DIDs relationship is omitted in payload already linked DIDs will be automatically unassigned. Default value is ``False``."
   "status", "``string``", "No", "No", "Can be either: active or blocked. If set to ``null``, the default value is active."
   "threshold_amount", "``string``", "Yes", "No", "The outbound trunk 24 hour threshold limit. Can be from 0.0 to 100000.0."
   "default_dst_action", "``string``", "No", "No", "Can be either: allow_all or reject_all."
   "dst_prefixes", "Array of ``strings``", "Yes", "No", "The allowed destination prefixes."
   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_,  `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP  "
   "callback_url", "``string``", "Yes", "No", "Can be null or valid HTTP(s) URL."
   "force_symmetric_rtp", "``boolean``", "No", "No", "When set to ``True``, the trunk operates in Symmetric RTP/COMEDIA mode."
   "rtp_ping", "``boolean``", "No", "No", "When set to ``True``, RTP ping is used to establish the connection for a call."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`DIDs <dids_v33>`", "The DID numbers if ``allow_any_did_as_cli`` is set to ``false``."

Examples
========

.. tabs::

   .. tab:: Create trunk

    .. http:example:: curl

        POST /v3/voice_out_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "voice_out_trunks",
            "attributes": {
              "name": "Outbound trunk 11",
              "allowed_sip_ips": ["198.51.100.1"],
              "on_cli_mismatch_action": "send_original_cli",
              "capacity_limit": 100,
              "allow_any_did_as_cli": true,
              "status": "active",
              "threshold_amount": "9999.0",
              "default_dst_action": "allow_all",
              "dst_prefixes": ["23"],
              "media_encryption_mode": "disabled",
              "allowed_rtp_ips": ["198.51.100.1"],
              "force_symmetric_rtp": false,
              "rtp_ping": false
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "d471975a-c6ee-4f84-80f0-fad67c5e22b1",
            "type": "voice_out_trunks",
            "attributes": {
              "allowed_sip_ips": [
                "198.51.100.1/32"
              ],
              "allowed_rtp_ips": [
                "198.51.100.1/32"
              ],
              "allow_any_did_as_cli": true,
              "status": "active",
              "on_cli_mismatch_action": "send_original_cli",
              "name": "Outbound trunk 11",
              "capacity_limit": 100,
              "username": "euc******",
              "password": "6fw******",
              "created_at": "2021-12-02T07:17:40.125Z",
              "threshold_reached": false,
              "threshold_amount": "9999.0",
              "media_encryption_mode": "disabled",
              "default_dst_action": "allow_all",
              "dst_prefixes": [
                "23"
              ],
              "force_symmetric_rtp": false,
              "rtp_ping": false,
              "callback_url": null
            },
            "relationships": {
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_out_trunks/d471975a-c6ee-4f84-80f0-fad67c5e22b1/relationships/dids",
                  "related": "https://api.didww.com/v3/voice_out_trunks/d471975a-c6ee-4f84-80f0-fad67c5e22b1/dids"
                }
              }
            },
            "meta": {
              "spent_amount": "0.0"
            }
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }

   .. tab:: Callback

    .. http:example:: curl

        POST /v3/voice_out_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "voice_out_trunks",
            "attributes": {
              "name": "Outbound replace cli",
              "allowed_sip_ips": [
                "198.51.100.1"
              ],
              "on_cli_mismatch_action": "send_original_cli",
              "capacity_limit": 300,
              "allow_any_did_as_cli": true,
              "status": "blocked",
              "threshold_amount": "1000.0",
              "default_dst_action": "allow_all",
              "dst_prefixes": [
                "23",
                "45"
              ],
              "media_encryption_mode": "disabled",
              "allowed_rtp_ips": [
                "198.51.100.1"
              ],
              "force_symmetric_rtp": true,
              "callback_url": "http://example.com",
              "rtp_ping": true
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "138a6765-bd54-4814-8ce7-35adc524e1fb",
            "type": "voice_out_trunks",
            "attributes": {
              "allowed_sip_ips": [
                "198.51.100.1/32"
              ],
              "allowed_rtp_ips": [
                "198.51.100.1/32"
              ],
              "allow_any_did_as_cli": true,
              "status": "blocked",
              "on_cli_mismatch_action": "send_original_cli",
              "name": "Outbound replace cli",
              "capacity_limit": 300,
              "username": "p2********",
              "password": "88********",
              "created_at": "2022-01-12T18:13:55.417Z",
              "threshold_reached": false,
              "threshold_amount": "1000.0",
              "media_encryption_mode": "disabled",
              "default_dst_action": "allow_all",
              "dst_prefixes": [
                "23",
                "45"
              ],
              "force_symmetric_rtp": true,
              "rtp_ping": true,
              "callback_url": "http://example.com"
            },
            "relationships": {
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_out_trunks/138a6765-bd54-4814-8ce7-35adc524e1fb/relationships/dids",
                  "related": "https://api.didww.com/v3/voice_out_trunks/138a6765-bd54-4814-8ce7-35adc524e1fb/dids"
                }
              }
            },
            "meta": {
              "spent_amount": "0.0"
            }
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }

   .. tab:: Create trunk with "allow_any_did_as_cli": false, assigning allowed DID

    .. http:example:: curl

        POST /v3/voice_out_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "voice_out_trunks",
            "attributes": {
              "name": "Outbound trunk 100",
              "allowed_sip_ips": [
                "198.51.100.1"
              ],
              "on_cli_mismatch_action": "reject_call",
              "capacity_limit": 300,
              "allow_any_did_as_cli": false,
              "status": "active",
              "threshold_amount": "1000.0",
              "default_dst_action": "allow_all",
              "dst_prefixes": [],
              "media_encryption_mode": "disabled",
              "allowed_rtp_ips": [
                "198.51.100.1"
              ],
              "force_symmetric_rtp": false,
              "callback_url": "http://example.com",
              "rtp_ping": false
            },
            "relationships": {
              "dids": {
                "data": [
                  {
                    "type": "dids",
                    "id": "7a6c177d-a054-4c75-9b4c-b1596ed6fa25"
                  }
                ]
              }
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "2680024e-b2a1-4175-a1ec-8f40ea144e64",
                "type": "voice_out_trunks",
                "attributes": {
                    "allowed_sip_ips": [
                        "198.51.100.1/32"
                    ],
                    "allowed_rtp_ips": [
                        "198.51.100.1/32"
                    ],
                    "allow_any_did_as_cli": false,
                    "status": "active",
                    "on_cli_mismatch_action": "reject_call",
                    "name": "Outbound trunk 100",
                    "capacity_limit": 300,
                    "username": "ok********",
                    "password": "m1********",
                    "created_at": "2022-03-03T09:29:20.694Z",
                    "threshold_reached": false,
                    "threshold_amount": "1000.0",
                    "media_encryption_mode": "disabled",
                    "default_dst_action": "allow_all",
                    "dst_prefixes": [],
                    "force_symmetric_rtp": false,
                    "rtp_ping": false,
                    "callback_url": "http://example.com"
                },
                "relationships": {
                    "dids": {
                        "links": {
                            "self": "https://api.didww.com/v3/voice_out_trunks/2680024e-b2a1-4175-a1ec-8f40ea144e64/relationships/dids",
                            "related": "https://api.didww.com/v3/voice_out_trunks/2680024e-b2a1-4175-a1ec-8f40ea144e64/dids"
                        }
                    }
                },
                "meta": {
                    "spent_amount": "0.0"
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }
            
Other Responses
===============
            
.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`"     



======================
Delete Voice OUT Trunk
======================

Deletes the Trunk without possibility to retrieve.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/voice_out_trunks/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk."

Example
=======

.. http:example:: curl

    DELETE /v3/voice_out_trunks/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    




====================
Get Voice OUT Trunks
====================

Returns the collection of Voice Out Trunks.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_out_trunks``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``, ``boolean`` ", "No", ":ref:`Filtering <api_filters>`"
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>`"
   "pagination","``string``", "No", ":ref:`Pagination <api_pagination>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "name", "``string``", "Yes", "Yes", "The trunk ``name`` field."
   "name_contains", "``string``", "Yes", "Yes", "The ``name_contains`` field."
   "on_cli_mismatch_action", "``string``", "Yes", "Yes", "The ``on_cli_mismatch_action`` field. This filter accepts one or more `reject_call` or `send_original_cli`."
   "allow_any_did_as_cli", "``boolean``", "No", "No", "The ``allow_any_did_as_cli`` field."
   "status", "``string``", "No", "No", "The ``status`` field. Can be `active` or `blocked`."
   "threshold_reached", "``boolean``", "No", "No", "The ``threshold_reached`` field."
   "default_dst_action", "``string``", "No", "No", "The ``default_dst_action`` field. Can be `allow_all` or `reject_all`."
   "media_encryption_mode", "``string``", "No", "No", "The ``media_encryption_mode`` field. This filter accepts the following values: `srtp_sdes`, `srtp_dtls`, `zrtp`, `disabled`."
   
Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "The ``name`` field."
   "created_at", "The ``created_at`` field."
   "allow_any_did_as_cli", "The ``allow_any_did_as_cli`` field."
   "threshold_reached", "The ``threshold_reached`` field."

Example
=======

.. tabs::

   .. tab:: Fetch Outbound trunks

    .. http:example:: curl

        GET /v3/voice_out_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
                    "type": "voice_out_trunks",
                    "attributes": {
                        "allowed_sip_ips": [
                            "0.0.0.0/0"
                        ],
                        "allowed_rtp_ips": [
                            "0.0.0.0/0"
                        ],
                        "allow_any_did_as_cli": true,
                        "status": "active",
                        "on_cli_mismatch_action": "send_original_cli",
                        "name": "Outbound trunk 1",
                        "capacity_limit": 100,
                        "username": "****ff1onm",
                        "password": "****b4m55h",
                        "created_at": "2022-05-10T18:59:28.875Z",
                        "threshold_reached": false,
                        "threshold_amount": "10000.0",
                        "media_encryption_mode": "disabled",
                        "default_dst_action": "allow_all",
                        "dst_prefixes": [],
                        "force_symmetric_rtp": false,
                        "rtp_ping": false,
                        "callback_url": null
                    },
                    "relationships": {
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753/relationships/dids",
                                "related": "https://api.didww.com/v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753/dids"
                            }
                        }
                    },
                    "meta": {
                        "spent_amount": "0.0"
                    }
                },
                {
                    "id": "d471975a-c6ee-4f84-80f0-fad67c5e22b1",
                    "type": "voice_out_trunks",
                    "attributes": {
                        "allowed_sip_ips": [
                            "198.51.100.1/32"
                        ],
                        "allowed_rtp_ips": [
                            "198.51.100.1/32"
                        ],
                        "allow_any_did_as_cli": false,
                        "status": "active",
                        "on_cli_mismatch_action": "send_original_cli",
                        "name": "Outbound trunk 11",
                        "capacity_limit": 100,
                        "username": "****rh5vb",
                        "password": "****kmgnda",
                        "created_at": "2021-12-02T07:17:40.125Z",
                        "threshold_reached": false,
                        "threshold_amount": "9999.0",
                        "media_encryption_mode": "disabled",
                        "default_dst_action": "allow_all",
                        "dst_prefixes": [
                            "23"
                        ],
                        "force_symmetric_rtp": false,
                        "rtp_ping": false,
                        "callback_url": null
                    },
                    "relationships": {
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/voice_out_trunks/d471975a-c6ee-4f84-80f0-fad67c5e22b1/relationships/dids",
                                "related": "https://api.didww.com/v3/voice_out_trunks/d471975a-c6ee-4f84-80f0-fad67c5e22b1/dids"
                            }
                        }
                    },
                    "meta": {
                        "spent_amount": "0.0"
                    }
                }
            ],
            "meta": {
                "total_records": 2,
                "api_version": "2022-05-10"
            },
            "links": {
                "first": "https://api.didww.com/v3/voice_out_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/voice_out_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }


.. |br| raw:: html

   <br />

======================
Update Voice OUT Trunk
======================

Updates a Trunk.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/voice_out_trunks/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "No", "Yes", "The voice out trunk name."
   "allowed_sip_ips", "Array of ``strings``", "No", "Yes", "The allowed originating IPs. Array from 0 to 15 items: IP v4/v6 single or subnet."
   "allowed_rtp_ips", "Array of ``strings``", "Yes", "No", "The allowed RTP IPs. Array from 0 to 10 items: IP v4/v6 single or subnet."
   "on_cli_mismatch_action", "``string``", "No", "Yes", "Possible values are: send_original_cli - the system will pass the ``FROM`` header value to the termination gateway. reject_call - the system will reject the call if the ``FROM`` header value does not match any of the allowed DIDs. replace_cli - the system will replace the CLI with one of the allowed DIDs."
   "capacity_limit", "``integer``", "Yes", "No", "The capacity limit of the voice out trunk. Allowed values from 0 to 32767."
   "allow_any_did_as_cli", "``boolean``", "No", "No", "When set to ``True``, passed than DIDs relationship can not be set to explicit DIDs. if DIDs relationship is omitted in payload already linked DIDs will be automatically unassigned. Default value is ``False``."
   "status", "``string``", "No", "No", "Can be either: active or blocked. If set to ``null``, the default value is active."
   "threshold_amount", "``string``", "Yes", "No", "The outbound trunk 24 hour threshold limit. Can be from 0.0 to 100000.0."
   "default_dst_action", "``string``", "No", "No", "Can be either: allow_all or reject_all."
   "dst_prefixes", "Array of ``strings``", "Yes", "No", "The allowed destination prefixes."
   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_,  `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP  "
   "callback_url", "``string``", "Yes", "No", "Can be null or valid HTTP(s) URL."
   "force_symmetric_rtp", "``boolean``", "No", "No", "When set to ``True``, the trunk operates in Symmetric RTP/COMEDIA mode."
   "rtp_ping", "``boolean``", "No", "No", "When set to ``True``, RTP ping is used to establish the connection for a call."
   
Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`DIDs <dids_v33>`", "The DID numbers if ``allow_any_did_as_cli`` is set to ``false``."

Examples
========

.. tabs::

   .. tab:: Update trunk example

    .. http:example:: curl

        PATCH /v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
            "type": "voice_out_trunks",
            "attributes": {
              "name": "Outbound trunk 99",
              "allowed_sip_ips": [
                "198.51.100.1"
              ],
              "on_cli_mismatch_action": "send_original_cli",
              "capacity_limit": 300,
              "allow_any_did_as_cli": false,
              "status": "blocked",
              "threshold_amount": "1000.0",
              "default_dst_action": "allow_all",
              "dst_prefixes": [
                "23",
                "45"
              ],
              "media_encryption_mode": "disabled",
              "allowed_rtp_ips": [
                "198.51.100.1"
              ],
              "force_symmetric_rtp": true,
              "rtp_ping": true
            }
          }
        }

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
            "type": "voice_out_trunks",
            "attributes": {
              "allowed_sip_ips": [
                "198.51.100.1/32"
              ],
              "allowed_rtp_ips": [
                "198.51.100.1/32"
              ],
              "allow_any_did_as_cli": false,
              "status": "blocked",
              "on_cli_mismatch_action": "send_original_cli",
              "name": "Outbound trunk 99",
              "capacity_limit": 300,
              "username": "91********",
              "password": "zu********",
              "created_at": "2022-05-10T18:59:28.875Z",
              "threshold_reached": false,
              "threshold_amount": "1000.0",
              "media_encryption_mode": "disabled",
              "default_dst_action": "allow_all",
              "dst_prefixes": [
                "23",
                "45"
              ],
              "force_symmetric_rtp": true,
              "rtp_ping": true,
              "callback_url": null
            },
            "relationships": {
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753/relationships/dids",
                  "related": "https://api.didww.com/v3/voice_out_trunks/457bf47d-446d-41cd-91c3-dfbda7bf0753/dids"
                }
              }
            },
            "meta": {
              "spent_amount": "0.0"
            }
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }

   .. tab:: Setting DIDswhen "allow_any_did_as_cli": "false"

    .. http:example:: curl

        PATCH /v3/voice_out_trunks/291ef437-8896-4834-b0c2-eefaa0bbde98 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "id": "291ef437-8896-4834-b0c2-eefaa0bbde98",
            "type": "voice_out_trunks",
            "attributes": {
              "name": "Outbound trunk 99",
              "allowed_sip_ips": [
                "198.51.100.1"
              ],
              "on_cli_mismatch_action": "send_original_cli",
              "capacity_limit": 300,
              "allow_any_did_as_cli": true,
              "status": "blocked",
              "threshold_amount": "1000.0",
              "default_dst_action": "allow_all",
              "dst_prefixes": [
                "23",
                "45"
              ],
              "media_encryption_mode": "disabled",
              "allowed_rtp_ips": [
                "198.51.100.1"
              ],
              "force_symmetric_rtp": true,
              "callback_url": "http://example.com",
              "rtp_ping": true
            },
            "relationships": {
              "dids": {
                "data": [
                  {
                    "type": "dids",
                    "id": "7a6c177d-a054-4c75-9b4c-b1596ed6fa25"
                  }
                ]
              }
            }
          }
        }

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "291ef437-8896-4834-b0c2-eefaa0bbde98",
                "type": "voice_out_trunks",
                "attributes": {
                    "allowed_sip_ips": [
                        "198.51.100.1/32"
                    ],
                    "allowed_rtp_ips": [
                        "198.51.100.1/32"
                    ],
                    "allow_any_did_as_cli": false,
                    "status": "blocked",
                    "on_cli_mismatch_action": "send_original_cli",
                    "name": "Outbound trunk 99",
                    "capacity_limit": 300,
                    "username": "e1********",
                    "password": "ke********",
                    "created_at": "2022-03-03T08:21:48.322Z",
                    "threshold_reached": false,
                    "threshold_amount": "1000.0",
                    "media_encryption_mode": "disabled",
                    "default_dst_action": "allow_all",
                    "dst_prefixes": [
                        "23",
                        "45"
                    ],
                    "force_symmetric_rtp": true,
                    "rtp_ping": true,
                    "callback_url": "http://example.com"
                },
                "relationships": {
                    "dids": {
                        "links": {
                            "self": "https://api.didww.com/v3/voice_out_trunks/291ef437-8896-4834-b0c2-eefaa0bbde98/relationships/dids",
                            "related": "https://api.didww.com/v3/voice_out_trunks/291ef437-8896-4834-b0c2-eefaa0bbde98/dids"
                        }
                    }
                },
                "meta": {
                    "spent_amount": "0.0"
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }
 
Other Responses
===============
            
.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 
                 


.. |br| raw:: html

   <br />

.. _voice_out_trunk_object_v33:

======================
Voice OUT Trunk Object
======================

Json API object with type ``voice_out_trunks``. 

Request
=======

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "The name of the voice out trunk."
   "allowed_sip_ips", "Array of ``strings``", "The allowed origination IP list."
   "on_cli_mismatch_action", "``string``", "The call action on CLI mismatch. Possible values are: |br| send_original_cli - the system will pass the ``FROM`` header value to the termination gateway. |br| reject_call - the system will reject the call if the ``FROM`` header value does not match any of the allowed DIDs. |br| replace_cli - the system will replace the CLI with one of the allowed DIDs."
   "capacity_limit", "``integer``", "The capacity limit of the voice out trunk."
   "username", "``string``", "The username for digest `authentication method <https://datatracker.ietf.org/doc/html/rfc8760>`_."
   "password", "``string``", "The password for digest authentication method."
   "created_at", "``date&time``", "The date&time of trunk creation."
   "allow_any_did_as_cli", "``boolean``", "The option to enable all DIDs to be used as CLI for this voice out trunk."
   "status", "``string``", "The status of the voice out trunk. Can be active or blocked."
   "threshold_reached", "``boolean``", "The 24 hour limit indicator. If the threshold_amount has been reached during the 24 hours, this indicator will be ``true``."
   "threshold_amount", "``string``", "The 24 hour threshold limit."
   "default_dst_action", "``string``", "The default destination action. Possible values are: allow_all or reject_all."
   "dst_prefixes", "Array of ``strings``", "The destination prefixes to which calls will be allowed or disallowed based on the default_dst_action."
   "media_encryption_mode", "``string``", "Media encryption mode. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
   "callback_url", "``string``", "The callback URI. Can be null or valid HTTP(s) URL."
   "allowed_rtp_ips", "Array of ``strings``", "The allowed origination RTP IP list."
   "force_symmetric_rtp", "``boolean``", "Forced to work in Symmetric RTP / COMEDIA mode."
   "rtp_ping", "``boolean``", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."


.. |br| raw:: html

   <br />

.. _voice_out_regenerate_credentials_v33:

======================================
Voice OUT Trunk Regenerate Credentials
======================================

Regenerates the username and password of voice_out trunk with new random string 10 symbols each.

HTTP Method: ``POST``

URI Path: ``/v3/voice_out_trunk_regenerate_credentials``

Example
=======

.. tabs::

   .. tab:: Regenerate Credentials

    .. http:example:: curl

        POST /v3/voice_out_trunk_regenerate_credentials HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "voice_out_trunk_regenerate_credentials",
            "relationships": {
              "voice_out_trunk": {
                "data": {
                  "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
                  "type": "voice_out_trunks"
                }
              }
            }
          }
        }

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
            "type": "voice_out_trunk_regenerate_credentials"
          },
          "meta": {
            "api_version": "2022-05-10"
          }
        }



.. |br| raw:: html

   <br />

.. _capacity_pools_v33:

=============
Capacity Pool
=============

.. note::

    To get familiar with Capacity and its options, please read this article: :ref:`Flexible Capacity <flexible_capacity>`

Returns a single or a list of the Capacity Pools which includes information about channels quantity, supported Countries, Shared Capacity Groups. 

Supported methods: ``GET``, ``PATCH``.

.. toctree::
  :maxdepth: 1
  
  get-capacity-pool.rst
  get-capacity-pools.rst
  update-capacity-pool.rst
  capacity-pool-object.rst
  
  
  
  


=================
Get Capacity Pool
=================

Returns a single Capacity Pool.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/capacity_pools/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number allocated to this Capacity Pool."
   "include","``string``","No",":ref:`Inclusion <api_includes>`. "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "countries", ":ref:`Country Object <country_object_v33>`"
   "shared_capacity_groups", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v33>`"
   "qty_based_pricings", ":ref:`Quantity Based Price Object <quantity_based_price_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 10,
              "assigned_channels_count": 6,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                }
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                }
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          }
        }
        
   .. tab:: Include Countries
   
     .. http:example:: curl
   
        GET /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f?include=countries HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 10,
              "assigned_channels_count": 6,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                },
                "data": [
                  {
                    "type": "countries",
                    "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8"
                  },
                  {
                    "type": "countries",
                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                  }
                ]
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                }
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          },
          "included": [
            {
              "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8",
              "type": "countries",
              "attributes": {
                "name": "United Kingdom",
                "prefix": "44",
                "iso": "GB"
              }
            },
            {
              "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
              "type": "countries",
              "attributes": {
                "name": "United States",
                "prefix": "1",
                "iso": "US"
              }
            }
          ]
        }
        
   .. tab:: Include Shared Capacity Groups
   
     .. http:example:: curl
   
        GET /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f?include=shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 10,
              "assigned_channels_count": 6,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                }
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                },
                "data": [
                  {
                    "type": "shared_capacity_groups",
                    "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc"
                  }
                ]
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          },
          "included": [
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Sample group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ]
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _capacity_pool_object_v33:

====================
Capacity Pool Object
====================

Capacity Pool Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Name of the Capacity Pool."
   "renew_date", "``date``", "Channel renewal date."
   "total_channels_count", "``integer``", "Total number of channels in the Capacity Pool."
   "assigned_channels_count", "``integer``", "Number of channels used in Shared Capacity Groups and/or assigned to DID numbers."
   "minimum_limit", "``integer``", "Minimum number of channels to be kept in the Capacity Pool."
   "minimum_qty_per_order", "``integer``", "Minimum number of channels per Order."
   "setup_price", "``string``", "Non Recurring Cost (one-time activation fee)."
   "monthly_price", "``string``", "Monthly Recurring Cost (ongoing monthly fee)."
   "metered_rate", "``string``", "Metered channel price per minute."


==================
Get Capacity Pools
==================

Returns a list of Capacity Pools.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/capacity_pools``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``", "No", ":ref:`Filtering <api_filters>`"
   "include","``string``", "No", ":ref:`Inclusion <api_includes>` "
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>` "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "countries", ":ref:`Country Object <country_object_v33>`"
   "shared_capacity_groups", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v33>`"
   "qty_based_pricings", ":ref:`Quantity Based Price Object <quantity_based_price_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Capacity Pool ``id`` field. "

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by"

   "name", "The ``name`` field."
   "renew_date", "The ``renew_date`` field."
   "total_channels_count", "The ``total_channels_count`` field."
   "assigned_channels_count", "The ``assigned_channels_count`` field."
   "minimum_limit", "The ``minimum_limit`` field."
   "minimum_qty_per_order", "The ``minimum_qty_per_order`` field."
   "setup_price", "The ``setup_price`` field."
   "monthly_price", "The ``monthly_price`` field."
   "metered_rate", "The ``metered_rate`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns"

   "name", "The ``name`` attribute."
   "renew_date", "The ``renew_date`` attribute."
   "total_channels_count", "The ``total_channels_count`` attribute."
   "assigned_channels_count", "The ``assigned_channels_count`` attribute."
   "minimum_limit", "The ``minimum_limit`` attribute."
   "minimum_qty_per_order", "The ``minimum_qty_per_order`` attribute."
   "setup_price", "The ``setup_price`` attribute."
   "monthly_price", "The ``monthly_price`` attribute."
   "metered_rate", "The ``metered_rate`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/capacity_pools HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "ca1315c5-1915-4fc7-9441-de78e1f38ef9",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 136,
                "assigned_channels_count": 136,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "25.0",
                "monthly_price": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/qty_based_pricings"
                  }
                }
              }
            },
            {
              "id": "daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d",
              "type": "capacity_pools",
              "attributes": {
                "name": "Standard",
                "renew_date": "2018-07-21",
                "total_channels_count": 2,
                "assigned_channels_count": 2,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "15.0",
                "monthly_price": "15.0",
                "metered_rate": "0.01"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Include Countries
   
     .. http:example:: curl
   
        GET /v3/capacity_pools?include=countries HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "ca1315c5-1915-4fc7-9441-de78e1f38ef9",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 136,
                "assigned_channels_count": 136,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "25.0",
                "monthly_price": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/countries"
                  },
                  "data": [
                    {
                      "type": "countries",
                      "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8"
                    }
                  ]
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/qty_based_pricings"
                  }
                }
              }
            },
            {
              "id": "daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d",
              "type": "capacity_pools",
              "attributes": {
                "name": "Standard",
                "renew_date": "2018-07-21",
                "total_channels_count": 2,
                "assigned_channels_count": 2,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "15.0",
                "monthly_price": "15.0",
                "metered_rate": "0.01"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/countries"
                  },
                  "data": [
                    {
                      "type": "countries",
                      "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                    }
                  ]
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8",
              "type": "countries",
              "attributes": {
                "name": "United Kingdom",
                "prefix": "44",
                "iso": "GB"
              }
            },
            {
              "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
              "type": "countries",
              "attributes": {
                "name": "United States",
                "prefix": "1",
                "iso": "US"
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Include Shared Capacity Groups
   
     .. http:example:: curl
   
        GET /v3/capacity_pools?include=shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "ca1315c5-1915-4fc7-9441-de78e1f38ef9",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 136,
                "assigned_channels_count": 136,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "25.0",
                "monthly_price": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/shared_capacity_groups"
                  },
                  "data": [
                    {
                      "type": "shared_capacity_groups",
                      "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc"
                    }
                  ]
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/qty_based_pricings"
                  }
                }
              }
            },
            {
              "id": "daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d",
              "type": "capacity_pools",
              "attributes": {
                "name": "Standard",
                "renew_date": "2018-07-21",
                "total_channels_count": 2,
                "assigned_channels_count": 2,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "15.0",
                "monthly_price": "15.0",
                "metered_rate": "0.01"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Sample group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"



====================
Update Capacity Pool
====================

Allows to update the existing Capacity Pool. By using this endpoint it is possible to remove Unassigned Channels from the Capacity Pool.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/capacity_pools/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number allocated to this Capacity Pool."
   "include","``string``","No",":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Title", "Type", "Nullable", "Description"

   "total_channels_count", "``integer``","False", "Total number of channels in the Capacity Pool."

Examples
========

.. tabs::

   .. tab:: Sample 1
   
     .. http:example:: curl
   
        PATCH /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "total_channels_count": 8
            }
          }
        }
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 8,
              "assigned_channels_count": 7,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                }
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                }
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          }
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _shared_capacity_groups_v33:

=====================
Shared Capacity Group
=====================

.. note::

    To get familiar with Capacity and its options, please read this article: :ref:`Flexible Capacity <flexible_capacity>`

Returns a list of the Capacity Groups assigned to a Capacity Pool. Allows to create, edit or delete a shared capacity group. 

Supported methods: ``GET``,  ``POST``, ``PATCH``, ``DELETE``. 

.. toctree::
  :maxdepth: 1
  
  get-shared-capacity-group.rst
  get-shared-capacity-groups.rst
  create-shared-capacity-group.rst
  update-shared-capacity-group.rst
  delete-shared-capacity-group.rst
  shared-capacity-group-object.rst
  
  
  


=========================
Get Shared Capacity Group
=========================

Returns a single Channels Group.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/shared_capacity_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number allocated to this Shared Capacity Group."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`A list of Shared Capacity Group objects <did_object_v33>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample group",
              "shared_channels_count": 3,
              "created_at": "2018-06-19T11:41:21.644Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }
        
   .. tab:: Include DIDs
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e?include=dids HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample group",
              "shared_channels_count": 3,
              "created_at": "2018-06-19T11:41:21.644Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                },
                "data": [
                  {
                    "type": "dids",
                    "id": "44957076-778a-4802-b60c-d22db0cda284"
                  }
                ]
              }
            },
            "included": [
              {
                "id": "44957076-778a-4802-b60c-d22db0cda284",
                "type": "dids",
                "attributes": {
                  "blocked": false,
                  "capacity_limit": 1,
                  "description": "string",
                  "terminated": false,
                  "awaiting_registration": false,
                  "number": "437xxxxxxxxx",
                  "expires_at": "2017-06-25T08:21:41.795Z",
                  "channels_included_count": 2,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "pending_removal": false,
                  "dedicated_channels_count": 0
                },
                "relationships": {
                  "did_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/did_group",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/did_group"
                    }
                  },
                  "order": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/order",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/order"
                    }
                  },
                  "voice_in_trunk": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk"
                    }
                  },
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk_group"
                    }
                  },
                  "capacity_pool": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/capacity_pool",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/capacity_pool"
                    }
                  },
                  "shared_capacity_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/shared_capacity_group",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/shared_capacity_group"
                    }
                  }
                }
              }
            ]
          }
        }
        
   .. tab:: Include Capacity Pool
   
     .. http:example:: curl
     
        GET /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e?include=capacity_pool HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]    
  
  
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample group",
              "shared_channels_count": 3,
              "created_at": "2018-06-19T11:41:21.644Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                },
                "data": {
                  "type": "capacity_pools",
                  "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            },
            "included": [
              {
                "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
                "type": "capacity_pools",
                "attributes": {
                  "name": "Extended",
                  "renew_date": "2018-07-21",
                  "total_channels_count": 10,
                  "unassigned_channels_count": 4,
                  "assigned_channels_count": 6,
                  "minimum_limit": 5,
                  "minimum_qty_per_order": 1,
                  "nrc": "0.0",
                  "mrc": "25.0",
                  "metered_rate": "0.02"
                },
                "relationships": {
                  "countries": {
                    "links": {
                      "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                      "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                    }
                  },
                  "shared_capacity_groups": {
                    "links": {
                      "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                      "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                    }
                  },
                  "qty_based_pricings": {
                    "links": {
                      "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                      "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                    }
                  }
                }
              }
            ]
          }
        }      
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



=============================
Create Shared Capacity Groups
=============================

Creates a Shared Capacity Group.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/shared_capacity_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "False", "Yes", "Unique name of Shared Capacity Group."
   "shared_channels_count", "``integer``", "False", "No", "Unassigned channels quantity to assign to the Shared Capacity Group from the Capacity Pool."
   "metered_channels_count", "``integer``", "False", "No", "Metered channels quantity to assign to the Shared Capacity Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`To Many <api_relationships>`", "Linkage for included dids."
   "capacity_pool", ":ref:`To one <api_relationships>`", "Linkage for included capacity_pool."

Examples
========

.. tabs::

   .. tab:: Simple Create
   
     .. http:example:: curl
   
        POST /v3/shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "metered_channels_count": 5,
              "shared_channels_count": 3
            },
            "relationships": {
              "capacity_pool": {
                "data": {
                  "type": "capacity_pools",
                  "id": "1e9e4362-bc5c-47f3-a2bb-c17afa66f3fa"
                }
              }
            }
          }
        }

     
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }
        
   .. tab:: Create and Assign DIDs
   
     .. http:example:: curl
   
        POST /v3/shared_capacity_groups?include=dids HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "metered_channels_count": 5,
              "shared_channels_count": 3
            },
            "relationships": {
              "capacity_pool": {
                "data": {
                  "type": "capacity_pools",
                  "id": "1e9e4362-bc5c-47f3-a2bb-c17afa66f3fa"
                }
              },
              "dids": {
                "data": [
                  {
                    "type": "dids",
                    "id": "091b6984-07f7-4eca-a42c-f1856248d646"
                  },
                  {
                    "type": "dids",
                    "id": "88b0e9a1-5d8e-4737-8f31-43f0b2aa2861"
                  }
                ]
              }
            }
          }
        }

        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        } 
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



============================
Delete Shared Capacity Group
============================

Deletes a Shared Capacity Group.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/shared_capacity_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number allocated to this Shared Capacity Group."

Example
=======

.. http:example:: curl

    DELETE /v3/shared_capacity_groups/1156df17-bcea-4c9a-9c1d-29320e288c03 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
        
        
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json

                

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 



==========================
Get Shared Capacity Groups
==========================

Returns a collection of Shared Capacity Groups.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/shared_capacity_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`A list of Shared Capacity Group objects <did_object_v33>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "name", "``string``", "Yes", "Yes", "Shared Capacity Group ``name`` field."
   "capacity_pool.id", "``string``", "Yes", "Yes", "The ``capacity_pool.id`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "name", "The ``name`` attribute."
   "shared_channels_count", "The ``shared_channels_count`` attribute."
   "metered_channels_count", "The ``metered_channels_count`` attribute."
   "created_at", "The ``created_at`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "8a581244-de83-4c46-ac0a-32659279169e",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Mixed group",
                "shared_channels_count": 3,
                "created_at": "2018-06-20T08:48:47.811Z",
                "metered_channels_count": 5
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/dids"
                  }
                }
              }
            },
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Metered group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Include DIDs
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups?include=dids HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "8a581244-de83-4c46-ac0a-32659279169e",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Mixed group",
                "shared_channels_count": 3,
                "created_at": "2018-06-20T08:48:47.811Z",
                "metered_channels_count": 5
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/dids"
                  },
                  "data": [
                    {
                      "type": "dids",
                      "id": "44957076-778a-4802-b60c-d22db0cda284"
                    }
                  ]
                }
              }
            },
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Metered group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "44957076-778a-4802-b60c-d22db0cda284",
              "type": "dids",
              "attributes": {
                "blocked": false,
                "capacity_limit": 1,
                "description": "string",
                "terminated": false,
                "awaiting_registration": false,
                "number": "437xxxxxxxxx",
                "expires_at": "2017-06-25T08:21:41.795Z",
                "channels_included_count": 2,
                "created_at": "2017-06-25T08:21:41.795Z",
                "pending_removal": false,
                "dedicated_channels_count": 0
              },
              "relationships": {
                "did_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/did_group",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/did_group"
                  }
                },
                "order": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/order",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/order"
                  }
                },
                "voice_in_trunk": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk"
                  }
                },
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk_group"
                  }
                },
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/capacity_pool"
                  }
                },
                "shared_capacity_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/shared_capacity_group",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/shared_capacity_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }        
        
   .. tab:: Include Capacity Pool
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups?include=capacity_pool HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "8a581244-de83-4c46-ac0a-32659279169e",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Mixed group",
                "shared_channels_count": 3,
                "created_at": "2018-06-20T08:48:47.811Z",
                "metered_channels_count": 5
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/capacity_pool"
                  },
                  "data": {
                    "type": "capacity_pools",
                    "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/dids"
                  }
                }
              }
            },
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Metered group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 10,
                "unassigned_channels_count": 4,
                "assigned_channels_count": 6,
                "minimum_limit": 5,
                "minimum_qty_per_order": 1,
                "nrc": "0.0",
                "mrc": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _shared_capacity_group_object_v33:

============================
Shared Capacity Group Object
============================

Shared Capacity Group Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Shared Capacity Group name."
   "metered_channels_count", "``integer``", "Metered channels quantity in Shared Capacity Group."
   "shared_channels_count", "``integer``", "Shared channels quantity in Shared Capacity Group."
   "created_at", "``DateTime``", "Shared Capacity Group creation date and time."




=============================
Update Shared Capacity Groups
=============================

Updates a Shared Capacity Group.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/shared_capacity_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "False", "Yes", "Unique name of Shared Capacity Group."
   "shared_channels_count", "``integer``", "False", "No", "Unassigned channels quantity to assign to the Shared Capacity Group from the Capacity Pool."
   "metered_channels_count", "``integer``", "False", "No", "Metered channels quantity to assign to the Shared Capacity Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`To Many <api_relationships>`", "Linkage for included dids."
   "capacity_pool", ":ref:`To one <api_relationships>`", "Linkage for included capacity_pool."

Examples
========

.. tabs::

   .. tab:: Simple Update
   
     .. http:example:: curl
   
        PATCH /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group"
            }
          }
        }

     
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }

   .. tab:: Update and Assign DIDs

     .. http:example:: curl

        PATCH /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "relationships": {
              "dids": {
                "data": [
                  {
                    "type": "dids",
                    "id": "a2dcccdb-4c81-4d93-a174-26001ccfc13a"
                  },
                  {
                    "type": "dids",
                    "id": "fd345680-4a4e-40db-b2f2-f81651e3e2df"
                  }
                ]
              }
            }
          }
        }

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group",
              "shared_channels_count": 3,
              "created_at": "2023-03-28T18:25:38.415Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/dids"
                }
              }
            }
          }
        }

   .. tab:: Update and Remove DIDs
   
     .. http:example:: curl
   
        PATCH /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "relationships": {
              "dids": {
                "data": [
        
                ]
              }
            }
          }
        }

        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }        

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




====================
Regulation Resources
====================

Regulation Resources allows customers to comply with the individual country DID registration requirements via API.

The regulation requirements are unique to each country and type of DID number. DIDWW **customers** and their **end users** have a collective obligation to comply with these regulations. 

To review the regulation requirements for each individual country and number type you can use :ref:`Requirements <requirements_v33>` resource.

The :ref:`Identity <identities_v33>` and :ref:`Addresses <addresses_v33>` may require additional :ref:`proofs <proofs_v33>` of existence.

The quantity of proofs required is indicated in the returned values of Get Requirements request. For more information review :ref:`Requirements Object <requirements_object_v33>`.

.. attention::

  All verifications will be reviewed by DIDWW Compliance Team and once **approved** the same identity and address can be used again for the DID types that fall under the same level of restrictions. 

To create a registration requirement verification task for existing DIDs or newly purchased DIDs, the following steps are required:

 1. Check the :ref:`Registration requirements <requirements_v33>`  for the DID that you are required to register.
 2. Create an :ref:`Identity <identities_v33>`. Two types of identities are supported:
     
  * Personal Identity 
  * Business Identity
  
 3. Create an :ref:`Address <addresses_v33>`.

 4. The **identity** and **address** may require additional :ref:`proof of existence <proofs_v33>` based on individual regulation requirements.

 5. The :ref:`proof types <proof_types_v33>` depend on the type of **Identity**.
 
.. note::
  
  Certain regulations do not require additional proofs, therefore steps **4** and **5** are completely optional. 
  
\

 6. Upload the documents using  :ref:`encrypted files <encrypted_files_v33>` endpoint.
 
.. attention::

 File format for the uploaded documents should be one of the following: **JPG**, **PNG**, **PDF**
 Other formats will be rejected during the verification process.
   
\

 
 7. Create a :ref:`proof <proofs_v33>` for identity or address.
 
 8. Additional :ref:`supporting document templates <supporting_document_template_v33>` may be required depending on the regulation.
 
.. note::

  Supporting document templates may be required by regulatory in certain countries. 

\

 9. :ref:`Validate <requirement_validations_v33>` the identity and address against the regulation requirements.
 
 10. Create a :ref:`verification task <address_verifications_v33>` for your DID Number.
 
 
.. note::
  You can receive :ref:`callback <callbacks_details_v33>` notifications about the verification task status. Status can be **Approved** or **Rejected**.
  

Proofs
======

.. tabs::

   .. tab:: Address
   
	.. csv-table::
		:header: "Name"

		"Copy of Phone Bill"
		"Utility Bill"
		"Rental Receipt"
		"Other"

   .. tab:: Personal Identity

	.. csv-table::
		:header: "Name"

		"Drivers License"
		"National ID "
		"Passport"
		"Residence Permit"
		"Visa"
		"Other"

   .. tab:: Business Identity

	.. csv-table::
		:header: "Name"

		"Business Registration Certificate / Incorporation Certificate"
		"Trade License  "
		"Excerpt from the commercial register "
		"Residence Permit"
		"Other"

The :ref:`Registration requirements <requirements_v33>` may require optional fields to be filled in.
If requirement have **personal_mandatory_fields** and/or **business_mandatory_fields**,the corresponding attributes/relationships of :ref:`Identity <identity_object_v33>` should be filled in.

Following mandatory values can be included in **personal_mandatory_fields** and/or **business_mandatory_fields**:

.. csv-table::
   :header: "Attribute", "Description"

   "birth_date", "Birth Date of a Person"
   "personal_tax_id", "Personal / Representative Tax Number"
   "id_number", "Proof of ID"
   "vat_id", "VAT / TAX Number"
   "company_reg_number", "Company Registration Number"
   
.. csv-table::
   :header: "Relationships", "Description"

   "country", "Place of Birth / Country of Incorporation"

The :ref:`Registration requirements <requirements_v33>` may require additional documents.
:ref:`Supporting Document Template Object <supporting_document_templates_object_v33>` lists all the additional documents that may be required by  :ref:`Registration requirements <requirements_v33>`.

There are 2 types of :ref:`Supporting Document Templates <supporting_document_template_v33>`: **permanent document** and **onetime document**.

Permanent document
==================

If the requirement contains **personal_permanent_document** and/or **business_permanent_document**, corresponding template form needs to be downloaded from the link provided under URL attribute.
The template form needs to be filled in and uploaded using :ref:`Encrypted File Resource<create_encrypted_files_v33>`.
The encrypted file(s) needs to be linked with the required Identity only once using :ref:`Permanent Supporting Document Resource<create_permanent_supporting_document_v33>`.
Consequently, this Identity can be reused again for the requirements with **Permanent Supporting Document** already linked.

Onetime document
================

If the requirement contains personal_onetime_document and/or business_onetime_document, corresponding template form needs to be downloaded from the link provided under URL attribute.
The template form needs to be filled in and uploaded using :ref:`Encrypted File Resource<create_encrypted_files_v33>`.
Such file(s) after encryption should be linked to the new address verification with this onetime document requirement.

Requirement Address Area Level
==============================

:ref:`Registration requirement <requirements_v33>` may enforce the :ref:`Address <addresses_object_v33>` to be from specific country/area.

The **address_area_level** attribute may be one of the following:

.. csv-table::
   :header: "Value", "Description"

   "Worldwide", "Address from any country can be used"
   "Country", "Address must be within the requirement country"
   "Area", "Address must be within the locality or region covered by the phone number's prefix"
   "City", "Address must be from the same City as DIDs"

Requirement Identity Area Level
===============================

:ref:`Registration requirement <requirements_v33>` may enforce the :ref:`Identity <identity_object_v33>` to be from specific country/area.

The **personal_area_level** and/or **business_area_level** attributes may be one of the following:

.. csv-table::
   :header: "Value", "Description"

   "Worldwide", "Address from any country can be used"
   "Country", "Address must be within the requirement country"

The following requests allows you to retrieve resources and services related to regulation of your DIDWW account.

 .. toctree::
    :maxdepth: 2

    identities/index
    addresses/index
    requirements/index
    address-verifications/index
    supporting-document-templates/index
    encrypted-files/index
    proofs/index
    permanent-documents/index
    proof-types/index
    areas/index
    


.. |br| raw:: html

   <br />

.. _identities_v33:

==========
Identities
==========

Returns a single or a list of Identities in the account. Allows creating modifying or deleting an identity.  

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  get-identity.rst
  get-identities.rst
  create-identity.rst
  update-identity.rst
  delete-identity.rst
  identity-object.rst
  
  
  



============
Get Identity
============

Returns a single Identity in the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/identities/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "id", "``string``","Yes","Unique ID identifier of the Identity."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/identities/0083c7f2-b030-491f-91b3-54597967ca38 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "0083c7f2-b030-491f-91b3-54597967ca38",
                "type": "identities",
                "attributes": {
                    "first_name": "Jane",
                    "last_name": "Smith",
                    "phone_number": "1276813663",
                    "id_number": "",
                    "birth_date": null,
                    "company_name": null,
                    "company_reg_number": null,
                    "vat_id": null,
                    "description": null,
                    "personal_tax_id": null,
                    "identity_type": "Personal",
                    "created_at": "2025-04-11T13:03:17.029Z",
                    "external_reference_id": null,
                    "verified": false,
                    "contact_email": "contact@email.com"
                },
                "relationships": {
                    "country": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/country",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/country"
                        }
                    },
                    "proofs": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/proofs",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/proofs"
                        }
                    },
                    "addresses": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/addresses",
                            "related": "https://sandbox-api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/addresses"
                        }
                    },
                    "permanent_documents": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/permanent_documents",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/permanent_documents"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

===============
Create Identity
===============

Create single Identity owned by your account.

Request
=======

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v33>`"
   "addresses", ":ref:`Addresses Object <addresses_object_v33>`"
   "addresses.country", ":ref:`Country Object <country_object_v33>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v33>`"
   "permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v33>`"
   "permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"

Request Body Object Attributes
------------------------------

.. tabs::

   .. tab:: Personal

     .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "first_name", "``string``", "Yes", "First name of the personal identity."
	   "last_name", "``string``", "Yes", "Last name of the personal identity."
	   "phone_number", "``string``", "Yes", "Phone number of the personal identity."
	   "personal_tax_id", "``string``", "No", "Personal tax ID of the personal identity."
	   "birth_date", "``string``", "No", "Birth date of the personal identity in ISO 8601 format."
	   "id_number", "``string``", "No", "ID number of the personal identity."
	   "description", "``string``", "No", "Description of the personal identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system"
	   "identity_type", "``string``", "Yes", "Type of Identity. Write “Personal” to create a personal identity."
	   "contact_email", "``string``", "No", "Contact email address of identity."

   .. tab:: Business

	 .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "company_name", "``string``", "Yes", "Company name of the business identity."
	   "company_reg_number", "``string``", "No", "Company registration number of the business identity."
	   "vat_id", "``string``", "No", "Company VAT ID of the business identity."
	   "first_name", "``string``", "Yes", "Company's representative First name of the business identity."
	   "last_name", "``string``", "Yes", "Company's representative Last name of the business identity."
	   "phone_number", "``string``", "Yes", "Company's representative Phone number of the business identity."
	   "personal_tax_id", "``string``", "No", "Company's representative Tax ID of the business identity."
	   "birth_date", "``string``", "No", "Company's representative Birth date of the business identity in ISO 8601 format."
	   "id_number", "``string``", "No", "Company's representative ID number of the business identity."
	   "description", "``string``", "No", "Company's representative description of the business identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system."
	   "identity_type", "``string``", "Yes", "Identity type. Write “Business” to create a business identity."
	   "contact_email", "``string``", "No", "Contact email address of identity."

Request Body Object Relationships
---------------------------------

	 .. csv-table::
	   :header: "Title", "Type", "Description"

	   "countries", ":ref:`Countries <country_object_v33>`","Specifies the country for identity."

Examples
========

.. tabs::

   .. tab:: Create Personal Identity

     .. http:example:: curl

            POST /v3/identities HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "birth_date": null,
                  "id_number": "string",
                  "description": "string",
                  "personal_tax_id": "string",
                  "external_reference_id": "string",
                  "identity_type": "Personal",
                  "contact_email": "string"
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "39623bf9-381f-4da6-ab29-2d3eb8783d81",
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "id_number": "string",
                  "birth_date": null,
                  "company_name": null,
                  "company_reg_number": null,
                  "vat_id": null,
                  "description": "string",
                  "personal_tax_id": "string",
                  "identity_type": "Personal",
                  "created_at": "2021-03-22T11:53:32.240Z",
                  "external_reference_id": null,
                  "verified": false,
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/country",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/country"
                    }
                  },
                  "proofs": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/proofs",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/proofs"
                    }
                  },
                  "addresses": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/addresses",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/addresses"
                    }
                  },
                  "permanent_documents": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/permanent_documents",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/permanent_documents"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

   .. tab:: Create Personal Identity with Country

     .. http:example:: curl

            POST /v3/identities HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "birth_date": null,
                  "id_number": "string",
                  "description": "string",
                  "personal_tax_id": "string",
                  "external_reference_id": "string",
                  "identity_type": "Personal",
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "data": {
                      "id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "874390d1-ea6f-47c0-8d30-c9baaaeebdd9",
                    "type": "identities",
                    "attributes": {
                        "first_name": "string",
                        "last_name": "string",
                        "phone_number": "string",
                        "id_number": "string",
                        "birth_date": null,
                        "company_name": null,
                        "company_reg_number": null,
                        "vat_id": null,
                        "description": "string",
                        "personal_tax_id": "string",
                        "identity_type": "Personal",
                        "created_at": "2023-01-31T09:23:10.406Z",
                        "external_reference_id": "string",
                        "verified": false,
                        "contact_email": "string"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/country",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/country"
                            }
                        },
                        "proofs": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/proofs",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/proofs"
                            }
                        },
                        "addresses": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/addresses",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/addresses"
                            }
                        },
                        "permanent_documents": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/permanent_documents",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/permanent_documents"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Create Business Identity

        .. http:example:: curl

            POST /v3/identities HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "id_number": "string",
                  "birth_date": "string",
                  "company_name": "string",
                  "company_reg_number": "string",
                  "vat_id": "string",
                  "description": "string",
                  "personal_tax_id": "string",
                  "external_reference_id": "string",
                  "identity_type": "Business",
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "data": {
                      "id": "6d0effab-3fe3-4e07-acc6-1d3ddc717ebc",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "fb7f3f67-014c-496b-b918-f874f2689a40",
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "id_number": "string",
                  "birth_date": null,
                  "company_name": "string",
                  "company_reg_number": null,
                  "vat_id": null,
                  "description": "string",
                  "personal_tax_id": "string",
                  "identity_type": "Business",
                  "created_at": "2021-03-22T12:08:29.987Z",
                  "external_reference_id": null,
                  "verified": false,
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/country",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/country"
                    }
                  },
                  "proofs": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/proofs",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/proofs"
                    }
                  },
                  "addresses": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/addresses",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/addresses"
                    }
                  },
                  "permanent_documents": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/permanent_documents",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/permanent_documents"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



===============
Delete Identity
===============

Deletes the Identity without restoration.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/identities/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "id", "``string``","Yes","Unique ID identifier of the Identities."

Example
=======

.. http:example:: curl

    DELETE /v3/identities/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "409","No",":ref:`Conflict <conflict_v1>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




==============
Get Identities
==============

Returns a list of Identities on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/identities``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``, ``DateTime``", "No", ":ref:`Filtering <api_filters>`"
   "includes", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Inclusion <api_filters>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"
   
   "country", ":ref:`Country Object <country_object_v33>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v33>`"
   "addresses", ":ref:`Addresses Object <addresses_object_v33>`"
   "addresses.country", ":ref:`Country Object <country_object_v33>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v33>`"
   "permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v33>`"
   "permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"
   
   "first_name", "``string``", "Yes", "Yes", "The ``first_name`` field."
   "first_name_contains", "``string``", "Yes", "Yes", "The ``firs_name_contains`` field."
   "last_name", "``string``", "Yes", "Yes", "The ``last_name`` field."
   "last_name_contains", "``string``", "Yes", "Yes", "The ``last_name_contains`` field."
   "phone_number", "``string``", "Yes", "Yes", "The ``phone_number`` field."
   "phone_number_contains", "``string``", "Yes", "No", "The ``phone_number_contains`` field."
   "id_number", "``string``", "Yes", "Yes", "The ``id_number`` field."
   "id_number_contains", "``string``", "Yes", "Yes", "The ``id_number_contains`` field."
   "birth_date", "``DateTime``", "No", "Yes", "The ``birth_date`` field."
   "company_name", "``string``", "Yes", "Yes", "The ``company_name`` field."
   "company_name_contains", "``string``", "Yes", "Yes", "The ``company_name_contains`` field."
   "company_reg_number", "``string``", "Yes", "Yes", "The ``company_reg_number`` field."
   "company_reg_number_contains", "``string``", "Yes", "Yes", "The ``company_reg_number_contains`` field."
   "vat_id", "``string``", "Yes", "Yes", "The ``vat_id`` field."
   "vat_id_contains", "``string``", "Yes", "Yes", "The ``vat_id_contains`` field."
   "description", "``string``", "Yes", "Yes", "The ``description`` field."
   "description_contains", "``string``", "Yes", "Yes", "The ``description_contains`` field"
   "personal_tax_id", "``string``", "Yes", "Yes", "The ``personal_tax_id`` field."
   "personal_tax_id_contains", "``string``", "Yes", "Yes", "The ``personal_tax_id`` field."
   "identity_type", "``string``", "No", "No", "The ``identity_type`` field."
   "country.id", "``string``", "No", "No", "The ``country.id`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"
   
   "first_name", "The ``first_name`` field."
   "last_name", "The ``last_name`` field."
   "phone_number", "The ``phone_number`` field."
   "id_number", "The ``id_number`` field."
   "birth_date", "The ``birth_date`` field."
   "company_name", "The ``company_name`` field."
   "company_reg_number", "The ``company_reg_number`` field."
   "vat_id", "The ``vat_id`` field."
   "description", "The ``description`` field."
   "personal_tax_id", "The ``personal_tax_id`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"
   
   "first_name", "The ``first_name`` attribute."
   "last_name", "The ``last_name`` attribute."
   "phone_number", "The ``phone_number`` attribute."
   "id_number", "The ``id_number`` attribute."
   "birth_date", "The ``birth_date`` attribute."
   "company_name", "The ``company_name`` attribute."
   "company_reg_number", "The ``company_reg_number`` attribute."
   "vat_id", "The ``vat_id`` attribute."
   "description", "The ``description`` attribute."
   "personal_tax_id", "The ``personal_tax_id`` attribute."
   "identity_type", "The ``identity_type`` attribute."
   "created_at", "The ``created_at`` attribute."
   "external_reference_id", "The ``external_reference_id`` attribute."
   "verified", "The ``verified`` attribute."
   "contact_email", "The ``contact_email`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/identities HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
		            "type": "identities",
		            "attributes": {
		                "first_name": "Jane",
		                "last_name": "Smith",
		                "phone_number": "353-1-9015266",
		                "id_number": "0000000000",
		                "birth_date": "2000-01-01",
		                "company_name": null,
		                "company_reg_number": null,
		                "vat_id": null,
		                "description": "Personal details",
		                "personal_tax_id": null,
		                "identity_type": "Personal",
		                "created_at": "2020-09-14T07:29:41.393Z",
                                "external_reference_id": null,
                                "verified": false,
                                "contact_email": "contact@email.com"
		            },
		            "relationships": {
		                "country": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
		                    }
		                },
		                "addresses": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
		                    }
		                },
		                "permanent_documents": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
		                    }
		                }
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 4,
		        "api_version": "2022-05-10"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/identities?page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/identities?page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Filter first_name_contains

    .. http:example:: curl

        GET /v3/identities/v3/identities?filter[first_name_contains]=Jane HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
		            "type": "identities",
		            "attributes": {
		                "first_name": "Jane",
		                "last_name": "Smith",
		                "phone_number": "353-1-9015266",
		                "id_number": "0000000000",
		                "birth_date": "2000-01-01",
		                "company_name": null,
		                "company_reg_number": null,
		                "vat_id": null,
		                "description": "Personal details",
		                "personal_tax_id": null,
		                "identity_type": "Personal",
		                "created_at": "2020-09-14T07:29:41.393Z",
                                "external_reference_id": null,
                                "verified": false,
                                "contact_email": "contact@email.com"
		            },
		            "relationships": {
		                "country": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
		                    }
		                },
		                "addresses": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
		                    }
		                },
		                "permanent_documents": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
		                    }
		                }
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 4,
		        "api_version": "2022-05-10"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane&page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane&page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Include country

    .. http:example:: curl

        GET /v3/identities/v3/identities?include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
		            "type": "identities",
		            "attributes": {
		                "first_name": "Jane",
		                "last_name": "Smith",
		                "phone_number": "353-1-9015266",
		                "id_number": "0000000000",
		                "birth_date": "2000-01-01",
		                "company_name": null,
		                "company_reg_number": null,
		                "vat_id": null,
		                "description": "Personal details",
		                "personal_tax_id": null,
		                "identity_type": "Personal",
		                "created_at": "2020-09-14T07:29:41.393Z",
                                "external_reference_id": null,
                                "verified": false,
                                "contact_email": "contact@email.com"
		            },
                  },
                  "relationships":{
                     "country":{
                        "links":{
                           "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/country",
                           "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/country"
                        },
                        "data":{
                           "type": "countries",
                           "id": "683c77a5-fcb0-48a0-8501-4de6284a2889"
                        }
                     },
                     "proofs": {"links":{
                        "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/proofs",
                        "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/proofs"
                     }},
                     "addresses": {"links":{
                        "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/addresses",
                        "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/addresses"
                     }},
                     "permanent_documents": {"links":{
                        "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/permanent_documents",
                        "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/permanent_documents"
                     }}
                  }
               }],
               "included": [{
                  "id": "683c77a5-fcb0-48a0-8501-4de6284a2889",
                  "type": "countries",
                  "attributes":{
                     "name": "Lithuania",
                     "prefix": "370",
                     "iso": "LT"
                  },
                  "relationships": {"regions": {"links":{
                     "self": "https://api.didww.com/v3/countries/683c77a5-fcb0-48a0-8501-4de6284a2889/relationships/regions",
                     "related": "https://api.didww.com/v3/countries/683c77a5-fcb0-48a0-8501-4de6284a2889/regions"
                  }}}
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/identities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/identities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 



.. _identity_object_v33:

===============
Identity Object
===============

Identity Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "first_name", "``string``", "First name of identity."
   "last_name", "``string``", "Last name of identity."
   "phone_number", "``string``", "Phone number of identity."
   "id_number", "``string``", "The ID number of identity."
   "birth_date", "``DateTime``", "The birth date of identity."
   "company_name", "``string``", "Company name of identity."
   "company_reg_number", "``string``", "Company Registration number of identity."
   "vat_id", "``string``", "The VAT ID of identity."
   "description", "``string``", "The friendly description of identity."
   "personal_tax_id", "``string``", "The personal tax number of identity."
   "external_reference_id", "``string``", "Identifier in external customer's system."
   "verified", "``boolean``", "Displays if Identity is verified."
   "contact_email", "``string``", "Contact email address of identity."
   "identity_type", "``string``", "One of the following: ``Personal`` or ``Business``."



.. |br| raw:: html

   <br />

===============
Update Identity
===============

Update the settings of a single Identity owned by your account.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/identities/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "id", "``string``","Yes","Unique ID identifier of the Identity."

Attributes
==========

.. tabs::

   .. tab:: Personal

     .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "first_name", "``string``", "No", "First name of the personal identity."
	   "last_name", "``string``", "No", "Last name of the personal identity."
	   "phone_number", "``string``", "No", "Phone number of the personal identity."
	   "personal_tax_id", "``string``", "No", "Personal tax ID of the personal identity."
	   "birth_date", "``string``", "No", "Birth date of the personal identity in ISO 8601 format."
	   "id_number", "``string``", "No", "ID number of the personal identity."
	   "description", "``string``", "No", "Description of the personal identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system."
	   "contact_email", "``string``", "No", "Contact email address of identity."

   .. tab:: Business

	 .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "company_name", "``string``", "No", "Company name of the business identity."
	   "company_reg_number", "``string``", "No", "Company registration number of the business identity."
	   "vat_id", "``string``", "No", "Company VAT ID of the business identity."
	   "first_name", "``string``", "No", "Company's representative First name of the business identity."
	   "last_name", "``string``", "No", "Company's representative Last name of the business identity."
	   "phone_number", "``string``", "No", "Company's representative Phone number of the business identity."
	   "personal_tax_id", "``string``", "No", "Company's representative Tax ID of the business identity."
	   "birth_date", "``string``", "No", "Company's representative Birth date of the business identity in ISO 8601 format."
	   "id_number", "``string``", "No", "Company's representative ID number of the business identity."
	   "description", "``string``", "No", "Company's representative description of the business identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system."
	   "contact_email", "``string``", "No", "Contact email address of identity."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch

     .. http:example:: curl

            PATCH /v3/identities/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
                "type": "identities",
                "attributes": {
                  "birth_date": "2000-01-01",
                  "phone_number": "35319015266",
                  "last_name": "Smith",
                  "contact_email": "support@didww.com",
                  "vat_id": null,
                  "id_number": "0000000000",
                  "description": "string",
                  "personal_tax_id": "string"
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
                "type": "identities",
                "attributes": {
                  "first_name": "Jane",
                  "last_name": "Smith",
                  "phone_number": "35319015266",
                  "id_number": "0000000000",
                  "birth_date": "2000-01-01",
                  "company_name": "string",
                  "company_reg_number": null,
                  "vat_id": null,
                  "description": "string",
                  "personal_tax_id": "string",
                  "identity_type": "Personal",
                  "created_at": "2020-09-14T07:29:41.393Z",
                  "contact_email": "support@didww.com"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
                    }
                  },
                  "proofs": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
                    }
                  },
                  "addresses": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
                    }
                  },
                  "permanent_documents": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _addresses_v33:

=========
Addresses
=========

Returns a single or a list of Addresses in the account. Allows creating modifying or deleting an address.  

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  get-address.rst
  get-addresses.rst
  create-address.rst
  update-address.rst
  delete-address.rst
  address-object.rst




===========
Get Address
===========

Returns a single Address in the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/addresses/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Addresses."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v33>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v33>`"
   "identity", ":ref:`Identities Object <identity_object_v33>`"
   "identity.country", ":ref:`Country Object <country_object_v33>`"
   "identity.proofs", ":ref:`Proofs Object <proofs_object_v33>`"
   "identity.proofs.proof_type", ":ref:`Proofs Object <proofs_object_v33>`"
   "identity.permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v33>`"
   "identity.permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "area", ":ref:`Area Object <area_object_v33>`"
   "city", ":ref:`City Object <city_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/addresses/0083c7f2-b030-491f-91b3-54597967ca38 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "54c92d8e-f135-4b55-ac48-748d44437509",
                "type": "addresses",
                "attributes": {
                    "city_name": "Dublin",
                    "postal_code": "Dublin 8",
                    "address": "10/13 Thomas Street",
                    "description": "My Business Address",
                    "created_at": "2020-09-14T07:29:41.413Z"
                },
                "relationships": {
                    "identity": {
                        "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/identity",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/identity"
                        }
                    },
                    "country": {
                        "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/country",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/country"
                        }
                    },
                    "proofs": {
                        "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/proofs",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/proofs"
                        }
                    },
                    "area": {
                      "links": {
                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/area",
                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/area"
                      }
                    },
                    "city": {
                      "links": {
                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/city",
                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/city"
                      }
                    }
                }
            },
            "meta": {
                "api_version": "2022-05-10"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



.. _addresses_object_v33:

================
Addresses Object
================

Addresses Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "city_name", "``string``", "City name of the address."
   "postal_code", "``string``", "Postal code of the address."
   "address", "``string``", "Full address."
   "description", "``string``", "Description of the address."
   "verified", "``boolean``", "Displays if Address is verified."
   "created_at", "``Date&Time``", "Creation date and time of the address."



.. |br| raw:: html

   <br />

================
Create Addresses
================

Creates an Address that can be assigned to an Identity.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/addresses``

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Required", "Description"

   "city_name", "``string``", "Yes", "City name of the address."
   "postal_code", "``string``", "Yes", "Postal code of the address."
   "address", "``string``", "Yes", "Full address."
   "description", "``string``", "No", "The description of the address."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "countries", ":ref:`Countries <country_object_v33>`", "Specifies the country for the address."
   "identities", ":ref:`Identities <identity_object_v33>`", "Specifies the identity for the address."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch

     .. http:example:: curl

            POST /v3/addresses HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "addresses",
                "attributes": {
                  "city_name": "string",
                  "postal_code": "string",
                  "address": "string",
                  "description": "string"
                },
                "relationships": {
                  "identity": {
                    "data": {
                      "id": "6c832a1d-b19d-471b-b416-9b5bf2b6ef9d",
                      "type": "identities"
                    }
                  },
                  "country": {
                    "data": {
                      "id": "38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                    "type": "addresses",
                    "attributes": {
                        "city_name": "string",
                        "postal_code": "string",
                        "address": "string",
                        "description": "string",
                        "created_at": "2020-09-16T10:23:07.846Z"
                    },
                    "relationships": {
                        "identity": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/identity",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/identity"
                            }
                        },
                        "country": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/country",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/country"
                            }
                        },
                        "proofs": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/proofs",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/proofs"
                            }
                        },
                        "area": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/area",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/area"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/city",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/city"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Invalid country.id Input

     .. http:example:: curl

            POST /v3/addresses HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "addresses",
                "attributes": {
                  "city_name": "Siauliai",
                  "postal_code": "LT80001",
                  "address": "Biciunu 14",
                  "description": "is kiemo puses"
                },
                "relationships": {
                  "identity": {
                    "data": {
                      "id": "6c832a1d-b19d-471b-b416-9b5bf2b6ef9d",
                      "type": "identities"
                    }
                  },
                  "country": {
                    "data": {
                      "id": "country_id_string",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {"errors": [{
               "title": "is invalid",
               "detail": "country - is invalid",
               "code": "100",
               "source": {"pointer": "/data/relationships/country"},
               "status": "422"
            }]}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


==============
Delete Address
==============

Deletes the address without restoration.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/addresses/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Addresses. "

Example
=======

.. http:example:: curl

    DELETE /v3/addresses/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "409","No",":ref:`Conflict <conflict_v1>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




=============
Get Addresses
=============

Returns a list of Addresses on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/addresses``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Inclusion <api_filters>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v33>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v33>`"
   "identity", ":ref:`Identities Object <identity_object_v33>`"
   "identity.country", ":ref:`Country Object <country_object_v33>`"
   "identity.proofs", ":ref:`Proofs Object <proofs_object_v33>`"
   "identity.proofs.proof_type", ":ref:`Proofs Object <proofs_object_v33>`"
   "identity.permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v33>`"
   "identity.permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "area", ":ref:`Area Object <area_object_v33>`"
   "city", ":ref:`City Object <city_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "city_name", "``string``", "Yes", "No", "The ``city_name`` field."
   "city_name_contains", "``string``", "Yes", "No", "The ``city_name_contains`` field."
   "postal_code", "``string``", "Yes", "No", "The ``postal_code`` field."
   "postal_code_contains", "``string``", "Yes", "No", "The ``postal_code_contains`` field."
   "address", "``string``", "Yes", "No", "The ``address`` field."
   "address_contains", "``string``", "Yes", "No", "The ``address_contains`` field."
   "description", "``string``", "Yes", "No", "The ``description`` field."
   "description_contains", "``string``", "Yes", "No", "The ``description_contains`` field."
   "identity.id", "``string``", "Yes", "Yes", "The ``identity.id`` field."
   "country.id", "``string``", "Yes", "Yes", "The ``country.id`` field."
   "area.id", "``string``", "Yes", "Yes", "The ``area.id`` field."
   "city.id", "``string``", "Yes", "Yes", "The ``city.id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "city_name", "The ``first_name`` field."
   "postal_code", "The ``last_name`` field."
   "address", "The ``address`` field."
   "description", "The ``id_number`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "city_name", "The ``first_name`` attribute."
   "postal_code", "The ``last_name`` attribute."
   "address", "The ``phone_number`` attribute."
   "description", "The ``id_number`` attribute."
   "created_at", "The ``created_at`` attribute."
   "verified", "The ``verified`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/addresses HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
		    "data": [
		        {
		            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
		            "type": "addresses",
		            "attributes": {
		                "city_name": "Antwerp",
		                "postal_code": "4641PA",
		                "address": "49th Ave",
		                "description": "Address of Rise Industries",
		                "created_at": "2020-09-16T10:23:07.846Z"
		            },
		            "relationships": {
		                "identity": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/identity",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/identity"
		                    }
		                },
		                "country": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/country",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/proofs",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/proofs"
		                    }
		                },
                        "area": {
                          "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/area",
                            "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/area"
                          }
                        },
                        "city": {
                          "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/city",
                            "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/city"
                          }
                        }
		            }
		        },
		        {
		            "id": "f3f18701-356b-43dc-8a96-82d07af415cf",
		            "type": "addresses",
		            "attributes": {
		                "city_name": "Galway",
		                "postal_code": "Galway 17",
		                "address": "Street 15",
		                "description": "Headquarters",
		                "created_at": "2020-09-22T11:57:05.524Z"
		            },
		            "relationships": {
		                "identity": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/identity",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/identity"
		                    }
		                },
		                "country": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/country",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/proofs",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/proofs"
		                    }
		                },
                        "area": {
                          "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/area",
                            "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/area"
                          }
                        },
                        "city": {
                          "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/city",
                            "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/city"
                          }
                        }
		            }
		        },
		        {
		            "id": "54c92d8e-f135-4b55-ac48-748d44437509",
		            "type": "addresses",
		            "attributes": {
		                "city_name": "Dublin",
		                "postal_code": "Dublin 8",
		                "address": "10/13 Thomas Street",
		                "description": "My Business Address",
		                "created_at": "2020-09-14T07:29:41.413Z"
		            },
		            "relationships": {
		                "identity": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/identity",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/identity"
		                    }
		                },
		                "country": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/country",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/proofs",
		                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/proofs"
		                    }
		                },
                        "area": {
                          "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/area",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/area"
                          }
                        },
                        "city": {
                          "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/city",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/city"
                          }
                        }
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 3,
		        "api_version": "2022-05-10"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/addresses?page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/addresses?page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Filter by country.id (i.e. Germany)

    .. http:example:: curl

        GET /v3/addresses?filter[country.id]=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "6f73fecd-6a7b-4440-93d7-41e0000baee0",
                  "type": "addresses",
                  "attributes":       {
                     "city_name": "Berlin",
                     "postal_code": "13089",
                     "address": "Leopoldstraße 38, Berlin Heinersdorf,Berlin",
                     "description": "none",
                     "created_at": "2021-06-08T08:38:25.433Z",
                     "verified": false
                  },
                  "relationships":       {
                     "identity": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/identity",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/identity"
                     }},
                     "country": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/country",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/country"
                     }},
                     "proofs": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/proofs",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/proofs"
                     }},
                     "area": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/area",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/area"
                     }},
                     "city": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/city",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/city"
                     }}
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/addresses?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/addresses?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

   .. tab:: Include country

    .. http:example:: curl

        GET /v3/addresses?include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "6f73fecd-6a7b-4440-93d7-41e0000baee0",
                  "type": "addresses",
                  "attributes":       {
                     "city_name": "Berlin",
                     "postal_code": "13089",
                     "address": "Leopoldstraße 38, Berlin Heinersdorf,Berlin",
                     "description": "none",
                     "created_at": "2021-06-08T08:38:25.433Z",
                     "verified": false
                  },
                  "relationships":       {
                     "identity": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/identity",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/identity"
                     }},
                     "country":          {
                        "links":             {
                           "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/country",
                           "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/country"
                        },
                        "data":             {
                           "type": "countries",
                           "id": "38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f"
                        }
                     },
                     "proofs": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/proofs",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/proofs"
                     }},
                     "area": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/area",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/area"
                     }},
                     "city": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/city",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/city"
                     }}
                  }
               }],
               "included": [   {
                  "id": "38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f",
                  "type": "countries",
                  "attributes":       {
                     "name": "Germany",
                     "prefix": "49",
                     "iso": "DE"
                  },
                  "relationships": {"regions": {"links":       {
                     "self": "https://api.didww.com/v3/countries/38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f/relationships/regions",
                     "related": "https://api.didww.com/v3/countries/38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f/regions"
                  }}}
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/addresses?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/addresses?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

================
Update Addresses
================

Update the settings of a single Address owned by your account.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/addresses/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number allocated to this Address."

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "city_name", "``string``", "No", "City name of the address."
   "postal_code", "``string``", "No", "Postal code of the address."
   "address", "``string``", "No", "Full address."
   "description", "``string``", "No", "The description of the address."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch

     .. http:example:: curl

      PATCH /v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
      Host: api.didww.com
      Content-Type: application/vnd.api+json
      Accept: application/vnd.api+json
      Api-Key: [API token]

      {
        "data": {
          "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
          "type": "addresses",
          "attributes": {
            "city_name": "string",
            "postal_code": "string",
            "address": "string",
            "description": "string"
          }
        }
      }

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json

      {
        "data": {
          "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
          "type": "addresses",
          "attributes": {
            "city_name": "string",
            "postal_code": "string",
            "address": "string",
            "description": "string",
            "created_at": "2020-09-16T10:23:07.846Z"
          },
          "relationships": {
            "identity": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/identity",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/identity"
              }
            },
            "country": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/country",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/country"
              }
            },
            "proofs": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/proofs",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/proofs"
              }
            },
            "area": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/area",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/area"
              }
            },
            "city": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/city",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/city"
              }
            }
          }
        },
        "meta": {
          "api_version": "2022-05-10"
        }
      }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _requirements_v33:

============
Requirements
============

Returns the list of the registration requirements per country.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-requirement.rst
  get-requirements.rst
  requirements-object.rst
  requirement-validations.rst




===============
Get Requirement
===============

Returns the registration requirements per single country.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/requirements/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "countries", ":ref:`Country Object <country_object_v33>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "personal_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "business_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "personal_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "business_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "personal_proof_types", ":ref:`Proof Type Object <proof_types_object_v33>`"
   "business_proof_types", ":ref:`Proof Type Object <proof_types_object_v33>`"
   "address_proof_types", ":ref:`Proof Type Object <proof_types_object_v33>`"

Example
=======

.. http:example:: curl

    GET /v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
            "type": "requirements",
            "attributes": {
                "identity_type": "Business",
                "personal_area_level": null,
                "business_area_level": "WorldWide",
                "address_area_level": "Area",
                "personal_proof_qty": 0,
                "business_proof_qty": 1,
                "address_proof_qty": 1,
                "personal_mandatory_fields": null,
                "business_mandatory_fields": null,
                "service_description_required": true,
                "restriction_message": "Ireland Local DID registration requirements:\r\n\r\n1. Name, business name and contact phone number.\r\n2. Current address in Ireland, must be from the same area in Ireland as DID ordered (street, building number, postal code, city).\r\n\r\nDID number will not be activated until full registration details are provided and approved."
            },
            "relationships": {
                "country": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                    }
                },
                "did_group_type": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                    }
                },
                "personal_permanent_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_permanent_document",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_permanent_document"
                    }
                },
                "business_permanent_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_permanent_document",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_permanent_document"
                    }
                },
                "personal_onetime_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_onetime_document",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_onetime_document"
                    }
                },
                "business_onetime_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_onetime_document",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_onetime_document"
                    }
                },
                "personal_proof_types": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_proof_types",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_proof_types"
                    }
                },
                "business_proof_types": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_proof_types",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_proof_types"
                    }
                },
                "address_proof_types": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/address_proof_types",
                        "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/address_proof_types"
                    }
                }
            }
        },
        "meta": {
            "api_version": "2022-05-10"
        }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 




================
Get Requirements
================

Returns the list of registration requirements.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/requirements``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"
   "include", "``string``", "No", ":ref:`Includes <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "personal_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "business_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "personal_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "business_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "personal_proof_types", ":ref:`Proof Type Object <proof_types_object_v33>`"
   "business_proof_types", ":ref:`Proof Type Object <proof_types_object_v33>`"
   "address_proof_types", ":ref:`Proof Type Object <proof_types_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Requirement ``id`` field."
   "country.id", "``string``", "Yes", "Yes", "The ``country.id`` field."
   "did_group_type.id", "``string``", "Yes", "Yes", "The ``did_group_type.id`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"
   
   "identity_type", "The ``identity_type`` attribute."
   "personal_area_level", "The ``personal_area_level`` attribute."
   "business_area_level", "The ``business_area_level`` attribute."
   "address_area_level", "The ``address_area_level`` attribute."
   "personal_proof_qty", "The ``personal_proof_qty`` attribute."
   "business_proof_qty", "The ``business_proof_qty`` attribute."
   "address_proof_qty", "The ``business_proof_qty`` attribute."
   "personal_mandatory_fields", "The ``personal_mandatory_fields`` attribute."
   "business_mandatory_fields", "The ``business_mandatory_fields`` attribute."
   "service_description_required", "The ``service_description_required`` attribute."
   "restriction_message", "The ``restriction_message`` attribute."

Available Mandatory Fields
--------------------------

.. important:: The ``personal_mandatory_fields`` and ``business_mandatory_fields`` arrays in the response may contain a selection of the fields listed below, depending on the specific requirement.

.. tabs::

    .. tab:: Personal

          .. csv-table::
             :header: "Value", "Description"

             "birth_date", "The user's date of birth."
             "country", "The user's country of tax residence."
             "birth_country", "The user's country of birth."
             "id_number", "The user's national identification number."
             "personal_tax_id", "The user's personal tax identification number."
             "contact_email", "The user's contact email address."

    .. tab:: Business

          .. csv-table::
             :header: "Value", "Description"

             "id_number", "The national ID number of the company's legal representative."
             "vat_id", "The company's Value Added Tax (VAT) identification number."
             "country", "The country where the company is registered."
             "company_reg_number", "The company's official registration number."
             "personal_tax_id", "The personal tax ID of the company's legal representative."
             "contact_email", "The contact email of the company's representative."

Example
=======

.. tabs::

    .. tab:: Simple Request

        .. http:example:: curl

            GET /v3/requirements HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "3f3be6a6-a513-4509-bd9b-945e599e16f5",
                        "type": "requirements",
                        "attributes": {
                            "identity_type": "Any",
                            "personal_area_level": "WorldWide",
                            "business_area_level": "WorldWide",
                            "address_area_level": "Area",
                            "personal_proof_qty": 0,
                            "business_proof_qty": 0,
                            "address_proof_qty": 0,
                            "personal_mandatory_fields": null,
                            "business_mandatory_fields": null,
                            "service_description_required": true,
                            "restriction_message": "Restriction message"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/country",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/country"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/did_group_type",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/did_group_type"
                                }
                            },
                            "personal_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/personal_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/personal_permanent_document"
                                }
                            },
                            "business_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/business_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/business_permanent_document"
                                }
                            },
                            "personal_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/personal_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/personal_onetime_document"
                                }
                            },
                            "business_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/business_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/business_onetime_document"
                                }
                            },
                            "personal_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/personal_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/personal_proof_types"
                                }
                            },
                            "business_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/business_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/business_proof_types"
                                }
                            },
                            "address_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/address_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/address_proof_types"
                                }
                            }
                        }
                    },
                    {
                        "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                        "type": "requirements",
                        "attributes": {
                            "identity_type": "Business",
                            "personal_area_level": null,
                            "business_area_level": "WorldWide",
                            "address_area_level": "Area",
                            "personal_proof_qty": 0,
                            "business_proof_qty": 1,
                            "address_proof_qty": 1,
                            "personal_mandatory_fields": null,
                            "business_mandatory_fields": null,
                            "service_description_required": true,
                            "restriction_message": "Ireland Local DID registration requirements:\r\n\r\n1. Name, business name and contact phone number.\r\n2. Current address in Ireland, must be from the same area in Ireland as DID ordered (street, building number, postal code, city).\r\n\r\nDID number will not be activated until full registration details are provided and approved."
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                                }
                            },
                            "personal_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_permanent_document"
                                }
                            },
                            "business_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_permanent_document"
                                }
                            },
                            "personal_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_onetime_document"
                                }
                            },
                            "business_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_onetime_document"
                                }
                            },
                            "personal_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_proof_types"
                                }
                            },
                            "business_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_proof_types"
                                }
                            },
                            "address_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/address_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/address_proof_types"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 2,
                    "api_version": "2022-05-10"
                },
                "links": {
                    "first": "https://sandbox-api.didww.com/v3/requirements?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://sandbox-api.didww.com/v3/requirements?page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

    .. tab:: Filter by country.id (i.e. Germany)

        .. http:example:: curl

            GET /v3/requirements?filter[country.id]=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data":    [
                        {
                     "id": "3553253a-99eb-4303-a16a-6b1042d3f147",
                     "type": "requirements",
                     "attributes":          {
                        "identity_type": "Any",
                        "personal_area_level": "WorldWide",
                        "business_area_level": "Country",
                        "address_area_level": "Country",
                        "personal_proof_qty": 1,
                        "business_proof_qty": 1,
                        "address_proof_qty": 1,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["country"],
                        "service_description_required": false,
                        "restriction_message": "German National DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n* Germany registration form<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n* Germany registration form<br>\r\nFor <b>address<\/b> verification:\r\n* Address in Germany (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)<br>\r\nThe number provided online is a <b>demo<\/b>. An active number will be provided when the registration process is complete.<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/country",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/requirements/3553253a-99eb-4303-a16a-6b1042d3f147/address_proof_types"
                        }}
                     }
                  },
                        {
                     "id": "229310cf-21c1-41f0-9cfb-c4ea133304d5",
                     "type": "requirements",
                     "attributes":          {
                        "identity_type": "Any",
                        "personal_area_level": "WorldWide",
                        "business_area_level": "Country",
                        "address_area_level": "City",
                        "personal_proof_qty": 1,
                        "business_proof_qty": 1,
                        "address_proof_qty": 1,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["country"],
                        "service_description_required": false,
                        "restriction_message": "German Local DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n* Germany registration form<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n* Germany registration form<br>\r\nFor <b>address<\/b> verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)<br>\r\nThe number provided online is a <b>demo<\/b>. An active number will be provided when the registration process is complete.<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/country",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/address_proof_types"
                        }}
                     }
                  }
               ],
               "meta":    {
                  "total_records": 2,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/requirements?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/requirements?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

    .. tab:: Filter by did_group_type.id (i.e. Shared-Cost)

        .. http:example:: curl

            GET /v3/requirements?filter[did_group_type.id]=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data":    [
                        {
                     "id": "5558cecd-cf91-4189-ad77-0f21518eb0d9",
                     "type": "requirements",
                     "attributes":          {
                        "identity_type": "Any",
                        "personal_area_level": "WorldWide",
                        "business_area_level": "WorldWide",
                        "address_area_level": "WorldWide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 0,
                        "address_proof_qty": 0,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": null,
                        "service_description_required": false,
                        "restriction_message": "Australian Shared Cost DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/country",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/address_proof_types"
                        }}
                     }
                  },
                        {
                     "id": "469d5cb4-baf6-4639-a500-f3bd04e89861",
                     "type": "requirements",
                     "attributes":          {
                        "identity_type": "Business",
                        "personal_area_level": null,
                        "business_area_level": "WorldWide",
                        "address_area_level": "WorldWide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 2,
                        "address_proof_qty": 2,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["id_number"],
                        "service_description_required": true,
                        "restriction_message": "Chinese Shared Cost DID End User registration requirements:<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport\r\n* Company name\r\n* Company incorporation certificate copy<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)\r\n* 2 copies of utility bills (less than 6 months old)<br>\r\nAdditional information:\r\n* Service usage description<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/country",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/address_proof_types"
                        }}
                     }
                  }
               ],
               "meta":    {
                  "total_records": 2,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

    .. tab:: Include country while filtered by did_group_type.id

        .. http:example:: curl

            GET /v3/requirements?filter[did_group_type.id]=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data":    [
                        {
                     "id": "5558cecd-cf91-4189-ad77-0f21518eb0d9",
                     "type": "requirements",
                     "attributes":          {
                        "identity_type": "Any",
                        "personal_area_level": "WorldWide",
                        "business_area_level": "WorldWide",
                        "address_area_level": "WorldWide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 0,
                        "address_proof_qty": 0,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": null,
                        "service_description_required": false,
                        "restriction_message": "Australian Shared Cost DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country":             {
                           "links":                {
                              "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/country",
                              "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/country"
                           },
                           "data":                {
                              "type": "countries",
                              "id": "afeb1a21-abb4-4983-8712-7ab44950fc16"
                           }
                        },
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/address_proof_types"
                        }}
                     }
                  },
                        {
                     "id": "469d5cb4-baf6-4639-a500-f3bd04e89861",
                     "type": "requirements",
                     "attributes":          {
                        "identity_type": "Business",
                        "personal_area_level": null,
                        "business_area_level": "WorldWide",
                        "address_area_level": "WorldWide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 2,
                        "address_proof_qty": 2,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["id_number"],
                        "service_description_required": true,
                        "restriction_message": "Chinese Shared Cost DID End User registration requirements:<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport\r\n* Company name\r\n* Company incorporation certificate copy<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)\r\n* 2 copies of utility bills (less than 6 months old)<br>\r\nAdditional information:\r\n* Service usage description<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country":             {
                           "links":                {
                              "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/country",
                              "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/country"
                           },
                           "data":                {
                              "type": "countries",
                              "id": "7006e60d-d2c7-4479-94ad-b954038e6dde"
                           }
                        },
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/address_proof_types"
                        }}
                     }
                  }
               ],
               "included":    [
                        {
                     "id": "afeb1a21-abb4-4983-8712-7ab44950fc16",
                     "type": "countries",
                     "attributes":          {
                        "name": "Australia",
                        "prefix": "61",
                        "iso": "AU"
                     },
                     "relationships": {"regions": {"links":          {
                        "self": "https://api.didww.com/v3/countries/afeb1a21-abb4-4983-8712-7ab44950fc16/relationships/regions",
                        "related": "https://api.didww.com/v3/countries/afeb1a21-abb4-4983-8712-7ab44950fc16/regions"
                     }}}
                  },
                        {
                     "id": "7006e60d-d2c7-4479-94ad-b954038e6dde",
                     "type": "countries",
                     "attributes":          {
                        "name": "China",
                        "prefix": "86",
                        "iso": "CN"
                     },
                     "relationships": {"regions": {"links":          {
                        "self": "https://api.didww.com/v3/countries/7006e60d-d2c7-4479-94ad-b954038e6dde/relationships/regions",
                        "related": "https://api.didww.com/v3/countries/7006e60d-d2c7-4479-94ad-b954038e6dde/regions"
                     }}}
                  }
               ],
               "meta":    {
                  "total_records": 2,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

.. _requirement_validations_v33:

=======================
Requirement Validations
=======================

Checks if the :ref:`Address <addresses_object_v33>` and / or :ref:`Identity <identity_object_v33>` created is valid against the :ref:`Requirement <requirements_v33>`.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/requirement_validations``

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "requirements", ":ref:`Requirement <requirements_object_v33>`", "Specifies the requirement ID."
   "identities", ":ref:`Identities <identity_object_v33>`", "Specifies the identity ID."
   "addresses", ":ref:`Addresses <addresses_object_v33>`", "Specifies the address ID."

Examples
========

.. tabs::

   .. tab:: Validation Request Error

     .. http:example:: curl

			POST /v3/requirement_validations HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "requirement_validations",
			    "relationships": {
			      "requirement": {
			        "data": {
			          "id": "ID_of_requirements",
			          "type": "requirements"
			        }
			      },
			      "address": {
			        "data": {
			          "id": "ID_of_Address",
			          "type": "addresses"
			        }
			      },
			      "identity": {
			        "data": {
			          "id": "ID_of_Identity",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 422 Unprocessable Entity
			Content-Type: application/vnd.api+json

			{
			    "errors": [
			        {
			            "title": "Identity Place of Birth must be Germany",
			            "detail": "Identity Place of Birth must be Germany",
			            "code": "100",
			            "source": {
			                "pointer": "/data"
			            },
			            "status": "422"
			        },
			        {
			            "title": "2 Identity Proof(s) (Drivers License, National ID, Passport, Residence Permit, Visa, Other) required",
			            "detail": "2 Identity Proof(s) (Drivers License, National ID, Passport, Residence Permit, Visa, Other) required",
			            "code": "100",
			            "source": {
			                "pointer": "/data"
			            },
			            "status": "422"
			        },
			        {
			            "title": "Address in Germany required",
			            "detail": "Address in Germany required",
			            "code": "100",
			            "source": {
			                "pointer": "/data"
			            },
			            "status": "422"
			        }
			    ]
			}

   .. tab:: Validation Request Success

     .. http:example:: curl

			POST /v3/requirement_validations HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "requirement_validations",
			    "relationships": {
			      "requirement": {
			        "data": {
			          "id": "ID_of_requirements",
			          "type": "requirements"
			        }
			      },
			      "address": {
			        "data": {
			          "id": "ID_of_Address",
			          "type": "addresses"
			        }
			      },
			      "identity": {
			        "data": {
			          "id": "ID_of_Identity",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 201 Created
			Content-Type: application/vnd.api+json

			{
			    "data":
			        {
			            "id": "3553253a-99eb-4303-a16a-6b1042d3f147",
			            "type": "requirement_validations"
			            },
			        "meta": {"api_version": "2022-05-10"}
			}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 



.. _requirements_object_v33:

===================
Requirements Object
===================

Requirements Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "identity_type", "``string``", "Identity type, possible values: Business or Personal."
   "personal_area_level", "``string``", "Required location proof for Personal Identity."
   "business_area_level", "``string``", "Required location proof for Business Identity."
   "address_area_level", "``string``", "Required location proof for Address."
   "restriction_message", "``string``", "The message with requirements for specific Country/Area."
   "personal_proof_qty", "``integer``", "The quantity of proof documents required for Personal Identity."
   "business_proof_qty", "``integer``", "The quantity of proof documents required for Business Identity."
   "address_proof_qty", "``integer``", "The quantity of proof documents required for Address."
   "personal_mandatory_fields", "``array[string]``", "Mandatory fields for Personal Identity."
   "business_mandatory_fields", "``array[string]``", "Mandatory fields for Business Identity."
   "service_description_required", "``boolean``", "If Service description is required. Possible values: True/False."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v33>`"
   "did_group_type", "to-one", ":ref:`DID Group Type Object <did_group_type_object_v33>`"
   "personal_permanent_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "business_permanent_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "personal_onetime_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "business_onetime_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v33>`"
   "personal_proof_types", "to-many", ":ref:`Proof Type Object <proof_types_object_v33>`"
   "business_proof_types", "to-many", ":ref:`Proof Type Object <proof_types_object_v33>`"
   "address_proof_types", "to-many", ":ref:`Proof Type Object <proof_types_object_v33>`"


.. |br| raw:: html

   <br />

.. _address_verifications_v33:

=====================
Address Verifications
=====================

Returns a single or a list of Address Verifications in the account. Allows create a callback/webhook method to receive notifications associated with Verification Statuses.

Supported methods: ``GET``, ``POST``

.. toctree::
  :maxdepth: 1
  
  get-address-verification.rst
  get-address-verifications.rst
  create-address-verification.rst
  address-verifications-object.rst
  
  
  

.. |br| raw:: html

   <br />

========================
Get Address Verification
========================

Returns a single address verification status and reason if the verification was rejected.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/address_verifications/``

URI Query Parameters
--------------------

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "address", ":ref:`Addresses Object <addresses_object_v33>`"
   "dids", ":ref:`DID Object <did_object_v33>`"
   "dids.did_group", ":ref:`DID Group Object <did_group_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Approved Verification

     .. http:example:: curl

            GET /v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
                    "type": "address_verifications",
                    "attributes": {
                        "service_description": null,
                        "callback_url": null,
                        "callback_method": null,
                        "status": "Approved",
                        "reject_reasons": null,
                        "created_at": "2020-09-15T06:38:12.650Z",
                        "reference": "SHB-485120"
                    },
                    "relationships": {
                        "dids": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/dids",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/dids"
                            }
                        },
                        "address": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/address",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/address"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Rejected Verification

     .. http:example:: curl

            GET /v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": {
                  "id": "48e72d60-1884-4997-8755-fd2ba9f307bd",
                  "type": "address_verifications",
                  "attributes": {
                     "service_description": "string",
                     "callback_url": "http://example.com",
                     "callback_method": "GET",
                     "status": "Rejected",
                     "reject_reasons": "The proof of personal address is required ",
                     "reference": "VFG-606536",
                     "created_at": "2021-08-12T06:47:58.477Z"
                  },
                  "relationships": {
                     "dids": {
                        "links": {
                           "self": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/relationships/dids",
                           "related": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/dids"
                        }
                     },
                     "address": {
                        "links": {
                           "self": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/relationships/address",
                           "related": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/address"
                        }
                     }
                  }
               },
               "meta": {
                  "api_version": "2022-05-10"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 



.. _address_verifications_object_v33:

============================
Address Verifications Object
============================

Address Verifications Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "service_description", "``string``", "The description of the verification task."
   "callback_url", "``string``", "The HTTP or HTTPS endpoint to which events related to the verification task will be delivered."
   "callback_method", "``string``", "The HTTP method used for verification task events. Supported methods: **POST**, **GET**."
   "status", "``string``", "The current status of the verification task."
   "reference", "``string``", "The unique reference number for the verification task."
   "reject_reasons", "``string``", "The reason(s) for verification rejection."
   "created_at", "``Date&Time``", "The date and time the verification task was created."


.. |br| raw:: html

   <br />

===========================
Create Address Verification
===========================

Creates an Address Verification task and configures a callback to receive status updates. |br|
Supports linking DIDs, addresses, and optional supporting files.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/address_verifications``

URI Query Parameters
--------------------

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "service_description", "``string``", "No", "The description of verification task."
   "callback_url", "``string``", "No", "The HTTP or HTTPS endpoint to where events related to verification task will be delivered."
   "callback_method", "``string``", "No", "The HTTP Method used for verification task events. **POST**, **GET** are supported methods."

See :ref:`Callback details <callbacks_details_v33>` for information about **callback_url** and **callback_method**.

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`DID <did_object_v33>`", "Specifies the ID of DID for verification task."
   "addresses", ":ref:`Addresses <addresses_object_v33>`", "Specifies the ID of Address for verification task."
   "onetime_files", ":ref:`Encrypted Files Object <encrypted_files_object_v33>`", "Specifies Onetime files for verification task."

Testing
=======

Confirm the correct functioning of your integration by simulating approvals and rejections in the **sandbox** environment.
This can be achieved by assigning specific testing values to the **id_number** attribute of the :ref:`Identity <identity_object_v33>`, which will be utilized when creating the Address Verification.
Refer to the table below for the available options.

.. csv-table::
   :header: "Action", "id_number value"

   "approve", "11111111-1111-1111-1111-111111111111"
   "reject", "22222222-2222-2222-2222-222222222222"

Examples
========

.. tabs::

   .. tab:: Create Address Verification

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "GET"
                },
                "relationships": {
                  "dids": {
                    "data": [
                      {
                        "id": "b0c54164-03b9-42fa-b052-68a95bdab67b",
                        "type": "dids"
                      },
                      {
                        "id": "95e9d153-4881-4a6a-85a0-9b9e68f817eb",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "a1f03dae-ea44-4348-993f-ce1c68ca1c21",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6",
                    "type": "address_verifications",
                    "attributes": {
                        "service_description": null,
                        "callback_url": "http://example.com",
                        "callback_method": "GET",
                        "status": "Pending",
                        "reject_reasons": null,
                        "reference": "TTC-388920",
                        "created_at": "2023-02-27T09:01:04.275Z"
                    },
                    "relationships": {
                        "dids": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/dids",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/dids"
                            }
                        },
                        "address": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/address",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/address"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2022-05-10"
                }
            }

   .. tab:: Create Address Verification with Service Description

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                "callback_url": "http://example.com",
                "callback_method": "GET",
                "service_description": "string"
                },
                "relationships": {
                  "onetime_files": {
                    "data": [
                      {
                        "id": "96fb69e0-d5bb-4637-b740-28349f1a4274",
                        "type": "encrypted_files"
                      }
                    ]
                  },
                  "dids": {
                    "data": [
                      {
                        "id": "723ba6a6-ec10-45f5-b2ba-84be6a4e0eb2",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "f13240d5-d3cc-4c05-a529-fb63a0027118",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
                "type": "address_verifications",
                "attributes": {
                  "service_description": "string",
                  "callback_url": "http://example.com",
                  "callback_method": "GET",
                  "status": "Pending",
                  "reject_reasons": null,
                  "created_at": "2021-03-23T12:20:04.584Z",
                  "reference": "SHB-485120"
                },
                "relationships": {
                  "dids": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids",
                      "related": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids"
                    }
                  },
                  "address": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address",
                      "related": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2022-05-10"
              }
            }

   .. tab:: Verification Error

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                    "type": "address_verifications",
                    "attributes": {
                    "callback_url": "http://example.com",
                    "callback_method": "GET",
                    "service_description": "string"
                    },
                    "relationships": {
                      "onetime_files": {
                            "data": [
                              {
                                    "id": "606911e3-ae91-4717-8d16-39d85de906fc",
                                    "type": "encrypted_files"
                              }
                            ]
                      },
                      "dids": {
                            "data": [
                              {
                                    "id": "e750ea2f-b1a0-4cf7-887d-0cab23ee4138",
                                    "type": "dids"
                              }
                            ]
                      },
                      "address": {
                            "data": {
                              "id": "ef8bedc8-4e2a-4064-b2b2-e08270eabe1b",
                              "type": "addresses"
                            }
                      }
                    }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {"errors": [
                  {
                  "title": "one-time document is not needed",
                  "detail": "one-time document is not needed",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               },
                  {
                  "title": "service description is not needed",
                  "detail": "service description is not needed",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               }
            ]}

   .. tab:: Verification Error: Missing proofs

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "GET"
                },
                "relationships": {
                  "dids": {
                    "data": [
                      {
                        "id": "dd769be0-d5ef-4c6f-b000-89cd2a780d7f",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "4f97a28d-d8be-4c00-bf72-df175e4d44c3",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {"errors": [
                  {
                  "title": "1 Identity Proof(s) (National ID, Passport) required",
                  "detail": "1 Identity Proof(s) (National ID, Passport) required",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               },
                  {
                  "title": "Following Supporting Document(s) required (Germany Registration Form)",
                  "detail": "Following Supporting Document(s) required (Germany Registration Form)",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               },
                  {
                  "title": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required",
                  "detail": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               }
            ]}

   .. tab:: Verification Error: Missing mandatory fields

    .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "GET"
                },
                "relationships": {
                  "dids": {
                    "data": [
                      {
                        "id": "a2eca370-0873-4b2e-b58b-3216ad3db98c",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "1703ec4d-2fc8-4965-b7d3-3645a2e90fac",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {
                "errors": [
                    {
                        "title": "Following mandatory fields are not filled in (Contact Email)",
                        "detail": "Following mandatory fields are not filled in (Contact Email)",
                        "code": "100",
                        "source": {
                            "pointer": "/data"
                        },
                        "status": "422"
                    }
                ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

=========================
Get Address Verifications
=========================

Returns the address verifications status and reasons if the verification was rejected.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/address_verifications``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "address", ":ref:`Addresses Object <addresses_object_v33>`"
   "dids", ":ref:`DID Object <did_object_v33>`"
   "dids.did_group", ":ref:`DID Group Object <did_group_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "address.id", "``string``", "Yes", "Yes", "The ``address.id`` field."
   "address.identity.id", "``string``", "Yes", "Yes", "The ``address.identity.id`` field."
   "status", "``string``", "No", "No", "The ``status`` field."
   "reference", "``string``", "No", "Yes", "The ``reference`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "service_description", "The ``service_description`` attribute."
   "callback_url", "The ``callback_url`` attribute."
   "callback_method", "The ``callback_method`` attribute."
   "status", "The ``status`` attribute."
   "reject_reasons", "The ``reject_reasons`` attribute."
   "reference", "The ``reference`` attribute."
   "created_at", "The ``created_at`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request

     .. http:example:: curl

            GET /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": [
                  {
                        "id": "40c315d2-255c-410f-9af7-6b288c3f8ba4",
                        "type": "address_verifications",
                        "attributes": {
                           "service_description": "testing",
                           "callback_url": null,
                           "callback_method": null,
                           "status": "Rejected",
                           "reject_reasons": "The DID cannot be used for the indicated service",
                           "reference": "EGE-764403",
                           "created_at": "2021-03-22T06:24:58.295Z"
                        },
                        "relationships": {
                           "dids": {
                              "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/dids",
                                    "related": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/dids"
                              }
                           },
                           "address": {
                              "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/address",
                                    "related": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/address"
                              }
                           }
                        }
                  }
               ],
               "meta": {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links": {
                  "first": "https://sandbox-api.didww.com/v3/address_verifications?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://sandbox-api.didww.com/v3/address_verifications?page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

   .. tab:: Filter by status

     .. http:example:: curl

            GET /v3/address_verifications?filter[status]=Rejected HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "40c315d2-255c-410f-9af7-6b288c3f8ba4",
                  "type": "address_verifications",
                  "attributes":       {
                     "service_description": "testing",
                     "callback_url": null,
                     "callback_method": null,
                     "status": "Rejected",
                     "reject_reasons": "The DID cannot be used for the indicated service",
                     "reference": "EGE-764403",
                     "created_at": "2021-03-22T06:24:58.295Z"
                  },
                  "relationships":       {
                     "dids": {"links":          {
                        "self": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/dids",
                        "related": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/dids"
                     }},
                     "address": {"links":          {
                        "self": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/address",
                        "related": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/address"
                     }}
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_verifications?filter%5Bstatus%5D=Rejected&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_verifications?filter%5Bstatus%5D=Rejected&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

   .. tab:: Include dids

     .. http:example:: curl

            GET /v3/address_verifications?include=dids HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "9814cf4f-b472-4ea7-9275-565eb90be397",
                  "type": "address_verifications",
                  "attributes":       {
                     "service_description": null,
                     "callback_url": "http://example.com",
                     "callback_method": "GET",
                     "status": "Rejected",
                     "reject_reasons": "The registration form should be fully filled and signed",
                     "reference": "XNH-144620",
                     "created_at": "2021-08-11T15:43:23.263Z"
                  },
                  "relationships":       {
                     "dids":          {
                        "links":             {
                           "self": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/relationships/dids",
                           "related": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/dids"
                        },
                        "data": [            {
                           "type": "dids",
                           "id": "9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc"
                        }]
                     },
                     "address": {"links":          {
                        "self": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/relationships/address",
                        "related": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/address"
                     }}
                  }
               }],
               "included": [   {
                  "id": "9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc",
                  "type": "dids",
                  "attributes":       {
                     "blocked": true,
                     "capacity_limit": 55,
                     "description": null,
                     "terminated": false,
                     "awaiting_registration": true,
                     "created_at": "2018-11-28T09:40:31.684Z",
                     "billing_cycles_count": null,
                     "number": "4921111111111",
                     "expires_at": "2021-08-19T17:32:21.390Z",
                     "channels_included_count": 2,
                     "dedicated_channels_count": 0
                  },
                  "relationships":       {
                     "did_group": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/did_group",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/did_group"
                     }},
                     "order": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/order",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/order"
                     }},
                     "voice_in_trunk": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/voice_in_trunk",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/voice_in_trunk"
                     }},
                     "voice_in_trunk_group": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/voice_in_trunk_group",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/voice_in_trunk_group"
                     }},
                     "capacity_pool": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/capacity_pool",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/capacity_pool"
                     }},
                     "shared_capacity_group": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/shared_capacity_group",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/shared_capacity_group"
                     }},
                     "address_verification": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/address_verification",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/address_verification"
                     }}
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_verifications?include=dids&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_verifications?include=dids&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _supporting_document_template_v33:

=============================
Supporting Document Templates
=============================

Retrieves a list of supporting document templates that may be required in certain countries by regulation.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-supporting-document-template.rst
  get-supporting-document-templates.rst
  supporting-document-templates-object.rst
  
  
  



=================================
Get Supporting Document Templates
=================================

Returns a single supporting document template. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/supporting_document_templates/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Template."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
    .. http:example:: curl

		GET /v3/supporting_document_templates/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
		Host: api.didww.com
		Content-Type: application/vnd.api+json
		Accept: application/vnd.api+json
		Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": {
		        "id": "206ccec2-1166-461f-9f58-3a56823db548",
		        "type": "supporting_document_templates",
		        "attributes": {
		            "name": "Generic LOI",
		            "permanent": false,
		            "url": "https://sandbox-api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn"
		        }
		    },
		    "meta": {
		        "api_version": "2022-05-10"
		    }
		}
      





=================================
Get Supporting Document Templates
=================================

Lists all supporting document templates. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/supporting_document_templates``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
  
Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "permanent", "``boolean``", "No", "No", "The ``permanent`` field."
   "name", "``string``", "No", "No", "The ``name`` field exact match."
   "name_contains", "``string``", "No", "No", "The ``name`` field contains."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "name", "The ``name`` attribute."
   "permanent", "The ``permanent`` attribute."
   "url", "The ``url`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
    .. http:example:: curl

		GET /v3/supporting_document_templates HTTP/1.1
		Host: api.didww.com
		Content-Type: application/vnd.api+json
		Accept: application/vnd.api+json
		Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "206ccec2-1166-461f-9f58-3a56823db548",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Generic LOI",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn"
		            }
		        },
		        {
		            "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Belgium Registration Form",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra"
		            }
		        },
		        {
		            "id": "4199435f-646e-4e9d-a143-8f3b972b10c5",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Germany Special Registration Form",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/4rghqnqtba0fa7mbdgig086xej1e"
		            }
		        },
		        {
		            "id": "94be4d74-c968-4d81-91c5-2d11b4e45328",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "LOI Example",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/xptvgb8derrz0ru95wr9oi68g9tg"
		            }
		        },
		        {
		            "id": "eb810289-8620-44e1-982d-13e6cee70404",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "TestPermanDoc",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/owwqi77007ks4qx198b7su3eukg6"
		            }
		        },
		        {
		            "id": "f65149c1-b551-4444-97d7-22939445c42a",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "TestDoc4",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/txm3ftmuhyhypm6553b2874iuljg"
		            }
		        },
		        {
		            "id": "8aacfda9-f78a-4d17-8d05-82e344bf822d",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "test",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/of8dctya2w8fqf3hxu71a3hcmsa4"
		            }
		        },
		        {
		            "id": "83f83c27-af8d-43f4-a9ca-a84c363e3e25",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Brazilian DIDWW LOA",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/gvbw9l9jcegb5re30afhpu4eisvu"
		            }
		        },
		        {
		            "id": "6da59922-6c98-4cfa-bd0e-ec15f71eb1ff",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Test34",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/o9rz29nhi4eoip5obmtuv7w23cvf"
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 30,
		        "api_version": "2022-05-10"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/supporting_document_templates?page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/supporting_document_templates?page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Filter name_contains

    .. http:example:: curl

		GET /v3/supporting_document_templates?filter[name_contains]=Germany HTTP/1.1
		Host: api.didww.com
		Content-Type: application/vnd.api+json
		Accept: application/vnd.api+json
		Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "a6f8fa4f-302b-447a-880f-f68407c67e78",
                  "type": "supporting_document_templates",
                  "attributes":       {
                     "name": "Germany Registration Form",
                     "permanent": true,
                     "url": "https://api.didww.com/storage/public/kb5ovqxc43xhompzcrhh6e3fz7mo"
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2022-05-10"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/supporting_document_templates?filter%5Bname_contains%5D=Germany&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/supporting_document_templates?filter%5Bname_contains%5D=Germany&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }


.. _supporting_document_templates_object_v33:

===================================
Supporting Document Template Object
===================================

Supporting Document Template Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Name of the template"
   "url", "``string``", "URL of the template."
   "permanent", "``boolean``", "Defines if the template is permanent. Possible values: True/False."

..
   **Templates**

   .. csv-table::
      :header: "Estonia LOI Example"

      "Georgia Registration Example"
      "Germany Registration Form"
      "LOI"
      "Panama Special Registration Form"



.. _encrypted_files_v33:

===============
Encrypted Files
===============

Returns a single or a list of Encrypted Files on the account. Allows uploading the encrypted files to DIDWW server. 

.. attention::

 File format for the uploaded documents should be one of the following: JPG, PNG, PDF
 Other formats will be rejected during the verification process.
 
Encryption details is available :ref:`here <encryption_details_v33>`.

Supported methods: ``GET``, ``POST``, ``DELETE``.

.. toctree::
  :maxdepth: 1

  encryption-details.rst
  get-encrypted-file.rst
  get-encrypted-files.rst
  create-encrypted-files.rst
  delete-encrypted-files.rst
  encrypted-files-object.rst
  public-keys.rst


.. |br| raw:: html

   <br />

.. _encryption_details_v33:

==================
Encryption details
==================

Files passed to :ref:`Create Encrypted File <create_encrypted_files_v33>` should be encrypted with :ref:`DIDWW Public Keys <public_keys_v33>`.

Using SDK for encryption
========================

Recommended way of using encryption is to encrypt files in browser.
it can be achieved via `@didww/encrypt <https://github.com/didww/didww-encrypt>`_  JS library.

If you want to encrypt files on server side it can be done via following:

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Gem**
      :link: https://github.com/didww/didww-v3-ruby/blob/master/lib/didww/encrypt.rb
      :link-type: url

      Use the APIv3 Ruby gem to perform file encryption on the server side.

   .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
      :link: https://github.com/didww/didww-api-3-php-sdk/blob/master/src/Encrypt.php
      :link-type: url

      Use the official PHP SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
      :link: https://github.com/didww/didww-api-3-java-sdk/blob/main/src/main/java/com/didww/sdk/Encrypt.java
      :link-type: url

      Use the official Java SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
      :link: https://github.com/didww/didww-api-3-python-sdk/blob/main/src/didww/encrypt.py
      :link-type: url

      Use the official Python SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
      :link: https://github.com/didww/didww-api-3-typescript-sdk/blob/main/src/encrypt.ts
      :link-type: url

      Use the official TypeScript SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`logos:go` **Go Encryption Sample**
      :link: https://github.com/didww/go-encrypt-sample
      :link-type: url

       Use the Go sample project to implement server-side file encryption compatible with DIDWW API v3.

To implement encryption manually see figure:

|br|

.. figure:: https://doc.didww.com/_images/enc.png
    :figclass: align-center

    **Fig. 1.** File encryption schematic.

For additional check you need to pass fingerprint of public keys along with encrypted files.
You can use our JS library or ruby SDK for that.

To implement fingerprint calculation manually see figure:

.. figure:: https://doc.didww.com/_images/fingerprint.png
    :figclass: align-center

    **Fig. 1.** Fingerprint calculation schematic.


.. |br| raw:: html

   <br />

==================
Get Encrypted File
==================

Returns a single encrypted file. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/encrypted_files/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Encrypted File."

Examples
========

.. tabs::

   .. tab:: Encrypted File 
   
     .. http:example:: curl

			GET /v3/encrypted_files/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			    "data": [
			        {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files",
			            "attributes": {
			                "description": "Description",
			                "expire_at": "2021-03-29T14:18:19.569Z"
			            }
			        }
			    ],
			    "meta": {
			        "total_records": 1,
			        "api_version": "2022-05-10"
			    },
			    "links": {
			        "first": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50",
			        "last": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

.. _create_encrypted_files_v33:

=====================
Create Encrypted File
=====================

Creates an encrypted file on your account.

Encryption details is available :ref:`here <encryption_details_v33>`.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/encrypted_files``

Header: ``Content-Type: multipart/form-data``

URI Query Parameters
--------------------

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Parameter Type", "Type", "Is Required?", "Description"

   "encrypted_files[encryption_fingerprint]", "``formData``", "``string``", "Yes", "The encryption fingerprint."
   "encrypted_files[items][][description]", "``formData``", "``string``", "No", "The encrypted file description."
   "encrypted_files[items][][file]", "``formData``", "``file``", "Yes", "The encrypted file."

.. note::

    - Accepted file formats:

        - `.pdf`
        - `.jpg`
        - `.png`

    - You may upload up to **5 files per request**.
    - Each file **must not exceed 20 MB** in size.
    - Uploaded encrypted files will **expire after 24 hours**.

Examples
========

.. tabs::

   .. tab:: Example

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/json; charset=utf-8

            {
                "ids": [
                    "377dc5cf-55b3-45b8-9fed-156600a7f151"
                ]
            }

   .. tab:: Outdated Fingerprint

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/json
            Api-Key: [API token]

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/json; charset=utf-8

            {
                "errors": {
                    "base": [
                        "outdated fingerprint"
                    ]
                }
            }

   .. tab:: File is missing

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/json
            Api-Key: [API token]

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/json; charset=utf-8

            {
                "errors": {
                    "items/0/file": [
                        "can't be blank"
                    ]
                }
            }

   .. tab:: File is too large

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/json
            Api-Key: [API token]

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/json; charset=utf-8

            {
                "errors": {
                    "items/0/file": [
                        "size must be less than or equal to 20 MB"
                    ]
                }
            }

curl example for creating encrypted file
========================================

.. code-block::

 curl -i -X POST https://api.didww.com/v3/encrypted_files -H 'Accept: application/json' -H 'Api-Key: [API token]' -H 'Content-Type: multipart/form-data' -F 'encrypted_files[encryption_fingerprint]: c24c8711fed0fb9df377d4dad6090038063eec27:::d8919eb961da809e4d597f5c072e04383055e219' -F 'encrypted_files[items][][description]: my file' -F 'encrypted_files[items][][file]=@"/path_to_file"'

For every additional file repeat the following
==============================================

.. code-block::

    -F 'encrypted_files[items][][file]=@"/path_to_file"'

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 
   "422","No","Validation Error"


.. |br| raw:: html

   <br />

=====================
Delete Encrypted File
=====================

Deletes an encrypted file from your account. 

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/encrypted_files``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Encrypted File."

Examples
========

.. tabs::

   .. tab:: Example
   
     .. http:example:: curl

			DELETE /v3/encrypted_files/dfd8ee70-3806-446e-aa49-7b7f30a4e7d0 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
		
		    HTTP/1.1 204 Deleted
		    Content-Type: application/vnd.api+json

   

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. _encrypted_files_object_v33:

.. |br| raw:: html

   <br />

======================
Encrypted Files Object
======================

Encrypted files object attributes. 

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "description", "``string``", "The description of encrypted file."
   "expire_at", "``Date&Time``", "The expiration date for the encrypted file."

Encrypted File Item
-------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "encrypted_files[encryption_fingerprint]", "``string``", "Yes", "The encryption fingerprint."
   "encrypted_files[items][][description]", "``string``", "No", "The encrypted file description."
   "encrypted_files[items][][file]", "``file``", "Yes", "The encrypted file."

.. |br| raw:: html

   <br />

===================
Get Encrypted Files
===================

Returns a list of encrypted files in the account. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/encrypted_files``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by"

   "description", "The encrypted file description."
   "expire_at", "The expiration date of encrypted file."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns"

   "description", "The ``description`` attribute."
   "expire_at", "The ``expire_at`` attribute."

Examples
========

.. tabs::

   .. tab:: Encrypted File 
   
     .. http:example:: curl

			GET /v3/encrypted_files HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			    "data": [
			        {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files",
			            "attributes": {
			                "description": "Description",
			                "expire_at": "2021-03-29T14:18:19.569Z"
			            }
			        }
			    ],
			    "meta": {
			        "total_records": 1,
			        "api_version": "2022-05-10"
			    },
			    "links": {
			        "first": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50",
			        "last": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. _public_keys_v33:

===============
Get Public Keys
===============

Returns a list of RSA public keys which should be used for files encryption.

Encryption details is available :ref:`here <encryption_details_v33>`.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/public_keys``

Examples
========

.. tabs::

   .. tab:: Encrypted File

     .. http:example:: curl

			GET /v3/public_keys HTTP/1.1
			Host: api.didww.com
			Accept: application/vnd.api+json

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			    "data": [
			        {
			            "id": "dcf2bfcb-a1d0-3b58-bbf0-3ec22a510ba8",
			            "type": "public_keys",
			            "attributes": {
			                "key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----\n"
			            }
			        },
			        {
			            "id": "f40e1176-a4ff-36e6-b2ed-c2c2d18097a3",
			            "type": "public_keys",
			            "attributes": {
			                "key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----\n"
			            }
			        }
			    ],
			    "meta": {
			        "api_version": "2022-05-10"
			    }
			}


.. |br| raw:: html

   <br />

.. _proofs_v33:

======
Proofs
======

Allows creating or deleting identity proofs.  

Supported methods: ``POST``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  create-proof.rst
  delete-proof.rst
  proofs-object.rst


.. |br| raw:: html

   <br />

============
Create Proof
============

Creates an identity proof. 

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/proofs``

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "files", "``string``", "Yes", "The ID of :ref:`encrypted files <encrypted_files_object_v33>` associated to this proof."
   "proof_types", "``string``", "Yes", "The ID of :ref:`proof type <proof_types_object_v33>` associated to this proof."
   "entity", "``string``", "Yes", "Allowed entity types: ``identities`` or ``addresses``"

Examples
========

.. tabs::

   .. tab:: Resource Creation Example: Identities
   
     .. http:example:: curl

			POST /v3/proofs HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
			{
			  "data": {
			    "type": "proofs",
			    "relationships": {
			      "files": {
			        "data": [
			          {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files"
			          }
			        ]
			      },
			      "proof_type": {
			        "data": {
			          "id": "d2c1b3fb-29f7-46ca-ba82-b617f4630b78",
			          "type": "proof_types"
			        }
			      },
			      "entity": {
			        "data": {
			          "id": "54c92d8e-f135-4b55-ac48-748d44437509",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}	
			
			
			HTTP/1.1 201 Created
			Content-Type: application/vnd.api+json
		
			{
			    "data": {
			        "id": "84155378-88d5-456e-844d-103596e3fb2c",
			        "type": "proofs",
			        "attributes": {
			            "created_at": "2021-03-28T18:01:50.387Z",
			            "expires_at": null
			        },
			        "relationships": {
			            "proof_type": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
			                }
			            },
			            "entity": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
			                }
			            }
			        }
			    },
			    "meta": {
			        "api_version": "2022-05-10"
			    }
			}

   .. tab:: Resource Creation Example: Addresses

     .. http:example:: curl

			POST /v3/proofs HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "proofs",
			    "relationships": {
			      "files": {
			        "data": [
			          {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files"
			          }
			        ]
			      },
			      "proof_type": {
			        "data": {
			          "id": "d2c1b3fb-29f7-46ca-ba82-b617f4630b78",
			          "type": "proof_types"
			        }
			      },
			      "entity": {
			        "data": {
			          "id": "54c92d8e-f135-4b55-ac48-748d44437509",
			          "type": "addresses"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 201 Created
			Content-Type: application/vnd.api+json

			{
			    "data": {
			        "id": "84155378-88d5-456e-844d-103596e3fb2c",
			        "type": "proofs",
			        "attributes": {
			            "created_at": "2021-03-28T18:01:50.387Z",
			            "expires_at": null
			        },
			        "relationships": {
			            "proof_type": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
			                }
			            },
			            "entity": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
			                }
			            }
			        }
			    },
			    "meta": {
			        "api_version": "2022-05-10"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

============
Delete Proof
============

Deletes a proof.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/proofs/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Proof."

Examples
========

.. tabs::

   .. tab:: Example
   
     .. http:example:: curl

			DELETE /v3/proofs/ed46925b-a830-482d-917d-015858cf7ab9 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
		
		    HTTP/1.1 204 No Content
		    Content-Type: application/vnd.api+json

   

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. _proofs_object_v33:

=============
Proofs Object
=============

Proofs Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "expires_at", "``Date&Time``", "Proof expiration date."
   "created_at", "``Date&Time``", "Proof creation date."

.. |br| raw:: html

   <br />

.. _permanent_documents_v33:

==============================
Permanent Supporting Documents
==============================

Allows creating or deleting permanent documents. 

Supported methods: ``POST``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  create-permanent-document.rst
  delete-permanent-document.rst
  permanent-documents-object.rst


.. |br| raw:: html

   <br />

.. _create_permanent_supporting_document_v33:

====================================
Create Permanent Supporting Document
====================================

Creates a permanent supporting document.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/permanent_supporting_documents``

URI Query Parameters
--------------------

Request Body Object Relationship
--------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "files", "``string``", "Yes", "The ID of :ref:`encrypted files <encrypted_files_object_v33>`."
   "template", "``string``", "Yes", "The ID of :ref:`supporting documents <supporting_document_templates_object_v33>`."
   "identity", "``string``", "Yes", "The ID of :ref:`identity <identity_object_v33>`."

Examples
========

.. tabs::

   .. tab:: Example

     .. http:example:: curl

			POST /v3/permanent_supporting_documents HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "permanent_supporting_documents",
			    "relationships": {
			      "files": {
			        "data": [
			          {
			            "id": "94ec30ef-9f9c-49d6-97a9-d76e93b818c5",
			            "type": "encrypted_files"
			          }
			        ]
			      },
			      "template": {
			        "data": {
			          "id": "47051582-bbe6-4d68-95f5-d7322bbaa74e",
			          "type": "supporting_document_templates"
			        }
			      },
			      "identity": {
			        "data": {
			          "id": "01798514-ccf8-495b-b4ee-01b91c533e53",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}

		    HTTP/1.1 201 Created
		    Content-Type: application/vnd.api+json

			{
			    "data": {
			        "id": "d1a1a686-969a-4c02-954c-ae500ba74a1d",
			        "type": "permanent_supporting_documents",
			        "attributes": {
			            "created_at": "2021-03-28T18:51:59.590Z"
			        },
			        "relationships": {
			            "template": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/template",
			                    "related": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/template"
			                }
			            },
			            "identity": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/identity",
			                    "related": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/identity"
			                }
			            }
			        }
			    },
			    "meta": {
			        "api_version": "2022-05-10"
			    }
			}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

====================================
Delete Permanent Supporting Document
====================================

Deletes a permanent document. 

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/permanent_supporting_documents/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Permanent supporting document."

Examples
========

.. tabs::

   .. tab:: Example
   
     .. http:example:: curl

			DELETE /v3/permanent_supporting_documents/19510da3-c07e-4fa9-a696-6b9ab89cc172 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
		
		    HTTP/1.1 204 No Content
		    Content-Type: application/vnd.api+json

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. _permanent_documents_object_v33:

=====================================
Permanent Supporting Documents Object
=====================================

Permanent documents attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "created_at", "``Date&Time``", "Permanent documents creation date."

.. |br| raw:: html

   <br />

.. _proof_types_v33:

===========
Proof Types
===========

Returns a single or a list of Proof Types for identities and addresses.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-proof-type.rst
  get-proof-types.rst
  proof-types-object.rst
  
  
  
  

.. |br| raw:: html

   <br />

==============
Get Proof Type
==============

Returns a single proof type.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/proof_types/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Proof Type."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl

			GET /v3/proof_types/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			    "data": {
			        "id": "ab1fb565-ac55-4c73-bc55-64dc61e70169",
			        "type": "proof_types",
			        "attributes": {
			            "name": "Utility Bill",
			            "entity_type": "Address"
			        }
			    },
			    "meta": {
			        "api_version": "2022-05-10"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. |br| raw:: html

   <br />

===============
Get Proof Types
===============

Returns the list of proof types for identities or addresses.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/proof_types``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filtering", "``string``", "No", ":ref:`Filtering <api_filters>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "entity_type", "``string``", "Yes", "Yes", "The ``entity_type`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "name", "The ``name`` attribute."
   "entity_type", "The ``entity_type`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
	 .. http:example:: curl

			GET /v3/proof_types HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
				"data": [
					{
						"id": "d2c1b3fb-29f7-46ca-ba82-b617f4630b78",
						"type": "proof_types",
						"attributes": {
							"name": "Copy of Phone Bill",
							"entity_type": "Address"
						}
					},
					{
						"id": "ab1fb565-ac55-4c73-bc55-64dc61e70169",
						"type": "proof_types",
						"attributes": {
							"name": "Utility Bill",
							"entity_type": "Address"
						}
					},
					{
						"id": "634aea96-43d9-49a2-bd4e-6e8e2ce4e5e9",
						"type": "proof_types",
						"attributes": {
							"name": "Rental Receipt",
							"entity_type": "Address"
						}
					},
					{
						"id": "49f42cbd-d051-43e0-9d30-883e154bad0d",
						"type": "proof_types",
						"attributes": {
							"name": "Other",
							"entity_type": "Address"
						}
					}
				],
				"meta": {
					"total_records": 4,
					"api_version": "2022-05-10"
				}
			}

   .. tab:: Filter by entity_type

	 .. http:example:: curl

			GET /v3/proof_types?filter[entity_type]=Address HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			   "data":    [
						{
					 "id": "58b80af0-81d5-4828-abd8-37ea48f3893d",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Copy of Phone Bill",
						"entity_type": "Address"
					 }
				  },
						{
					 "id": "d29b6637-36fe-477c-941c-19965a81e96c",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Utility Bill",
						"entity_type": "Address"
					 }
				  },
						{
					 "id": "af64c2cb-8db2-4076-a667-9014a48f24a4",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Rental Receipt",
						"entity_type": "Address"
					 }
				  },
						{
					 "id": "9e24acf0-fc18-4079-b546-4f316d0e9003",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Other",
						"entity_type": "Address"
					 }
				  }
			   ],
			   "meta":    {
				  "total_records": 4,
				  "api_version": "2022-05-10"
			   }
			}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 

.. _proof_types_object_v33:

.. |br| raw:: html

   <br />

==================
Proof Types Object
==================

The proof types object attributes. 

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "The name of proof type."
   "entity_type", "``string``", "The entity type: Personal, Business or Address."

.. _areas_v33:

=====
Areas
=====
 
Returns a single or a list of regulatory areas.
If address includes information about the regulatory area, it means that address created must be within locality or region covered by the phone number's prefix.

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-area.rst
  get-areas.rst
  area-object.rst



.. _get_area_v33:

========
Get Area
========

Returns an area for a given area ID. Note that a unique identification number is allocated to each area.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/areas/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number for the area."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                "type": "areas",
                "attributes": {
                  "name": "Tuscany"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                      "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                    }
                  }
                }
              }
            }

   .. tab:: Include Country 
      
   
      .. http:example:: curl
         
            GET /v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                "type": "areas",
                "attributes": {
                  "name": "Tuscany"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                      "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "51d3fe2a-6588-496b-870c-398e627de5c4"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "51d3fe2a-6588-496b-870c-398e627de5c4",
                  "type": "countries",
                  "attributes": {
                    "name": "Italy",
                    "prefix": "39",
                    "iso": "IT"
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"

.. _area_object_v33:

===========
Area Object
===========

Area Object definition.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Area name"

Relationships
-------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v33>`"


.. _get_areas_v33:

=========
Get Areas
=========

Returns a list of areas. Maximum :ref:`page size <api_pagination>` is 1000. Default page size is 1000.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/areas``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v33>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Area ``id`` field."
   "name", "``string``", "Yes", "Yes", "Area ``name`` field. Case insensitive."
   "country.id", "``string``", "Yes", "Yes", "A ``country.id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by: "

   "name", "Area ``name`` field."

Sparse Fieldsets
----------------

.. csv-table::
   :header: "Value", "Returns:"

   "name", "Area ``name`` attribute."

Examples
========

.. tabs::

   .. tab:: Simple request
   
        .. http:example:: curl 
        
           GET /v3/areas HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]
           
           
           HTTP/2 200 OK
           Content-Type: application/vnd.api+json
           
           {
             "data": [
               {
                 "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                 "type": "areas",
                 "attributes": {
                   "name": "Tuscany"
                 },
                 "relationships": {
                   "country": {
                     "links": {
                       "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                       "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                     }
                   }
                 }
               }
             ],
              "meta": {
                  "total_records": 1,
                  "api_version": "2022-05-10"
              },
              "links": {
                  "first": "https://api.didww.com/v3/areas?page%5Bnumber%5D=1&page%5Bsize%5D=1000",
                  "last": "https://api.didww.com/v3/areas?page%5Bnumber%5D=1&page%5Bsize%5D=1000"
              }
           }

   .. tab:: Filter by name or country.id
   
      .. http:example:: curl
         
            GET /v3/areas?filter[name]=Tuscany&filter[country.id]=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                  "type": "areas",
                  "attributes": {
                    "name": "Tuscany"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                        "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                      }
                    }
                  }
                }
              ],
              "meta": {
                  "total_records": 1,
                  "api_version": "2022-05-10"
              },
              "links": {
                  "first": "https://api.didww.com/v3/areas?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Tuscany&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
                  "last": "https://api.didww.com/v3/areas?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Tuscany&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
              }
            }
            

   .. tab:: Include Country Resource
      
   
      .. http:example:: curl
         
            GET /v3/areas?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                  "type": "areas",
                  "attributes": {
                    "name": "Tuscany"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                        "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                      },
                      "data": {
                          "type": "countries",
                          "id": "51d3fe2a-6588-496b-870c-398e627de5c4"
                      }
                    }
                  }
                }
              ],
              "included": [
                {
                  "id": "51d3fe2a-6588-496b-870c-398e627de5c4",
                  "type": "countries",
                  "attributes": {
                    "name": "Italy",
                    "prefix": "39",
                    "iso": "IT"
                  }
                }
              ],
              "meta": {
                  "total_records": 1,
                  "api_version": "2022-05-10"
              },
              "links": {
                  "first": "https://api.didww.com/v3/areas?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
                  "last": "https://api.didww.com/v3/areas?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"

.. |br| raw:: html

    </br>

.. _callbacks_details_v34:

=================
Callbacks Details
=================

Callbacks allow you to receive events related to your :ref:`Orders <orders_v34>`, :ref:`Exports <export_v34>`,
:ref:`Address Verifications <address_verifications_v34>`, :ref:`Emergency Verifications <emergency_verifications_v34>`,
and :ref:`Voice Out Trunks <voice_out_trunks_v34>` via HTTP request.

Order Callback Request Parameters
=================================

Configure a **callback_url** and **callback_method** attributes for single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either ``get`` or ``post``.

With ``get`` request you will receive payload as query parameters.
``post`` request will set the "Content-Type" header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of order status change DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "ID of an order"
   "``type``", "``orders``"
   "``status``", "``completed`` or ``canceled``"

Export Callback Request Parameters
==================================

Configure a **callback_url** and **callback_method** attributes for single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either ``get`` or ``post``.

With ``get`` request you will receive payload as query parameters.
``post`` request will set the "Content-Type" header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of export complete DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "ID of an export"
   "``type``", "``exports``"
   "``status``", "``completed``"
   "``url``", "Direct download URL of the completed exported file."

.. note:: For CDR In (``cdr_in``) and CDR Out (``cdr_out``) export types created via APIv3 2026-04-16, the callback payload additionally includes a ``url`` parameter with a download link to the exported file.

Address Verification Callback Request Parameters
================================================

Configure a **callback_url** and **callback_method** attributes for a single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either ``get`` or ``post``.

    - With a ``get`` request, you will receive the payload as query parameters.
    - With a ``post`` request, DIDWW sets the "Content-Type" header to ``application/x-www-form-urlencoded`` and sends the payload in the request body.

In case of address verification status change DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "Unique ID of the address verification"
   "``type``", "Resource type, always ``address_verifications``"
   "``status``", "Verification status: ``approved`` or ``rejected``."
   "``reject_reason``", "Reason for rejection, provided if the status is ``rejected``.

   .. important:: The ``reject_reason`` field is always included, but it only contains a value when the status is ``rejected``. |br| For all other statuses, this field will be empty."
   "``reject_comment``", "Detailed compliance comment for rejection, provided if the status is ``rejected``.

   .. important:: The ``reject_comment`` field is always included, but it only contains a value when the status is ``rejected`` and a detailed rejection comment is available. |br| For all other statuses, this field will be empty."

Emergency Verification Callback Request Parameters
==================================================

Configure a **callback_url** and **callback_method** attributes for a single resource via the REST API,
and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL. **callback_method** can be either ``get`` or ``post``.

    - With a ``get`` request, you will receive the payload as query parameters.
    - With a ``post`` request, DIDWW sets the "Content-Type" header to ``application/x-www-form-urlencoded`` and sends the payload in the request body.

In case of emergency verification status change DIDWW makes an HTTP request to the **callback_url** you've set with following parameters:

.. csv-table::
   :header: "Parameter", "Description"

   "``id``", "Unique ID of the emergency verification"
   "``type``", "Resource type, always ``emergency_verifications``"
   "``status``", "Verification status: ``approved`` or ``rejected``."
   "``reject_reasons``", "Reason or reasons for rejection, provided if the status is ``rejected``.

   .. important:: The ``reject_reasons`` field is always included, but it only contains a value when the status is ``rejected``. |br| For all other statuses, this field will be empty."
   "``reject_comment``", "Detailed compliance comment for rejection, provided if the status is ``rejected``.

   .. important:: The ``reject_comment`` field is always included, but it only contains a value when the status is ``rejected`` and a detailed rejection comment is available. |br| For all other statuses, this field will be empty."
   "``emergency_calling_service_id``", "ID of the related Emergency Calling Service."

.. note:: When Emergency Calling Service is activated, an order is created and the Order Callback is triggered with the same parameters (``id``, ``type``, ``status``).

Voice OUT Trunk Callback Request Parameters
===========================================

Configure a **callback_url** attribute for single resource via the REST API,
and DIDWW will make an HTTP ``post`` request (webhook) to that URL whenever an event takes place for it.
**callback_url** can be set to any valid URL.

In case of Voice OUT Trunk being blocked due to set 24 hour limit value being reached or trunk being unblocked
DIDWW makes an HTTP ``post`` request to the **callback_url** with "Content-Type" header set to “application/json”
and body as JSON array with one or more JSON objects.

Each JSON object will have following parameters:

.. csv-table::
   :header: "Parameter", "Type", "Description"

   "``id``", "``string``", "ID of a Voice OUT Trunk"
   "``type``", "``string``", "``voice_out_trunks``"
   "``status``", "``string``", "``active`` or ``blocked``"
   "``threshold_reached``", "``boolean``", "``false`` or ``true``"
   "``created_at``", "``string``", "Date and Time of event creation"

Example
=======

.. code-block:: json

    [
        {
            "id": "f36d1d17-bd16-42b9-af42-0cfe166bf3ec",
            "type": "voice_out_trunks",
            "status": "blocked",
            "threshold_reached": true,
            "created_at": "2017-06-25T08:21:41.795Z"
        }
    ]

HTTP Request Validation
=======================

If your application exposes sensitive data or is possibly mutative to your data,
then you may want to be sure that the HTTP requests to your web application are indeed coming from DIDWW,
and not a malicious third party.
To allow you this level of security, DIDWW cryptographically signs its requests. Here's how it works:

#. Turn on TLS on your server and configure your DIDWW account to use HTTPS URLs in **callback_url**.
#. DIDWW assembles and normalizes the payload.
    * If your request is a ``post``, DIDWW takes all the ``post`` fields, sorts them alphabetically by their name, and concatenates the parameters name and value (with no delimiters).
    * If your request is a ``get``, DIDWW takes all the ``get`` query fields (except the query added to the URL itself), sorts them alphabetically by their name, and concatenates the parameters name and value (with no delimiters).
#. DIDWW normalizes the URL (the full URL with a scheme, port, query string, and fragments), concatenates with normalized payload and sign it using HMAC-SHA1 and your **API key** as the key.
#. DIDWW sends this signature in an HTTP header called **X-DIDWW-Signature**.

.. note::

 Only an **API key** with the **enable_callbacks** option enabled will be used.
 If there is no **API key** with this option enabled, then no callback will be performed.
 Therefore, it's crucial to make sure that the correct **API key** is being used to generate the **X-DIDWW-Signature**
 for the validation process to function properly.
 Callbacks can be enabled only for a single **API key**.

Then, on your end, if you want to verify the authenticity of the request,
you can leverage the built-in request validation method provided by all of our SDKs:

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Gem**
      :link: https://github.com/didww/didww-v3-ruby/blob/master/lib/didww/callback/request_validator.rb
      :link-type: url

      Use the APIv3 Ruby gem to validate callback requests and verify their authenticity.

   .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
      :link: https://github.com/didww/didww-api-3-php-sdk/blob/master/src/Callback/RequestValidator.php
      :link-type: url

      Use the official PHP SDK to validate incoming callback requests from DIDWW.

   .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
      :link: https://github.com/didww/didww-api-3-java-sdk/blob/main/src/main/java/com/didww/sdk/callback/RequestValidator.java
      :link-type: url

      Use the official Java SDK to verify the integrity and origin of callback requests.

   .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
      :link: https://github.com/didww/didww-api-3-python-sdk/blob/main/src/didww/callback/request_validator.py
      :link-type: url

      Use the official Python SDK to validate DIDWW callback request signatures.

   .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
      :link: https://github.com/didww/didww-api-3-typescript-sdk/blob/main/src/callback/request-validator.ts
      :link-type: url

      Use the official TypeScript SDK to verify callback request signatures.

   .. grid-item-card:: :iconify:`logos:go` **Go Sample**
      :link: https://github.com/didww/didww-api-3-go-sdk/blob/main/callback.go
      :link-type: url

      Use the Go sample to implement callback request validation compatible with DIDWW API v3.

Algorithm implementation details
================================

Steps to perform validation manually:

#. Take the full URL of the request URL you specify in the **callback_url** attribute, from the protocol (https...) through the end of the query string (everything after the ?).
#. If the request is a ``post``, sort all of the ``post`` parameters alphabetically (using Unix-style case-sensitive sorting order).
#. If the request is a ``get``, sort all of the query parameters alphabetically (except that are specifically set in **callback_url**, using Unix-style case-sensitive sorting order).
#. For ``post`` requests iterate through the sorted list of ``post`` parameters, and append the variable name and value (with no delimiters) to the end of the URL string.
#. For ``get`` requests iterate through the sorted list of ``get`` parameters (except that are specifically set in **callback_url**) and append the variable name and value (with no delimiters) to the end of the URL string.
#. Sign the resulting string with HMAC-SHA1 using your **API key** as the key (remember, your API key's case matters!).
#. Encode the resulting hash as a hex-encoded string (each byte of result data transformed into hex from 00 to ff, most encryption libraries have a function that returns hex digest on the previous step).
#. Compare your hash to ours, submitted in the **X-DIDWW-Signature** header. If they match, then you're good to go.

Here's an example. DIDWW made a ``post`` to your application as part of an order callback:

..  code-block::

    https://mycompany.com/didww_callbacks?opaque=123

And DIDWW posted the following ``post`` fields:

 * type: :code:`orders`
 * status: :code:`completed`
 * id: :code:`bf2cee72-6caa-4ae2-917e-bea01945691e`

Create a string that is your URL with the full query string and explicitly set the port:

..  code-block::

    https://mycompany.com:443/didww_callbacks?opaque=123

Then, sort the list of ``post`` variables by the parameter name (using Unix-style case-sensitive sorting order):

 * id: :code:`bf2cee72-6caa-4ae2-917e-bea01945691e`
 * status: :code:`completed`
 * type: :code:`orders`

Next, append each ``post`` variable, name and value, to the string with no delimiters:

..  code-block::

    https://mycompany.com:443/didww_callbacks?opaque=123idbf2cee72-6caa-4ae2-917e-bea01945691estatuscompletedtypeorders

Hash the resulting string using HMAC-SHA1, using following test API key :code:`szrdgh6547umt7tht7xbqhj6g9gdbyp7`
and encode as a hex-encoded string

The resulting signature should be :code:`30f66e9d72eb5e193051fd02952f70d8e934b4ff`

.. note::

 Concerned about SHA1 security issues? DIDWW does not use SHA-1 alone.
 In short, the critical component of HMAC-SHA1 that distinguishes it from SHA-1 alone is the use of your **DIDWW API key** as a complex secret key.
 While there are possible collision-based attacks on SHA-1, HMACs are not affected by those same attacks -
 it's the combination of the underlying hashing algorithm (SHA-1) and the strength of the secret key (API key) that protects you in this case.

IP addresses
============
Requests are being sent from IPv4 network 46.19.208.0/21 and IPv6 network 2a01:ad00::/32

HTTP Response Error Handling
============================

When DIDWW receives **non 2XX** response status code from an HTTP request to the **callback_url** it will re-attempt to send it again up to 9 times.

After 10 attempt DIDWW will stop sending callback event.

HTTP request timeout more than 60 seconds will consider as failed response.

.. csv-table::
   :header: "Callback attempt ", "Wait interval"

   "2", "1 minute "
   "3", "10 minutes "
   "4", "30 minutes"
   "5", "1 hour"
   "6", "3 hours"
   "7", "6 hours "
   "8", "12 hours "
   "9", "1 day "
   "10", "2 days "

Testing Callbacks on local machine behind NAT
=============================================

In order to test Callbacks feature on local servers behind NAT, tools such as `ngrok <https://ngrok.com/docs/start>`_ or `localtunnel <https://theboroer.github.io/localtunnel-www/>`_ could be used.
These tools allows you to expose a web server running on your local machine to the internet.


.. _changelog_2026_04_16:

=========
Changelog
=========

This changelog lists API changes introduced in version ``2026-04-16``.

New Endpoints
=============

.. dropdown:: ``/v3/did_history`` **added read endpoints**

   ``/v3/did_history`` read endpoints are available.

   **What changed**

   - Added ``GET`` ``/v3/did_history``.
   - Added ``GET`` ``/v3/did_history/{id}``.
   - The resource returns DID history records from the last ``90`` days.
   - The default sort order is ``created_at`` in descending order.
   - Pagination defaults to ``50`` records per page.
   - ``GET`` ``/v3/did_history`` supports filtering by ``id``, ``did_number``, ``action``, ``method``, ``created_at_gteq``, and ``created_at_lteq``.
   - ``GET`` ``/v3/did_history`` supports sorting by ``created_at``.

   **Behavior notes**

   - Records are sourced from events shown on the billing Histories page.
   - Supported ``action`` values are ``assigned``, ``renewed``, ``canceled``, ``removed``, ``billing_cycles_count_changed``, and ``restored``.
   - Supported ``method`` values are ``system``, ``api2``, ``api3``, ``staff``, and ``user_panel``.
   - Records with ``action = billing_cycles_count_changed`` also return ``meta.from`` and ``meta.to``.
   - ``id`` is the UUID of the DID history event.
   - Older billing history records in the ``90``-day window are backfilled with UUID values.

   **Affected resources**

   - :doc:`Get DID Histories <inventory-resources/did-history/get-did-histories>`
   - :doc:`Get DID History <inventory-resources/did-history/get-did-history>`
   - :ref:`DID History Object <did_history_object_v34>`

.. dropdown:: ``/v3/emergency_calling_services`` added read and delete endpoints

   ``/v3/emergency_calling_services`` read and delete endpoints are available.

   **What changed**

   - Added ``GET`` ``/v3/emergency_calling_services``.
   - Added ``GET`` ``/v3/emergency_calling_services/{id}``.
   - Added ``DELETE`` ``/v3/emergency_calling_services/{id}``.
   - Emergency calling service responses include ``name``, ``reference``, ``status``, ``activated_at``, ``canceled_at``, ``created_at``, and ``renew_date``.
   - Responses include ``meta.setup_price`` and ``meta.monthly_price``.
   - Supported relationships are ``country``, ``did_group_type``, ``order``, ``emergency_requirement``, ``emergency_verification``, and ``dids``.
   - Collection filters include ``status``, ``country.id``, ``did_group_type.id``, ``name``, ``reference``, ``address.id``, and ``identity.id``.
   - Collection sorting includes ``name``, ``status``, ``country.name``, ``renew_date``, and ``created_at``.

   **Affected resources**

   - :doc:`Get Emergency Calling Services <emergency-resources/emergency-calling-services/get-emergency-calling-services>`
   - :doc:`Get Emergency Calling Service <emergency-resources/emergency-calling-services/get-emergency-calling-service>`
   - :doc:`Delete Emergency Calling Service <emergency-resources/emergency-calling-services/delete-emergency-calling-service>`
   - :ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`

.. dropdown:: ``/v3/emergency_requirement_validations`` added write endpoint

   ``/v3/emergency_requirement_validations`` write endpoint is available.

   **What changed**

   - Added ``POST`` ``/v3/emergency_requirement_validations``.
   - The request validates an ``address`` and / or ``identity`` against a selected ``emergency_requirement``.
   - Successful validation returns a JSON:API resource with type ``emergency_requirement_validations``.
   - Validation failures return JSON:API ``422`` error objects.

   **Affected resources**

   - :doc:`Emergency Requirement Validations <emergency-resources/emergency-requirements/emergency-requirement-validations>`
   - :ref:`Emergency Requirement Object <emergency_requirement_object_v34>`

.. dropdown:: ``/v3/emergency_requirements`` added read endpoints

   ``/v3/emergency_requirements`` read endpoints are available.

   **What changed**

   - Added ``GET`` ``/v3/emergency_requirements``.
   - Added ``GET`` ``/v3/emergency_requirements/{id}``.
   - Emergency requirement responses include ``identity_type``, ``address_area_level``, ``personal_area_level``, ``business_area_level``, ``address_mandatory_fields``, ``personal_mandatory_fields``, ``business_mandatory_fields``, ``estimate_setup_time``, and ``requirement_restriction_message``.
   - Responses include ``meta.setup_price`` and ``meta.monthly_price``.
   - Supported relationships are ``country`` and ``did_group_type``.
   - Collection filters include ``id``, ``country.id``, and ``did_group_type.id``.

   **Behavior notes**

   - ``meta.setup_price`` is returned as ``0`` when the customer's emergency plan has a matching rate for the requirement, even if the configured setup price is greater than zero.
   - ``meta.monthly_price`` returns the monthly price from the matching emergency plan rate.
   - ``meta.setup_price`` and ``meta.monthly_price`` are both ``null`` when the customer has no matching emergency plan rate for that country and DID group type.

   **Affected resources**

   - :doc:`Get Emergency Requirements <emergency-resources/emergency-requirements/get-emergency-requirements>`
   - :doc:`Get Emergency Requirement <emergency-resources/emergency-requirements/get-emergency-requirement>`
   - :ref:`Emergency Requirement Object <emergency_requirement_object_v34>`

.. dropdown:: ``/v3/emergency_verifications`` added read, write, and update endpoints

   ``/v3/emergency_verifications`` read, write, and update endpoints are available.

   **What changed**

   - Added ``GET`` ``/v3/emergency_verifications``.
   - Added ``GET`` ``/v3/emergency_verifications/{id}``.
   - Added ``POST`` ``/v3/emergency_verifications`` for create and resubmission flows.
   - Added ``PATCH`` ``/v3/emergency_verifications/{id}``.
   - Only ``external_reference_id`` can be updated through the emergency verification update flow.
   - Emergency verification responses include ``reference``, ``status``, ``reject_reasons``, ``reject_comment``, ``callback_url``, ``callback_method``, ``created_at``, and ``external_reference_id``.
   - Supported relationships are ``address``, ``emergency_calling_service``, and ``dids``.
   - Collection filters include ``status`` and ``emergency_calling_service.id``.

   **Behavior notes**

   - The verification flow supports creating a new Emergency Calling Service by sending ``address`` plus ``dids``.
   - The same endpoint supports resubmitting / updating an existing calling service by sending ``emergency_calling_service`` plus ``address``.
   - Emergency Calling Services support filtering by ``address.id`` and ``identity.id`` of the last linked verification.
   - Requests can return per-DID validation errors under pointers like ``/data/relationships/dids/{uuid}``.

   **Affected resources**

   - :doc:`Get Emergency Verifications <emergency-resources/emergency-verifications/get-emergency-verifications>`
   - :doc:`Get Emergency Verification <emergency-resources/emergency-verifications/get-emergency-verification>`
   - :doc:`Create Emergency Verification <emergency-resources/emergency-verifications/create-emergency-verification>`
   - :doc:`Update Emergency Verification <emergency-resources/emergency-verifications/update-emergency-verification>`
   - :ref:`Emergency Verification Object <emergency_verification_object_v34>`

Breaking Changes
================

.. dropdown:: ``/v3/requirement_validations`` changed to ``/v3/address_requirement_validations``

   ``/v3/requirement_validations`` is renamed to ``/v3/address_requirement_validations``.

   **Why this is a breaking change**

   Requests sent to the previous validation endpoint are no longer valid..

   **What changed**

   - Renamed ``POST`` ``/v3/requirement_validations`` to ``POST`` ``/v3/address_requirement_validations``.
   - Requests to the previous endpoint path now return ``400 Bad Request``.

   **Affected resources**

   - :doc:`Address Requirement Validations <regulation-resources/requirements/address-requirement-validations>`

   **Upgrade**

   - Replace ``/v3/requirement_validations`` with ``/v3/address_requirement_validations`` in validation requests and tests.

.. dropdown:: ``/v3/requirements`` changed to ``/v3/address_requirements``

   ``/v3/requirements`` is renamed to ``/v3/address_requirements``.

   **Why this is a breaking change**

   Requests sent to the previous requirements endpoints are no longer valid.

   **What changed**

   - Renamed ``GET`` ``/v3/requirements`` to ``GET`` ``/v3/address_requirements``.
   - Renamed ``GET`` ``/v3/requirements/{id}`` to ``GET`` ``/v3/address_requirements/{id}``.
   - Requests to the previous endpoint path now return ``400 Bad Request``.

   **Affected resources**

   - :doc:`Get Address Requirements <regulation-resources/requirements/get-address-requirements>`
   - :doc:`Get Address Requirement <regulation-resources/requirements/get-address-requirement>`
   - :ref:`Address Requirement Object <address_requirement_object_v34>`

   **Upgrade**

   - Replace ``/v3/requirements`` with ``/v3/address_requirements`` in all requests, tests, and internal references.

.. dropdown:: ``/v3/address_requirement_validations`` rename ``requirement`` relationship to ``address_requirement``

   ``/v3/address_requirement_validations`` now uses ``address_requirement`` instead of ``requirement`` for this relationship.

   **Why this is a breaking change**

   Integrations that still send or parse the ``requirement`` relationship must switch to ``address_requirement``.

   **What changed**

   - Renamed the ``requirement`` relationship in validation payloads to ``address_requirement``.
   - DID group responses also use ``address_requirement`` in place of the previous requirement relationship name.
   - The JSON:API resource type now uses ``address_requirements`` / ``address_requirement_validations``.

   **Affected resources**

   - :doc:`Address Requirement Validations <regulation-resources/requirements/address-requirement-validations>`
   - :doc:`Get DID Groups <coverage-resources/did-group/get-did-groups>`
   - :doc:`Get DID Group <coverage-resources/did-group/get-did-group>`

   **Upgrade**

   - Replace the ``requirement`` relationship key with ``address_requirement`` in request payloads and response parsing.
   - Update JSON:API ``type`` values and fixtures accordingly.

.. dropdown:: ``/v3/address_verifications`` attribute ``reject_reasons`` changed from string to array of strings

   ``/v3/address_verifications`` now returns ``reject_reasons`` as an array of strings.

   **Why this is a breaking change**

   Integrations that still parse ``reject_reasons`` as a single string must update their response handling.

   **What changed**

   - ``reject_reasons`` is now returned as an array of strings instead of a single string.

   **Affected resources**

   - :doc:`Get Address Verifications <regulation-resources/address-verifications/get-address-verifications>`
   - :doc:`Get Address Verification <regulation-resources/address-verifications/get-address-verification>`
   - :doc:`Create Address Verification <regulation-resources/address-verifications/create-address-verification>`
   - :ref:`Address Verifications Object <address_verifications_object_v34>`

   **Upgrade**

   - Update response parsing, serializers, and tests to treat ``reject_reasons`` as an array.

.. dropdown:: ``/v3/available_dids`` filter ``did_group.features`` no longer include ``sms_out`` value

   ``/v3/available_dids`` no longer supports ``sms_out`` for the ``did_group.features`` filter.

   **Why this is a breaking change**

   Requests that still use ``sms_out`` in ``filter[did_group.features]`` must be updated to the supported values.

   **What changed**

   - ``GET`` ``/v3/available_dids?filter[did_group.features]`` no longer accepts ``sms_out``.

   **Affected resources**

   - :doc:`Get Available DIDs <coverage-resources/available-did/get-available-dids>`

   **Upgrade**

   - Replace ``sms_out`` in available DID feature filtering with the supported values.

.. dropdown:: ``/v3/dids`` filter ``did_group.features`` no longer includes ``sms_out`` value

   ``/v3/dids`` no longer supports ``sms_out`` for the ``did_group.features`` filter.

   **Why this is a breaking change**

   Requests that still use ``sms_out`` in DID feature filtering must be updated to the supported values.

   **What changed**

   - ``GET`` ``/v3/dids?filter[did_group.features]`` no longer accepts ``sms_out``.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`

   **Upgrade**

   - Replace ``sms_out`` in DID feature filters with the supported values.

.. dropdown:: ``/v3/did_groups`` ``features`` attribute and filter no longer include ``sms_out`` value

   ``/v3/did_groups`` features attribute and filter no longer include sms_out value.

   **Why this is a breaking change**

   Integrations that still read or send ``sms_out`` in DID group feature values or feature filters must switch to the updated feature set.

   **What changed**

   - DID group ``features`` no longer include ``sms_out``.
   - DID group feature filtering no longer accepts ``sms_out``.

   **Affected resources**

   - :doc:`Get DID Groups <coverage-resources/did-group/get-did-groups>`
   - :doc:`Get DID Group <coverage-resources/did-group/get-did-group>`
   - :ref:`DID Group Object <did_group_object_v34>`

   **Upgrade**

   - Remove ``sms_out`` from DID group feature parsing and feature filters.
   - Update any typed models or tests that still expect ``sms_out``.

.. dropdown:: ``/v3/did_reservations`` attribute ``expire_at`` renamed to ``expires_at``

   ``/v3/did_reservations`` now uses expires_at instead of expire_at.

   **Why this is a breaking change**

   Integrations that still read ``expire_at`` from DID reservation responses must switch to ``expires_at``.

   **What changed**

   - Renamed the DID reservation expiry attribute from ``expire_at`` to ``expires_at``.
   - ``GET`` and ``POST`` DID reservation responses now return ``expires_at``.

   **Affected resources**

   - :doc:`Get DID Reservations <coverage-resources/did-reservation/get-did-reservations>`
   - :doc:`Get DID Reservation <coverage-resources/did-reservation/get-did-reservation>`
   - :doc:`Create DID Reservation <coverage-resources/did-reservation/create-did-reservation>`
   - :ref:`DID Reservation Object <did_reservation_object_v34>`

   **Upgrade**

   - Replace ``expire_at`` with ``expires_at`` in response parsing, typed models, and tests.

.. dropdown:: ``/v3/encrypted_files`` attribute ``expire_at`` renamed to ``expires_at``

   ``/v3/encrypted_files`` now uses expires_at instead of expire_at.

   **Why this is a breaking change**

   Integrations that still read ``expire_at`` from encrypted file responses must switch to ``expires_at``.

   **What changed**

   - Renamed the encrypted file expiry attribute from ``expire_at`` to ``expires_at``.
   - ``GET`` ``/v3/encrypted_files`` now returns ``expires_at``.
   - ``GET`` ``/v3/encrypted_files/{id}`` now returns ``expires_at``.

   **Affected resources**

   - :doc:`Get Encrypted Files <regulation-resources/encrypted-files/get-encrypted-files>`
   - :doc:`Get Encrypted File <regulation-resources/encrypted-files/get-encrypted-file>`
   - :ref:`Encrypted Files Object <encrypted_files_object_v34>`

   **Upgrade**

   - Replace ``expire_at`` with ``expires_at`` in response parsing, typed models, and tests.

.. dropdown:: ``/v3/encrypted_files`` POST request body format changed: single file per request instead of batch ``items`` array

   ``/v3/encrypted_files`` now uses the updated POST request body format.

   **Why this is a breaking change**

   API no longer uses the legacy batch request format or plain JSON response bodies for ``POST`` ``/v3/encrypted_files``.

   **What changed**

   - ``POST`` ``/v3/encrypted_files`` now accepts flat single-file parameters:
     - ``encrypted_files[encryption_fingerprint]``
     - ``encrypted_files[description]``
     - ``encrypted_files[file]``
   - ``POST`` ``/v3/encrypted_files`` now returns a JSON:API resource object on success.
   - ``POST`` ``/v3/encrypted_files`` now returns JSON:API error objects for ``400`` and ``422`` responses.
   - Legacy batch parameters such as ``encrypted_files[items][][file]`` are not supported.

   **Affected resources**

   - :doc:`Create Encrypted File <regulation-resources/encrypted-files/create-encrypted-files>`
   - :ref:`Encrypted Files Object <encrypted_files_object_v34>`
   - :ref:`Bad Request Error Object <api_bad_request>`
   - :ref:`Validation Error Object <api_validation_error_object>`

   **Upgrade**

   - Stop sending legacy batch parameters such as ``encrypted_files[items][][file]``.
   - Send exactly one file per request using ``encrypted_files[file]``.
   - Parse successful and error responses as JSON:API documents.

.. dropdown:: ``/v3/exports`` filters ``year`` and ``month`` replaced with ``from`` and ``to`` datetime filters for ``cdr_in`` and ``cdr_out`` export types

   ``/v3/exports`` now uses from and to datetime filters for cdr_in and cdr_out export types instead of year and month.

   **Why this is a breaking change**

   Requests that still use the previous ``year`` and ``month`` filters for ``cdr_in`` and ``cdr_out`` exports must be updated.

   **What changed**

   - Replaced the previous ``year`` and ``month`` filters with ``from`` and ``to`` datetime filters for ``cdr_in`` and ``cdr_out`` export types.

   **Affected resources**

   - :doc:`Create Export <export/create-export>`
   - :doc:`Get Exports <export/get-exports>`
   - :ref:`Export Object <export_object_v34>`

   **Upgrade**

   - Replace ``year`` and ``month`` with ``from`` and ``to`` in export creation and filtering workflows.

.. dropdown:: ``/v3/voice_out_trunks`` attributes ``allowed_sip_ips``, ``allowed_rtp_ips``, ``username``, ``password`` removed in favor of ``authentication_method`` object

   ``/v3/voice_out_trunks`` now uses authentication_method object instead of the previous attributes.

   **Why this is a breaking change**

   Integrations must stop reading or writing top-level authentication fields and must move authentication handling into ``authentication_method``. ``allowed_rtp_ips`` is now handled as a top-level outbound trunk attribute.

   **What changed**

   - Added the ``authentication_method`` object with supported types ``credentials_and_ip``, ``ip_only``, and ``twilio``.
   - ``GET`` endpoints return authentication data only inside ``authentication_method``.
   - ``allowed_rtp_ips`` is now a top-level outbound trunk attribute.
   - Changing the authentication type clears the previous authentication attributes.
   - ``PATCH`` ``/v3/voice_out_trunks/{id}`` does not allow changing ``authentication_method.type`` to ``ip_only``.

   **Behavior notes**

   - ``credentials_and_ip`` returns ``allowed_sip_ips``, ``tech_prefix``, ``username``, and ``password`` inside ``authentication_method.attributes``.
   - ``ip_only`` returns ``allowed_sip_ips`` and ``tech_prefix`` inside ``authentication_method.attributes`` and does not return credentials.
   - ``twilio`` returns only ``twilio_account_sid`` inside ``authentication_method.attributes``.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`
   - :doc:`Get Outbound Trunk <inventory-resources/voice-out-trunks/get-voice-out-trunk>`
   - :doc:`Create Outbound Trunk <inventory-resources/voice-out-trunks/create-voice-out-trunk>`
   - :doc:`Update Outbound Trunk <inventory-resources/voice-out-trunks/update-voice-out-trunk>`
   - :doc:`Outbound Trunk Regenerate Credentials <inventory-resources/voice-out-trunks/voice-out-trunk-regenerate-credentials>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`

   **Upgrade**

   - Move outbound trunk authentication parsing and request building into ``authentication_method``.
   - Move any ``allowed_rtp_ips`` handling to ``data.attributes.allowed_rtp_ips``.
   - Update tests and serializers to stop expecting flat authentication fields.

.. dropdown:: multiple resources attribute values standardized to lowercase snake_case format

   Multiple APIv3 resources now use lowercase snake_case values consistently in responses, write requests, filters, and sorting-related value descriptions.

   **Why this is a breaking change**

   Integrations that still send or parse Title Case, uppercase, or space-separated values must update to the normalized lowercase snake_case values.

   **What changed**

   - Order statuses now use ``pending``, ``completed``, and ``canceled``.
   - Export statuses now use ``pending``, ``processing``, and ``completed``.
   - Address verification statuses now use ``pending``, ``approved``, and ``rejected``.
   - Emergency Calling Service statuses now use ``new``, ``in_process``, ``changes_required``, ``active``, ``pending_update``, and ``canceled``.
   - Outbound trunk status and enum-like attributes now use lowercase snake_case values such as ``active``, ``blocked``, ``reject_call``, ``replace_cli``, ``send_original_cli``, ``allow_all``, ``reject_all``, ``disabled``, ``srtp_sdes``, ``srtp_dtls``, and ``zrtp``.
   - Identity types now use ``personal`` and ``business``.
   - Callback methods now use ``get`` and ``post``.
   - Requirement area-level values now use ``world_wide``, ``country``, ``area``, and ``city`` where applicable.

   **Behavior notes**

   - The normalization applies to ``GET`` responses, supported ``POST`` / ``PATCH`` request values, filter values, and the documented value sets used in collection sorting and query parameter tables.
   - Values that were already using lowercase snake_case, such as ``cdr_in``, ``cdr_out``, ``voice_in`` and ``credentials_and_ip``, are unchanged.

   **Affected resources**

   - :ref:`Order Object <order_object_v34>`
   - :ref:`Export Object <export_object_v34>`
   - :ref:`Address Verifications Object <address_verifications_object_v34>`
   - :ref:`Identity Object <identity_object_v34>`
   - :ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`
   - :ref:`Emergency Verification Object <emergency_verification_object_v34>`
   - :ref:`Address Requirement Object <address_requirement_object_v34>`
   - :ref:`Emergency Requirement Object <emergency_requirement_object_v34>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`
   - :doc:`Callbacks Details <callbacks-details>`

   **Upgrade**

   - Update request payloads, filter values, response parsing, fixtures, and tests to use lowercase snake_case values only.
   - Treat previous Title Case, uppercase, and space-separated values as obsolete.

Enhancements
============

.. dropdown:: ``/v3/address_verifications`` attribute ``external_reference_id`` added

   ``/v3/address_verifications`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to address verification requests and responses.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Address Verification <regulation-resources/address-verifications/create-address-verification>`
   - :doc:`Get Address Verifications <regulation-resources/address-verifications/get-address-verifications>`
   - :doc:`Get Address Verification <regulation-resources/address-verifications/get-address-verification>`
   - :ref:`Address Verifications Object <address_verifications_object_v34>`

.. dropdown:: ``/v3/address_verifications`` added update endpoint

   ``PATCH`` ``/v3/address_verifications/{id}`` is available and only ``external_reference_id`` can be changed.

   **What changed**

   - Added ``PATCH`` ``/v3/address_verifications/{id}``.
   - Only ``external_reference_id`` can be updated through the address verification update flow.

   **Affected resources**

   - :doc:`Update Address Verification <regulation-resources/address-verifications/update-address-verification>`
   - :doc:`Get Address Verifications <regulation-resources/address-verifications/get-address-verifications>`
   - :doc:`Get Address Verification <regulation-resources/address-verifications/get-address-verification>`
   - :ref:`Address Verifications Object <address_verifications_object_v34>`

.. dropdown:: ``/v3/address_verifications`` attribute ``reject_comment`` added

   ``/v3/address_verifications`` now supports reject_comment.

   **What changed**

   - Added ``reject_comment`` to ``address_verifications`` responses.
   - Added ``reject_comment`` to ``emergency_verifications`` responses.
   - Address verification callbacks now include ``reject_comment`` alongside the rejection fields.
   - Emergency verification callbacks now include ``reject_comment`` alongside the rejection fields.

   **Behavior notes**

   - ``reject_comment`` provides the detailed compliance comment shown for rejected verifications.

   **Affected resources**

   - :doc:`Get Address Verifications <regulation-resources/address-verifications/get-address-verifications>`
   - :doc:`Get Address Verification <regulation-resources/address-verifications/get-address-verification>`
   - :doc:`Create Address Verification <regulation-resources/address-verifications/create-address-verification>`
   - :ref:`Address Verifications Object <address_verifications_object_v34>`
   - :doc:`Callbacks Details <callbacks-details>`

.. dropdown:: ``/v3/addresses`` attribute ``external_reference_id`` added

   ``/v3/addresses`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to address requests and responses.
   - Added exact-match ``external_reference_id`` filtering on collection responses where supported.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Addresses <regulation-resources/addresses/create-address>`
   - :doc:`Update Addresses <regulation-resources/addresses/update-address>`
   - :doc:`Get Addresses <regulation-resources/addresses/get-addresses>`
   - :ref:`Addresses Object <addresses_object_v34>`

.. dropdown:: ``/v3/available_dids`` filter ``did_group.features`` support new values ``emergency``, ``cnam_out``, ``a2p`` and ``p2p``

   ``/v3/available_dids`` now supports additional values for the did_group.features filter.

   **What changed**

   - ``GET`` ``/v3/available_dids?filter[did_group.features]`` now supports ``emergency``.
   - ``GET`` ``/v3/available_dids?filter[did_group.features]`` now supports ``cnam_out``.
   - ``GET`` ``/v3/available_dids?filter[did_group.features]`` now supports ``a2p`` and ``p2p``.

   **Affected resources**

   - :doc:`Get Available DIDs <coverage-resources/available-did/get-available-dids>`

.. dropdown:: ``/v3/did_groups`` attribute ``service_restrictions`` added

   ``/v3/did_groups`` now supports service_restrictions.

   **What changed**

   - Added the ``service_restrictions`` attribute to DID group responses.
   - ``service_restrictions`` returns the DID group service restriction message when restrictions apply.
   - ``service_restrictions`` can be ``null`` when no restriction message applies.

   **Affected resources**

   - :doc:`Get DID Groups <coverage-resources/did-group/get-did-groups>`
   - :doc:`Get DID Group <coverage-resources/did-group/get-did-group>`
   - :ref:`DID Group Object <did_group_object_v34>`

.. dropdown:: ``/v3/did_groups`` ``features`` attribute and filter support new values ``emergency``, ``cnam_out``, ``a2p`` and ``p2p``

   ``/v3/did_groups`` features attribute and filter support new values emergency, cnam_out, a2p and p2p.

   **What changed**

   - DID group ``features`` now support ``emergency``.
   - DID group ``features`` now support ``cnam_out``.
   - DID group ``features`` now support ``a2p`` and ``p2p`` for outbound messaging capabilities.
   - ``GET`` ``/v3/did_groups?filter[features]=emergency`` filters DID groups that support the emergency feature.

   **Affected resources**

   - :doc:`Get DID Groups <coverage-resources/did-group/get-did-groups>`
   - :doc:`Get DID Group <coverage-resources/did-group/get-did-group>`
   - :ref:`DID Group Object <did_group_object_v34>`

.. dropdown:: ``/v3/dids`` attribute ``emergency_enabled`` added

   ``/v3/dids`` now supports emergency_enabled.

   **What changed**

   - Added the ``emergency_enabled`` attribute to DID responses.
   - ``filter[emergency_enabled]`` can be used to find DIDs that are or are not assigned to an Emergency Calling Service.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`
   - :doc:`Get DID <inventory-resources/did/get-did>`
   - :ref:`DID Object <did_object_v34>`

.. dropdown:: ``/v3/dids`` filter ``did_group.features`` support new values ``emergency``, ``cnam_out``, ``a2p`` and ``p2p``

   ``/v3/dids`` now supports additional values for the did_group.features filter.

   **What changed**

   - ``GET`` ``/v3/dids?filter[did_group.features]`` now supports ``emergency``.
   - ``GET`` ``/v3/dids?filter[did_group.features]`` now supports ``cnam_out``.
   - ``GET`` ``/v3/dids?filter[did_group.features]`` now supports ``a2p`` and ``p2p``.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`

.. dropdown:: ``/v3/dids`` filter ``emergency_calling_service.id`` and filter ``emergency_enabled`` added

   ``/v3/dids`` now supports the emergency_calling_service.id and filter emergency_enabled filter.

   **What changed**

   - Added ``filter[emergency_calling_service.id]``.
   - Added ``filter[emergency_enabled]``.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`

.. dropdown:: ``/v3/dids`` relationship ``emergency_calling_service`` added

   ``/v3/dids`` now exposes the emergency_calling_service relationship.

   **What changed**

   - Added the ``emergency_calling_service`` relationship to DID responses.
   - When a DID is assigned to an Emergency Calling Service, relationship data identifies that service.
   - When a DID is not assigned to an Emergency Calling Service, relationship data is ``null`` when relationship data is present.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`
   - :doc:`Get DID <inventory-resources/did/get-did>`
   - :ref:`DID Object <did_object_v34>`

.. dropdown:: ``/v3/dids`` relationship ``emergency_verification`` added

   ``/v3/dids`` now exposes the emergency_verification relationship.

   **What changed**

   - Added the ``emergency_verification`` relationship to DID responses.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`
   - :doc:`Get DID <inventory-resources/did/get-did>`
   - :ref:`DID Object <did_object_v34>`

.. dropdown:: ``/v3/dids`` relationship ``identity`` added

   ``/v3/dids`` now exposes the identity relationship.

   **What changed**

   - Added the ``identity`` relationship to DID responses.
   - ``GET`` ``/v3/dids?include=identity`` returns included identity resources.

   **Behavior notes**

   - The relationship represents the main identity assigned to the DID, or the porting identity as a fallback.

   **Affected resources**

   - :doc:`Get DIDs <inventory-resources/did/get-dids>`
   - :doc:`Get DID <inventory-resources/did/get-did>`
   - :ref:`DID Object <did_object_v34>`

.. dropdown:: ``/v3/exports`` attribute ``external_reference_id`` added

   ``/v3/exports`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to export requests and responses.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Export <export/create-export>`
   - :doc:`Get Exports <export/get-exports>`
   - :doc:`Get Export <export/get-export>`
   - :ref:`Export Object <export_object_v34>`

.. dropdown:: ``/v3/exports`` added update endpoint

   ``/v3/exports`` update is available and only external_reference_id can be changed.

   **What changed**

   - Added an export update endpoint.
   - Only ``external_reference_id`` can be updated through the export update flow.

   **Affected resources**

   - :doc:`Get Exports <export/get-exports>`
   - :doc:`Get Export <export/get-export>`
   - :ref:`Export Object <export_object_v34>`

.. dropdown:: ``/v3/exports`` attribute ``filters`` added

   ``/v3/exports`` now supports filters.

   **What changed**

   - Added the ``filters`` attribute to export responses.

   **Affected resources**

   - :doc:`Get Exports <export/get-exports>`
   - :doc:`Get Export <export/get-export>`
   - :ref:`Export Object <export_object_v34>`

.. dropdown:: ``/v3/exports`` ``cdr_in`` export CSV columns renamed and new columns added

   ``/v3/exports`` cdr_in export CSV columns renamed and new columns added.

   **What changed**

   - ``cdr_in`` export CSV columns were renamed.
   - Additional columns were added to ``cdr_in`` export files.

   **Affected resources**

   - :doc:`Create Export <export/create-export>`
   - :doc:`Get Exports <export/get-exports>`

.. dropdown:: ``/v3/exports`` ``cdr_out`` export CSV columns renamed and new columns added

   ``/v3/exports`` cdr_out export CSV columns renamed and new columns added.

   **What changed**

   - ``cdr_out`` export CSV columns were renamed.
   - Additional columns were added to ``cdr_out`` export files.

   **Affected resources**

   - :doc:`Create Export <export/create-export>`
   - :doc:`Get Exports <export/get-exports>`

.. dropdown:: ``/v3/exports`` export callback includes ``url`` attribute with the download link

   ``/v3/exports`` callbacks now include additional export file information.

   **What changed**

   - Added ``url`` to the export callback payload for supported export types.
   - The callback can include a direct download link to the exported file.

   **Affected resources**

   - :doc:`Callbacks Details <callbacks-details>`
   - :doc:`Get Export <export/get-export>`
   - :ref:`Export Object <export_object_v34>`

.. dropdown:: ``/v3/identities`` relationship ``birth_country`` added

   ``/v3/identities`` now exposes the birth_country relationship.

   **What changed**

   - Added the ``birth_country`` relationship to ``GET`` ``/v3/identities`` and ``GET`` ``/v3/identities/{id}``.
   - ``POST`` ``/v3/identities`` supports sending ``birth_country`` separately from ``country``.
   - ``PATCH`` ``/v3/identities/{id}`` supports updating ``birth_country`` separately from ``country``.
   - ``PATCH`` ``/v3/identities/{id}`` supports removing ``birth_country`` by sending an empty string.
   - ``birth_country`` is no longer auto-assigned when ``country`` is set.

   **Affected resources**

   - :doc:`Get Identities <regulation-resources/identities/get-identities>`
   - :doc:`Get Identity <regulation-resources/identities/get-identity>`
   - :doc:`Create Identity <regulation-resources/identities/create-identity>`
   - :doc:`Update Identity <regulation-resources/identities/update-identity>`
   - :ref:`Identity Object <identity_object_v34>`

   **Upgrade**

   - Send and parse ``birth_country`` independently from ``country``.

.. dropdown:: ``/v3/orders`` attribute ``external_reference_id`` added

   ``/v3/orders`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to order requests and responses.
   - ``external_reference_id`` is optional.
   - ``external_reference_id`` has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Order <inventory-resources/order/create-order>`
   - :doc:`Get Orders <inventory-resources/order/get-orders>`
   - :doc:`Get Order <inventory-resources/order/get-order>`
   - :ref:`Order Object <order_object_v34>`

.. dropdown:: ``/v3/orders`` added update endpoint

   ``/v3/orders`` update is available and only external_reference_id can be changed.

   **What changed**

   - Added an order update endpoint.
   - Only ``external_reference_id`` can be updated through the order update flow.

   **Affected resources**

   - :doc:`Create Order <inventory-resources/order/create-order>`
   - :doc:`Get Orders <inventory-resources/order/get-orders>`
   - :doc:`Get Order <inventory-resources/order/get-order>`
   - :ref:`Order Object <order_object_v34>`

.. dropdown:: ``/v3/orders`` filter ``external_reference_id`` added

   ``/v3/orders`` now supports the external_reference_id filter.

   **What changed**

   - Added the ``external_reference_id`` collection filter to orders.

   **Affected resources**

   - :doc:`Get Orders <inventory-resources/order/get-orders>`

.. dropdown:: ``/v3/orders`` insufficient funds error response includes ``meta`` with ``total_cost`` and ``available_balance``

   ``/v3/orders`` now returns additional metadata in insufficient funds error responses.

   **What changed**

   - Added ``errors[].meta.total_cost``.
   - Added ``errors[].meta.available_balance``.
   - Both values are returned as strings.
   - This applies to both DID order creation and capacity order creation.

   **Behavior notes**

   - ``meta.total_cost`` contains the cost of the current order only.
   - ``meta.available_balance`` contains the customer's available balance, including credit, at the time of the check.

   **Affected resources**

   - :doc:`Create Order <inventory-resources/order/create-order>`
   - :ref:`Insufficient Balance Error Object <api_insufficient_balance_error_object>`

   **Upgrade**

   - Read ``errors[].meta.total_cost`` and ``errors[].meta.available_balance`` when presenting insufficient balance failures to users.
   - Update automated tests for insufficient balance responses.

.. dropdown:: ``/v3/orders`` attribute ``allow_back_ordering`` defaults to ``true`` when not provided in request

   ``/v3/orders`` attribute allow_back_ordering defaults to true when not provided in request.

   **What changed**

   - ``POST`` ``/v3/orders`` now defaults ``allow_back_ordering`` to ``true``.
   - If ``allow_back_ordering`` is omitted, a DID order with pending inventory can be created instead of returning a validation error.
   - To limit ordering to currently available inventory only, requests must explicitly send ``allow_back_ordering: false``.

   **Affected resources**

   - :doc:`Create Order <inventory-resources/order/create-order>`

   **Upgrade**

   - Explicitly send ``allow_back_ordering: false`` if your workflow must reject out-of-stock DID orders.

.. dropdown:: ``/v3/orders`` Emergency order item attribute ``emergency_calling_service_id`` added

   ``/v3/orders`` Emergency order item attribute emergency_calling_service_id added.

   **What changed**

   - ``GET`` ``/v3/orders`` and ``GET`` ``/v3/orders/{id}`` can now return ``emergency_order_items``.
   - ``emergency_order_items`` include ``emergency_calling_service_id``.
   - Orders created by the Emergency Calling activation flow return ``callback_method: null`` and ``callback_url: null``.
   - ``meta.api_version`` reflects the actual API version used to produce the response.

   **Behavior notes**

   - Earlier API versions may continue to return emergency charges as ``generic_order_items`` for backward compatibility.

   **Affected resources**

   - :doc:`Get Orders <inventory-resources/order/get-orders>`
   - :doc:`Get Order <inventory-resources/order/get-order>`
   - :ref:`Order Object <order_object_v34>`

.. dropdown:: ``/v3/permanent_supporting_documents`` attribute ``external_reference_id`` added

   ``/v3/permanent_supporting_documents`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to permanent supporting document requests and responses.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Permanent Supporting Document <regulation-resources/permanent-documents/create-permanent-document>`
   - :doc:`Get Permanent Supporting Documents <regulation-resources/permanent-documents/get-permanent-documents>`
   - :doc:`Get Permanent Supporting Document <regulation-resources/permanent-documents/get-permanent-document>`
   - :ref:`Permanent Documents Object <permanent_documents_object_v34>`

.. dropdown:: ``/v3/permanent_supporting_documents`` added read endpoints

   ``/v3/permanent_supporting_documents`` read endpoints are available.

   **What changed**

   - Added ``GET`` ``/v3/permanent_supporting_documents``.
   - Added ``GET`` ``/v3/permanent_supporting_documents/{id}``.
   - The collection endpoint supports JSON:API pagination and sparse fieldsets.
   - The collection endpoint supports exact-match filtering by ``external_reference_id``.

   **Affected resources**

   - :doc:`Get Permanent Supporting Documents <regulation-resources/permanent-documents/get-permanent-documents>`
   - :doc:`Get Permanent Supporting Document <regulation-resources/permanent-documents/get-permanent-document>`
   - :ref:`Permanent Documents Object <permanent_documents_object_v34>`

.. dropdown:: ``/v3/proofs`` attribute ``external_reference_id`` added

   ``/v3/proofs`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to proof requests and responses.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Proof <regulation-resources/proofs/create-proof>`
   - :doc:`Get Proofs <regulation-resources/proofs/get-proofs>`
   - :doc:`Get Proof <regulation-resources/proofs/get-proof>`
   - :ref:`Proofs Object <proofs_object_v34>`

.. dropdown:: ``/v3/proofs`` added read endpoints

   ``/v3/proofs`` read endpoints are available.

   **What changed**

   - Added ``GET`` ``/v3/proofs``.
   - Added ``GET`` ``/v3/proofs/{id}``.
   - The collection endpoint supports JSON:API pagination and sparse fieldsets.
   - The collection endpoint supports exact-match filtering by ``external_reference_id``.

   **Affected resources**

   - :doc:`Get Proofs <regulation-resources/proofs/get-proofs>`
   - :doc:`Get Proof <regulation-resources/proofs/get-proof>`
   - :ref:`Proofs Object <proofs_object_v34>`

.. dropdown:: ``/v3/shared_capacity_groups`` attribute ``external_reference_id`` added

   ``/v3/shared_capacity_groups`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to Shared Capacity Group requests and responses.
   - Added exact-match ``external_reference_id`` filtering on collection responses where supported.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Shared Capacity Groups <inventory-resources/shared-capacity-group/create-shared-capacity-group>`
   - :doc:`Update Shared Capacity Groups <inventory-resources/shared-capacity-group/update-shared-capacity-group>`
   - :doc:`Get Shared Capacity Groups <inventory-resources/shared-capacity-group/get-shared-capacity-groups>`
   - :ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`

.. dropdown:: ``/v3/voice_in_trunk_groups`` attribute ``external_reference_id`` added

   ``/v3/voice_in_trunk_groups`` now supports external_reference_id.

   **What changed**

   - Added ``external_reference_id`` to Inbound Trunk Group requests and responses.
   - Added exact-match ``external_reference_id`` filtering on collection responses where supported.
   - ``external_reference_id`` is optional and has a maximum length of ``100`` characters.

   **Affected resources**

   - :doc:`Create Voice IN Trunk Group <inventory-resources/voice-in-trunk-groups/create-trunk-group>`
   - :doc:`Update Voice IN Trunk Group <inventory-resources/voice-in-trunk-groups/update-trunk-group>`
   - :doc:`Get Voice IN Trunk Groups <inventory-resources/voice-in-trunk-groups/get-trunk-groups>`
   - :ref:`Voice IN Trunk Group Object <voice_in_trunk_group_object_v34>`

.. dropdown:: ``/v3/voice_in_trunks`` SIP configuration attributes ``network_protocol_priority``, ``enabled_sip_registration``, ``use_did_in_ruri``, ``diversion_relay_policy``, ``diversion_inject_mode``, and ``cnam_lookup`` added

   ``/v3/voice_in_trunks`` now supports additional SIP configuration attributes.

   **What changed**

   - Added ``network_protocol_priority``.
   - Added ``enabled_sip_registration``.
   - Added ``use_did_in_ruri``.
   - Added ``diversion_relay_policy``.
   - Added ``diversion_inject_mode``.
   - Added ``cnam_lookup``.

   **Behavior notes**

   - ``use_did_in_ruri`` works only when ``enabled_sip_registration`` is ``true``.

   **Affected resources**

   - :doc:`Get Voice IN Trunks <inventory-resources/voice-in-trunks/get-voice-in-trunks>`
   - :doc:`Get Voice IN Trunk <inventory-resources/voice-in-trunks/get-voice-in-trunk>`
   - :doc:`Create Voice IN Trunk <inventory-resources/voice-in-trunks/create-voice-in-trunk>`
   - :doc:`Update Voice IN Trunk <inventory-resources/voice-in-trunks/update-voice-in-trunk>`
   - :ref:`Inbound Trunk Object <voice_in_trunk_object_v34>`

.. dropdown:: ``/v3/voice_out_trunks`` attribute ``authentication_method`` added with support for ``ip_only``, ``credentials_and_ip``, and ``twilio`` types

   ``/v3/voice_out_trunks`` attribute authentication_method added with support for ip_only, credentials_and_ip, and twilio types.

   **What changed**

   - Added the ``authentication_method`` object.
   - Supported authentication method types are ``ip_only``, ``credentials_and_ip``, and ``twilio``.
   - ``POST`` ``/v3/voice_out_trunks`` supports creation with ``credentials_and_ip`` and ``twilio``.
   - ``PATCH`` ``/v3/voice_out_trunks/{id}`` supports switching between supported updatable authentication types.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`
   - :doc:`Get Outbound Trunk <inventory-resources/voice-out-trunks/get-voice-out-trunk>`
   - :doc:`Create Outbound Trunk <inventory-resources/voice-out-trunks/create-voice-out-trunk>`
   - :doc:`Update Outbound Trunk <inventory-resources/voice-out-trunks/update-voice-out-trunk>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`

.. dropdown:: ``/v3/voice_out_trunks`` attribute ``emergency_enable_all`` added

   ``/v3/voice_out_trunks`` now supports emergency_enable_all.

   **What changed**

   - Added the ``emergency_enable_all`` attribute to outbound trunk requests and responses.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`
   - :doc:`Get Outbound Trunk <inventory-resources/voice-out-trunks/get-voice-out-trunk>`
   - :doc:`Create Outbound Trunk <inventory-resources/voice-out-trunks/create-voice-out-trunk>`
   - :doc:`Update Outbound Trunk <inventory-resources/voice-out-trunks/update-voice-out-trunk>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`

.. dropdown:: ``/v3/voice_out_trunks`` attribute ``rtp_timeout`` added

   ``/v3/voice_out_trunks`` now supports rtp_timeout.

   **What changed**

   - Added the ``rtp_timeout`` attribute to outbound trunk requests and responses.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`
   - :doc:`Get Outbound Trunk <inventory-resources/voice-out-trunks/get-voice-out-trunk>`
   - :doc:`Create Outbound Trunk <inventory-resources/voice-out-trunks/create-voice-out-trunk>`
   - :doc:`Update Outbound Trunk <inventory-resources/voice-out-trunks/update-voice-out-trunk>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`

.. dropdown:: ``/v3/voice_out_trunks`` attribute ``tech_prefix`` added

   ``/v3/voice_out_trunks`` now supports tech_prefix.

   **What changed**

   - Added ``tech_prefix`` inside ``authentication_method.attributes`` for ``credentials_and_ip`` and ``ip_only``.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`
   - :doc:`Get Outbound Trunk <inventory-resources/voice-out-trunks/get-voice-out-trunk>`
   - :doc:`Create Outbound Trunk <inventory-resources/voice-out-trunks/create-voice-out-trunk>`
   - :doc:`Update Outbound Trunk <inventory-resources/voice-out-trunks/update-voice-out-trunk>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`

.. dropdown:: ``/v3/voice_out_trunks`` filter ``authentication_method.type`` added

   ``/v3/voice_out_trunks`` now supports the authentication_method.type filter.

   **What changed**

   - Added ``filter[authentication_method.type]``.
   - Supported values are ``credentials_and_ip``, ``ip_only``, and ``twilio``.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`

.. dropdown:: ``/v3/voice_out_trunks`` relationship ``emergency_dids`` added

   ``/v3/voice_out_trunks`` now exposes the emergency_dids relationship.

   **What changed**

   - Added the ``emergency_dids`` relationship to outbound trunk responses.
   - ``GET`` ``/v3/voice_out_trunks?include=emergency_dids`` and ``GET`` ``/v3/voice_out_trunks/{id}?include=emergency_dids`` return related DID data in the ``included`` array.

   **Affected resources**

   - :doc:`Get Outbound Trunks <inventory-resources/voice-out-trunks/get-voice-out-trunks>`
   - :doc:`Get Outbound Trunk <inventory-resources/voice-out-trunks/get-voice-out-trunk>`
   - :ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`


.. _quantity_based_price_object_v34:

===================================
Channel Quantity Based Price Object
===================================

Quantity based pricing lets you automatically apply different discount prices to channels in Capacity pool that depend on the quantity.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "setup_price", "``string``", "Price for Order creation per channel."
   "monthly_price", "``string``", "Monthly price for Order renew based on Capacity pool billing cycle date (renew_date)."
   "qty", "``integer``", "Quantity on channels from which price per channel will be with discount."




===========
Definitions
===========

.. toctree::
  :maxdepth: 1

  stock-keeping-unit-object.rst
  channel-quantity-based-price-object.rst


.. _stock_keeping_unit_object_v34:

=========================
Stock Keeping Unit Object
=========================

Unique identification ID of inventory unit.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "setup_price", "``string``", "Price for Order creation."
   "monthly_price", "``string``", "Monthly price for order renew."
   "channels_included_count", "``integer``", "Included channels capacity for each DID."


.. _available_did_object_v34:

====================
Available DID Object
====================

Available DID Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "number","``string``","DID Number"

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "did_group", "to-one", ":ref:`DID Group Object <did_group_object_v34>`. Returns the DID Group linked to the available DID."
   "nanpa_prefix", "to-one", ":ref:`NANPA Prefix Object <nanpa_prefix_object_v34>`. Returns the NANPA prefix linked to the available DID when applicable."




=================
Get Available DID
=================

Returns a single Available DID from DIDWW inventory.

.. note::

 Available DID request is not enabled by default. To enable this feature, please contact our Customer Service or Sales Departments. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/available_dids/``

.. note:: For all returned data attributes, see :doc:`Available Did Object <available-did-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number of the Available DID."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"
   "nanpa_prefix", ":ref:`Nanpa Prefix Object <nanpa_prefix_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple request
   
        .. http:example:: curl
        
           GET /v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144 HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API token]
           
           
           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json
           
            {
                "data": {
                    "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                    "type": "available_dids",
                    "attributes": {
                        "number": "12124727604"
                    },
                    "relationships": {
                        "did_group": {
                            "links": {
                                "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                                "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                            }
                        },
                        "nanpa_prefix": {
                            "links": {
                                "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                                "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Include did_group
   
      .. http:example:: curl
      
        GET /v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144?include=did_group HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json        

        {
            "data": {
                "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                "type": "available_dids",
                "attributes": {
                    "number": "12124727604"
                },
                "relationships": {
                    "did_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                        },
                        "data": {
                            "type": "did_groups",
                            "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c"
                        }
                    },
                    "nanpa_prefix": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                        }
                    }
                }
            },
            "included": [
                {
                    "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "212",
                        "features": [
                            "voice_in",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "New York",
                        "allow_additional_channels": true,
                        "service_restrictions": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/stock_keeping_units"
                            }
                        },
                        "address_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/address_requirement",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/address_requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 8
                    }
                }
            ],
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Include did_group.stock_keeping_units
   
      .. http:example:: curl
      
        GET /v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144?include=did_group.stock_keeping_units HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
            "data": {
                "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                "type": "available_dids",
                "attributes": {
                    "number": "12124727604"
                },
                "relationships": {
                    "did_group": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                        },
                        "data": {
                            "type": "did_groups",
                            "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c"
                        }
                    },
                    "nanpa_prefix": {
                        "links": {
                            "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                            "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                        }
                    }
                }
            },
            "included": [
                {
                    "id": "916c8f4d-2108-4d79-853b-7c545ee83f8c",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "212",
                        "features": [
                            "voice_in",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "New York",
                        "allow_additional_channels": true,
                        "service_restrictions": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/stock_keeping_units"
                            },
                            "data": [
                                {
                                    "type": "stock_keeping_units",
                                    "id": "af589936-3e8d-498c-b127-8054ef026dfa"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "5dec9d3e-f25a-4ac3-a9b0-efcdd9ec744b"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "e48e981f-ab6d-48a6-aaf6-e75539fc1011"
                                }
                            ]
                        },
                        "address_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/relationships/address_requirement",
                                "related": "https://api.didww.com/v3/did_groups/916c8f4d-2108-4d79-853b-7c545ee83f8c/address_requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 8
                    }
                },
                {
                    "id": "af589936-3e8d-498c-b127-8054ef026dfa",
                    "type": "stock_keeping_units",
                    "attributes": {
                        "setup_price": "0.0",
                        "monthly_price": "0.09",
                        "channels_included_count": 0
                    }
                },
                {
                    "id": "5dec9d3e-f25a-4ac3-a9b0-efcdd9ec744b",
                    "type": "stock_keeping_units",
                    "attributes": {
                        "setup_price": "0.0",
                        "monthly_price": "0.19",
                        "channels_included_count": 2
                    }
                },
                {
                    "id": "e48e981f-ab6d-48a6-aaf6-e75539fc1011",
                    "type": "stock_keeping_units",
                    "attributes": {
                        "setup_price": "4.42",
                        "monthly_price": "4.42",
                        "channels_included_count": 5
                    }
                }
            ],
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _available_dids_v34_get_available_dids:

==================
Get Available DIDs
==================

Returns a list of Available DIDs. :ref:`Pagination <api_pagination>` and :ref:`Sorting <api_sorting>` are disabled.

.. warning::

   Do not use the number selection tool to populate another database with available numbers, as DID inventory changes frequently.

.. note::

   - The ``/v3/available_dids`` endpoint is disabled by default. Contact **Customer Service** or **Sales** to enable it.
   - Results are returned in random order.
   - Requests are not cached. A new request may return the same results as a previous one, depending on the filters applied.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/available_dids``

.. note:: For all returned data attributes, see :doc:`Available Did Object <available-did-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
   "fields[available_dids]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"
   "nanpa_prefix", ":ref:`Nanpa Prefix Object <nanpa_prefix_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Available DID ``id`` field."
   "number_contains", "``string``", "No", "No", "The ``number`` field."
   "did_group.id", "``string``", "No", "Yes", "DID Group ``id`` field."
   "did_group_type.id", "``string``", "No", "Yes", "DID Group ``type id`` field."
   "country.id", "``string``", "No", "Yes", "DID Group ``country id`` field."
   "region.id", "``string``", "No", "Yes", "DID Group ``region id`` field."
   "city.id", "``string``", "No", "Yes", "DID Group ``city id`` field."
   "did_group.needs_registration", "``boolean``", "No", "No", "DID Group ``needs_registration`` field."
   "did_group.features", "``string``", "No", "Yes", "DID Group ``features`` field. Can be one or several of ``voice_in``, ``voice_out``, ``t38``, ``sms_in``, ``p2p``, ``a2p``, ``emergency``, and ``cnam_out``. Example: ``voice_in,emergency``."
   "nanpa_prefix.id", "``string``", "No", "No", "Nanpa prefix ``id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/available_dids HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": [
                    {
                        "id": "55ac507c-6248-412a-abbb-a02bbe7034e6",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727600"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/55ac507c-6248-412a-abbb-a02bbe7034e6/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "54563944-801d-40ba-add1-b9e48b669493",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14803023230"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/54563944-801d-40ba-add1-b9e48b669493/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "126607e3-1ff7-4399-89cf-aea426c47134",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858120"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/126607e3-1ff7-4399-89cf-aea426c47134/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "90113411-3037-4f25-a33b-7898b601f271",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858091"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/90113411-3037-4f25-a33b-7898b601f271/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "a017bb1a-b4b1-48cb-9331-31bf6394f191",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858035"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/a017bb1a-b4b1-48cb-9331-31bf6394f191/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "7f396769-5203-470c-9595-b158c6bba7c8",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727603"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "065fda4b-1730-4e20-81d0-96f7335347ea",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727606"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "5dead00e-6751-411a-929b-a25e5bace5b0",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858086"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/5dead00e-6751-411a-929b-a25e5bace5b0/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727604"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_count": 361188,
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Include did_group and did_group.stock_keeping_units
      
   
      .. http:example:: curl
         
            GET /v3/available_dids?include=did_group&include=did_group.stock_keeping_units HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": [
                    {
                        "id": "1f5c3a09-03ea-4adb-98ac-37075753ecfd",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907306"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/1f5c3a09-03ea-4adb-98ac-37075753ecfd/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "93796469-642e-49d9-945d-473904c10591",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316908161"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/93796469-642e-49d9-945d-473904c10591/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "fe44fba4-a5c9-4e01-a5c3-1e9075e91638",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907298"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/fe44fba4-a5c9-4e01-a5c3-1e9075e91638/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "2b86c154-1576-416e-a6c9-d6a1f1479cea",
                        "type": "available_dids",
                        "attributes": {
                            "number": "17634977780"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "07ff1c6f-23cb-4938-a5cb-abb751e67c46"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/2b86c154-1576-416e-a6c9-d6a1f1479cea/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "6d391601-51cd-4e22-ae1d-f58153b5bd2a",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907218"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/6d391601-51cd-4e22-ae1d-f58153b5bd2a/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "4449880c-d11a-431c-ae94-32bf61f43655",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316908157"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/4449880c-d11a-431c-ae94-32bf61f43655/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "3f186a11-c01e-41be-ad0a-8d1611078e74",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907182"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/3f186a11-c01e-41be-ad0a-8d1611078e74/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "57180089-2d22-4508-b2b4-0f6a69730dd2",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907303"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/57180089-2d22-4508-b2b4-0f6a69730dd2/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "033d2f74-ef23-4779-95ed-3c0e3bbe2363",
                        "type": "available_dids",
                        "attributes": {
                            "number": "18197718303"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "b77cfb79-be19-44d7-a2e6-39c28253df73"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/033d2f74-ef23-4779-95ed-3c0e3bbe2363/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "630ec71a-f86b-4543-bd72-4799144fe5d7",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316908151"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/did_group"
                                },
                                "data": {
                                    "type": "did_groups",
                                    "id": "80672e46-0ca9-4d45-8709-a537a526d7cc"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/630ec71a-f86b-4543-bd72-4799144fe5d7/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "80672e46-0ca9-4d45-8709-a537a526d7cc",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "631",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Nogales",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/stock_keeping_units"
                                },
                                "data": [
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "11005837-36ac-49a0-91b7-97a0f35829b1"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "697ce6ad-73f3-458d-8bd3-dd1f33718c2a"
                                    }
                                ]
                            },
                            "address_requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/relationships/address_requirement",
                                    "related": "https://api.didww.com/v3/did_groups/80672e46-0ca9-4d45-8709-a537a526d7cc/address_requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 231
                        }
                    },
                    {
                        "id": "07ff1c6f-23cb-4938-a5cb-abb751e67c46",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "763",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Osseo",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/stock_keeping_units"
                                },
                                "data": [
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "aef9387a-6b7e-489c-9927-818e27a20b57"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "2418d053-f6ed-44a4-8414-926ba7193e53"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "ad642989-191f-4df6-80e3-176942ef5643"
                                    }
                                ]
                            },
                            "address_requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/relationships/address_requirement",
                                    "related": "https://api.didww.com/v3/did_groups/07ff1c6f-23cb-4938-a5cb-abb751e67c46/address_requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 1
                        }
                    },
                    {
                        "id": "b77cfb79-be19-44d7-a2e6-39c28253df73",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "819",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Ottawa-Hull",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/stock_keeping_units"
                                },
                                "data": [
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "09c1ebf4-f52c-413b-92bc-960d089f4fc8"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "a0b4086c-7734-4d41-962a-6f9b9593ad6d"
                                    },
                                    {
                                        "type": "stock_keeping_units",
                                        "id": "dc8b2df7-23b6-4723-b918-84efb987eae5"
                                    }
                                ]
                            },
                            "address_requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/relationships/address_requirement",
                                    "related": "https://api.didww.com/v3/did_groups/b77cfb79-be19-44d7-a2e6-39c28253df73/address_requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 2
                        }
                    },
                    {
                        "id": "11005837-36ac-49a0-91b7-97a0f35829b1",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "3.82",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "697ce6ad-73f3-458d-8bd3-dd1f33718c2a",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "6.99",
                            "channels_included_count": 2
                        }
                    },
                    {
                        "id": "aef9387a-6b7e-489c-9927-818e27a20b57",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.09",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "2418d053-f6ed-44a4-8414-926ba7193e53",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.19",
                            "channels_included_count": 2
                        }
                    },
                    {
                        "id": "ad642989-191f-4df6-80e3-176942ef5643",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "4.42",
                            "monthly_price": "4.42",
                            "channels_included_count": 5
                        }
                    },
                    {
                        "id": "09c1ebf4-f52c-413b-92bc-960d089f4fc8",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.18",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "a0b4086c-7734-4d41-962a-6f9b9593ad6d",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.28",
                            "channels_included_count": 2
                        }
                    },
                    {
                        "id": "dc8b2df7-23b6-4723-b918-84efb987eae5",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "4.42",
                            "monthly_price": "4.42",
                            "channels_included_count": 5
                        }
                    }
                ],
                "meta": {
                    "total_count": 361188,
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Include nanpa_prefix

      .. http:example:: curl

            GET /v3/available_dids?include=nanpa_prefix HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "c6ff0b43-aed2-4697-b2d5-6ec8ca36a415",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14805539893"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/c6ff0b43-aed2-4697-b2d5-6ec8ca36a415/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9"
                                }
                            }
                        }
                    },
                    {
                        "id": "b721db67-a85b-4e76-9df0-5e2977f99655",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14802405726"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/b721db67-a85b-4e76-9df0-5e2977f99655/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "34bed380-d056-4d2f-909b-4463f1935ec6"
                                }
                            }
                        }
                    },
                    {
                        "id": "c99679cf-7f5d-45de-b86f-1e7606e603fc",
                        "type": "available_dids",
                        "attributes": {
                            "number": "19164148368"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/c99679cf-7f5d-45de-b86f-1e7606e603fc/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "11049f22-ac70-4a1f-8ef3-e95f86f19aae"
                                }
                            }
                        }
                    },
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e"
                                }
                            }
                        }
                    },
                    {
                        "id": "f0bd90e3-ce64-4b4e-935b-afe75f600e8f",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858027"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/f0bd90e3-ce64-4b4e-935b-afe75f600e8f/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "41686b02-738b-4fa0-bb0e-cf20c5761c5e"
                                }
                            }
                        }
                    },
                    {
                        "id": "065fda4b-1730-4e20-81d0-96f7335347ea",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727606"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/065fda4b-1730-4e20-81d0-96f7335347ea/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e"
                                }
                            }
                        }
                    },
                    {
                        "id": "cbaf7322-c045-45f1-9b2a-6a3ce59ad27a",
                        "type": "available_dids",
                        "attributes": {
                            "number": "17328579010"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/cbaf7322-c045-45f1-9b2a-6a3ce59ad27a/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "209e3b8a-c72e-46c3-a7ff-5de4975d93cc"
                                }
                            }
                        }
                    },
                    {
                        "id": "f54296e7-fcfd-4693-ae11-b8700c41cc72",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14806858151"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/f54296e7-fcfd-4693-ae11-b8700c41cc72/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "41686b02-738b-4fa0-bb0e-cf20c5761c5e"
                                }
                            }
                        }
                    },
                    {
                        "id": "05ca4efd-f73f-4cc9-a0db-8c2248291f4a",
                        "type": "available_dids",
                        "attributes": {
                            "number": "14807174998"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/05ca4efd-f73f-4cc9-a0db-8c2248291f4a/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "249a5255-31e1-4501-afee-80e4d7d1b06b"
                                }
                            }
                        }
                    },
                    {
                        "id": "75a21935-acfd-4160-8485-9fb7d049f144",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727604"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/75a21935-acfd-4160-8485-9fb7d049f144/nanpa_prefix"
                                },
                                "data": {
                                    "type": "nanpa_prefixes",
                                    "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "553"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1c8c762e-e1bf-4b57-a2c7-13b5d2b984c9/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "34bed380-d056-4d2f-909b-4463f1935ec6",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "240"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/34bed380-d056-4d2f-909b-4463f1935ec6/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "11049f22-ac70-4a1f-8ef3-e95f86f19aae",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "916",
                            "nxx": "414"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/11049f22-ac70-4a1f-8ef3-e95f86f19aae/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "43af8c26-8dd0-41af-ba02-3617fbcbd76e",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "212",
                            "nxx": "472"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/43af8c26-8dd0-41af-ba02-3617fbcbd76e/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "41686b02-738b-4fa0-bb0e-cf20c5761c5e",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "685"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/41686b02-738b-4fa0-bb0e-cf20c5761c5e/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "209e3b8a-c72e-46c3-a7ff-5de4975d93cc",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "732",
                            "nxx": "857"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/209e3b8a-c72e-46c3-a7ff-5de4975d93cc/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "249a5255-31e1-4501-afee-80e4d7d1b06b",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "480",
                            "nxx": "717"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/249a5255-31e1-4501-afee-80e4d7d1b06b/region"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_count": 361188,
                    "api_version": "2026-04-16"
                }
            }
             
Response
========

Top Level Meta Attributes
-------------------------

.. csv-table::
   :header: "Name", "Type", "Description"
   :widths: 4, 3, 10
   
   "total_count","``integer``","Total count of available DIDs that match the query."
   "available_count","``integer``","Count of available DIDs for reservation." 

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _available_dids_v34:
 
=============
Available DID
=============
 
Returns a single or a list of available DID numbers included in DIDWW inventory. 

.. note::

 Available DIDs request is not enabled by default. To enable this feature, please contact our Customer Service or Sales Departments.

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-available-did.rst
  get-available-dids.rst
  available-did-object.rst



.. _city_object_v34:

===========
City Object
===========

City Object definition.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","City name"

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`. Returns the country assigned to the city."
   "region", "to-one", ":ref:`Region Object <region_object_v34>`. Returns the region assigned to the city."
   "area", "to-one", ":ref:`Area Object <area_object_v34>`. Returns the area assigned to the city."


.. _cities_v34_get_cities:

==========
Get Cities
==========

Returns a list of cities. Maximum :ref:`page size <api_pagination>` is 1000. Default page size is 1000.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/cities``

.. note:: For all returned data attributes, see :doc:`City Object <city-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]","``string``, ``boolean``","No",":ref:`Filtering <api_filters>`"
   "fields[cities]","``string``","No",":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value","Description"
   
   "country",":ref:`Country Object <country_object_v34>`"
   "region",":ref:`Region Object <region_object_v34>`"
   "area",":ref:`Area Object <area_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank","Allow Array","Filters by:"
   
   "id","``string``","No","Yes","City ``id`` field."
   "name","``string``","Yes","Yes","City ``name`` field. Case insensitive."
   "country.id","``string``","Yes","Yes","A ``country.id`` field."
   "region.id","``string``","Yes","Yes","A ``region.id`` field."
   "is_available","``boolean``","No","No","Indicates if DID numbers in the specified city are currently available for purchase"
   "area.id","``string``","Yes","Yes","A ``area.id`` field."

Sorting
-------

.. csv-table::
   :header: "Value","Sort by"
   
   "name","City ``name`` field."

Examples
========

.. tabs::

   .. tab:: Simple request
   
        .. http:example:: curl 
        
           GET /v3/cities HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]
           
           
           HTTP/2 200 OK
           Content-Type: application/vnd.api+json
           
           {
             "data": [
               {
                 "id": "dccb89ba-f777-4128-b99b-b25e19ccf4ea",
                 "type": "cities",
                 "attributes": {
                   "name": "Aachen"
                 },
                 "relationships": {
                   "country": {
                     "links": {
                       "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/country",
                       "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/country"
                     }
                   },
                   "region": {
                     "links": {
                       "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/region",
                       "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/region"
                     }
                   },
                   "area": {
                     "links": {
                       "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/area",
                       "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/area"
                     }
                   }
                 }
               }
             ]
           }

   .. tab:: Filter by name or country.id
   
      .. http:example:: curl
         
            GET /v3/cities?filter[name]=Springfield&filter[country.id]=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
                  "type": "cities",
                  "attributes": {
                    "name": "Springfield"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
                      }
                    },
                    "region": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
                      }
                    },
                    "area": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
                      }
                    }
                  }
                }
              ]
            }
            

   .. tab:: Include Country Resource
      
   
      .. http:example:: curl
         
            GET /v3/cities?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
                  "type": "cities",
                  "attributes": {
                    "name": "Springfield"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
                      }
                    },
                    "region": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
                      }
                    },
                    "area": {
                      "links": {
                        "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
                        "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
                      }
                    }
                  }
                }
              ],
              "included": [
                {
                  "id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
                  "type": "countries",
                  "attributes": {
                    "name": "United States",
                    "prefix": "1",
                    "iso": "US"
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


========
Get City
========

Returns a city for a given city ID number. Note that a unique identification number is allocated to each city included in the DIDWW coverage.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/cities/``

.. note:: For all returned data attributes, see :doc:`City Object <city-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the City."
   "include","``string``","No",":ref:`Inclusion <api_includes>`"   

Includes
--------

.. csv-table::
   :header: "Value","Description"
   
   "country",":ref:`Country Object <country_object_v34>`"
   "region",":ref:`Region Object <region_object_v34>`"
   "area",":ref:`Area Object <area_object_v34>`"
   
Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "cdf449bc-e3fb-42cc-bf31-b88f91e40de4",
                "type": "cities",
                "attributes": {
                  "name": "London"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/relationships/country",
                      "related": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/country"
                    }
                  },
                  "region": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/relationships/region",
                      "related": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/country"
                    }
                  },
                  "area": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/relationships/area",
                      "related": "https://api.didww.com/v3/cities/cdf449bc-e3fb-42cc-bf31-b88f91e40de4/area"
                    }
                  }
                }
              }
            }
            

   .. tab:: Include Country 
      
   
      .. http:example:: curl
         
            GET /v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "498f2880-591f-436d-aacd-46ad3a7d8be8",
                "type": "cities",
                "attributes": {
                  "name": "London"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/relationships/country",
                      "related": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "2e89d524-55b6-4b6c-a0af-3c1ed0f407f9"
                    }
                  },
                  "region": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/relationships/region",
                      "related": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/region"
                    }
                  },
                  "area": {
                    "links": {
                      "self": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/relationships/area",
                      "related": "https://api.didww.com/v3/cities/498f2880-591f-436d-aacd-46ad3a7d8be8/area"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "2e89d524-55b6-4b6c-a0af-3c1ed0f407f9",
                  "type": "countries",
                  "attributes": {
                    "name": "United Kingdom",
                    "prefix": "44",
                    "iso": "GB"
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"


.. _cities_v34:

 
======
Cities
======
 
Returns a single or a list of cities included in DIDWW inventory. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-city.rst
  get-cities.rst
  city-object.rst



.. _country_object_v34:

==============
Country Object
==============

Country Object attributes

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","Country name (for example United Kingdom)."
   "prefix","``string``","Country prefix (country calling code, for example 44)."
   "iso","``iso``","Country ISO code (for example GB)."

   
   
   
   
   

   



.. _countries_v34_get_countries:

=============
Get Countries
=============

Returns a list of countries. :ref:`Pagination <api_pagination>` is disabled.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/countries``

.. note:: For all returned data attributes, see :doc:`Country Object <country-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "filter[<filter_name>]","``string``, ``boolean``","No",":ref:`Filtering <api_filters>`"
   "fields[countries]","``string``","No",":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank","Allow Array","Filters by:"
   
   "id","``string``","No","Yes","Country ``id`` field."
   "name","``string``","Yes","Yes","Country ``name`` field."
   "prefix","``string``","Yes","Yes","Country ``prefix`` field."
   "iso","``string``","Yes","Yes","Country ``iso`` field."
   "is_available","``boolean``","No","No","Indicates if DID numbers in the specified country are currently available for purchase."
   
Sorting
-------

.. csv-table::
   :header: "Value","Sorts by"
   
   "name","Country ``name`` field"
   "prefix","Country ``prefix`` field"
   "iso","Country ``iso`` field"

Example
=======

.. http:example:: curl

   GET /v3/countries HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
   
   
   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json
   
   {
       "data": [
       {
           "id": "9c56fe0f-eff0-4742-85f6-24868959344a",
           "type": "countries",
           "attributes": {
               "name": "United Kingdom",
               "prefix": "44",
               "iso": "GB"
              }
        },
        {
            "id": "5d3d7640-16d2-4dc0-9aca-408789fbefc6",
            "type": "countries",
            "attributes": {
                "name": "United States",
                "prefix": "1",
                "iso": "US"
            }
        }
        ]
   }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"




===========
Get Country
===========

Returns a country for a given country ID number. Note that a unique identification number is allocated to each country included in the DIDWW coverage.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/countries/``

.. note:: For all returned data attributes, see :doc:`Country Object <country-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number for the country"

Example
=======

.. http:example:: curl 

   GET /v3/countries/e352699c-3764-415b-8946-dd470c1e0ed7 HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API Token]
   
   
   HTTP/2 200 OK
   Content-Type: application/vnd.api+json
   
   {
   	"data":{
   		"id": "e352699c-3764-415b-8946-dd470c1e0ed7",
   		"type": "countries",
   		"attributes": {
   			"name": "United Kingdom",
   			"prefix": "44",
   			"iso": "GB"
   		}
   	}
   }
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"
   





.. _countries_v34:
 
=========
Countries
=========
 
Returns a list of countries included in the current DIDWW inventory, or return the details of a specific country. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-country.rst
  get-countries.rst
  country-object.rst



.. _did_group_type_object_v34:

=====================
DID Group Type Object
=====================

DID Group Type Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","DID Group Type name, such as **Local**, **Mobile** or **Toll-free**."

   

   





==================
Get DID Group Type
==================

Returns a single DID Group Type. A DID Group Type defines a broad category of DID services supported by DIDWW (for example, mobile, local and toll-free).

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_group_types/``

.. note:: For all returned data attributes, see :doc:`Did Group Type Object <did-group-type-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number of a DID Group Type."

Example
=======

.. http:example:: curl 

   GET /v3/did_group_types/4e057223-2a0a-4707-8b35-4e6ef96c9dd9 HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API Token]
   
   
   HTTP/2 200 OK
   Content-Type: application/vnd.api+json
   
   {
       "data": {
           "id": "4e057223-2a0a-4707-8b35-4e6ef96c9dd9",
           "type": "did_group_types",
           "attributes": {
               "name": "Local"
              }
        }
   }
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"

   
   
   
   

   



.. _did_group_types_v34_get_did_group_types:

===================
Get DID Group Types
===================

Returns a list of DID Group Types. A DID Group Type defines a broad category of DID services supported by DIDWW (for example, mobile, local and toll-free).

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_group_types``

.. note:: For all returned data attributes, see :doc:`Did Group Type Object <did-group-type-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[did_group_types]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Group Type ``id`` field."
   "name", "``string``", "Yes", "Yes", "Group Type ``name`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "DID Group Type ``name`` field."

Example
=======

.. http:example:: curl

   GET /v3/did_group_types HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
   
   
   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json
   
   {
       "data": [
       {
           "id": "5827aaef-b3e7-4282-ab9f-e9c17a3e9b93",
           "type": "did_group_types",
           "attributes": {
               "name": "Local"
              }
        },
        {
            "id": "842b298a-9243-4989-a455-4bceac0c7e0e",
            "type": "did_group_types",
            "attributes": {
                "name": "National"
            }
        },
        {
            "id": "96462614-64cf-4898-a434-4e03f8d7f6ab",
            "type": "did_group_types",
            "attributes": {
                "name": "Toll-free"
            }
        },
        {
            "id": "bf31407e-d583-4a1b-b8ee-a5f0d77d865a",
            "type": "did_group_types",
            "attributes": {
                "name": "Mobile"
            }
        },
        {
            "id": "5ad07e30-11f3-4ff9-ba87-fd06575c8f06",
            "type": "did_group_types",
            "attributes": {
                "name": "Shared Cost"
            }
        },
        {
            "id": "e961316f-7f16-4d29-b619-2fd7c421c738",
            "type": "did_group_types",
            "attributes": {
                "name": "Global"
            }
        }
        ],
        "meta": {
            "total_records": 6
            },
            "links": {
                "first": "https://api.didww.comv3/did_group_types?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/did_group_types?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
   }
            

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _did_group_types_v34:
 
==============
DID Group Type
==============
 
Returns a single or a list of the various types of DIDs that are supported in DIDWW inventory. For example: mobile, toll-free, local. Features that are supported: SMS IN, SMS OUT, Voice IN, Voice OUT. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-did-group-type.rst
  get-did-group-types.rst
  did-group-type-object.rst



.. _did_group_object_v34:

================
DID Group Object
================

DID Group Object attributes and meta attributes.

Meta attributes are not available through :ref:`includes <api_includes>`.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "area_name ","``string``","DID Group area name. This will be the name of the city, or a designation applicable to the area code such as **National**."
   "prefix ","``string``","DID Group prefix (city or area calling code)."
   "features","Array of ``strings``","Features available for the DID Group. Supported values are ``voice_in``, ``voice_out``, ``t38``, ``sms_in``, ``p2p``, ``a2p``, ``emergency``, and ``cnam_out``. A DID Group may have multiple features."
   "is_metered ","``boolean``","Defines if the DID Group supports metered services (per-minute billing)."
   "allow_additional_channels ","``boolean``","Defines if channel capacity may be added to this DID Group."
   "service_restrictions","``string`` or ``null``","Service restrictions message for the DID Group, if any restrictions apply."

Meta Attributes
===============

.. csv-table::
   :header: "Name","Type","Description"
   
   "needs_registration ","``boolean``","Defines if end-user registration is required for this DID Group."
   "is_available ","``boolean``","Defines if numbers in this DID Group are currently in stock. "
   "available_dids_enabled","``boolean``","Defines if the DID Group supports numbers selection feature. "
   "total_count","``integer``","Defines current stock available."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`. Returns the country assigned to the DID Group."
   "region", "to-one", ":ref:`Region Object <region_object_v34>`. Returns the region assigned to the DID Group."
   "city", "to-one", ":ref:`City Object <city_object_v34>`. Returns the city assigned to the DID Group."
   "did_group_type", "to-one", ":ref:`DID Group Type Object <did_group_type_object_v34>`. Returns the DID Group Type assigned to the DID Group."
   "stock_keeping_units", "to-many", "A list of :ref:`Stock Keeping Unit Objects <stock_keeping_unit_object_v34>` returned for the DID Group."
   "address_requirement", "to-one", ":ref:`Address Requirement Object <address_requirement_object_v34>`. Returns the address requirement assigned to the DID Group."




=============
Get DID Group
=============

Returns a single DID Group. DID Groups are phone numbers that share a common city or area code.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_groups/``

.. note:: For all returned data attributes, see :doc:`Did Group Object <did-group-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   :widths: 6, 5, 5, 10

   "id", "``string``", "Yes", "Unique ID number of a DID Group."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"
   :widths: 5, 10

   "country", ":ref:`Country Object <country_object_v34>`"
   "region", ":ref:`Region Object <region_object_v34>`"
   "city", ":ref:`City Object <city_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "stock_keeping_units", "A list of :ref:`Stock Keeping Unit Objects <stock_keeping_unit_object_v34>`"
   "address_requirement", ":ref:`Address Requirement Object <address_requirement_object_v34>`"

Example
=======

.. http:example:: curl

    GET /v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API Token]

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "2187c36d-28fb-436f-8861-5a0f5b5a3ee1",
            "type": "did_groups",
            "attributes": {
                "prefix": "241",
                "features": [
                    "voice_in",
                    "cnam_out"
                ],
                "is_metered": false,
                "area_name": "Aachen",
                "allow_additional_channels": true,
                "service_restrictions": "Restriction Message A"
            },
            "relationships": {
                "country": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/country",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/country"
                    }
                },
                "city": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/city",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/city"
                    }
                },
                "did_group_type": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/did_group_type",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/did_group_type"
                    }
                },
                "region": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/region",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/region"
                    }
                },
                "stock_keeping_units": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/stock_keeping_units",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/stock_keeping_units"
                    }
                },
                "address_requirement": {
                    "links": {
                        "self": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/relationships/address_requirement",
                        "related": "https://api.didww.com/v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1/address_requirement"
                    }
                }
            },
            "meta": {
                "available_dids_enabled": false,
                "needs_registration": true,
                "is_available": true,
                "total_count": 7
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   :widths: 5, 5, 10
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



.. _did_groups_v34_get_did_groups:

==============
Get DID Groups
==============

Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_groups``

.. note:: For all returned data attributes, see :doc:`Did Group Object <did-group-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``, ``boolean``, ``Integer``", "No", ":ref:`Filtering <api_filters>`"
   "fields[did_groups]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "region", ":ref:`Region Object <region_object_v34>`"
   "city", ":ref:`City Object <city_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "stock_keeping_units", "A list of :ref:`Stock Keeping Unit Objects <stock_keeping_unit_object_v34>`"
   "address_requirement", ":ref:`Address Requirement Object <address_requirement_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Group ``id`` field."
   "prefix", "``string``", "Yes", "Yes", "The group ``prefix`` field."
   "nanpa_prefix.id", "``string``", "Yes", "Yes", "The nanpa prefix ``id`` field."
   "nanpa_prefix.npanxx", "``string``", "Yes", "Yes", "The nanpa prefix ``npa`` / ``nxx`` fields."
   "area_name", "``string``", "Yes", "Yes", "The ``area_name`` field (for example London). Case insensitive."
   "is_metered", "``boolean``", "No", "No", "The ``is_metered`` field."
   "allow_additional_channels", "``boolean``", "No", "No", "The ``allow_additional_channels`` field."
   "available_dids_enabled", "``boolean``", "No", "No", "The ``available_dids_enabled`` field."
   "features", "``string``", "No", "Yes", "The ``features`` field. Can be one or several of ``voice_in``, ``voice_out``, ``t38``, ``sms_in``, ``p2p``, ``a2p``, ``emergency``, and ``cnam_out``. Example: ``voice_in,emergency``."
   "needs_registration", "``boolean``", "No", "No", "The ``needs_registration`` field."
   "is_available", "``boolean``", "No", "No", "The ``is_available`` field."
   "country.id", "``string``", "Yes", "Yes", "The ``country.id`` field."
   "region.id", "``string``", "Yes", "Yes", "The ``region.id`` field."
   "city.id", "``string``", "Yes", "Yes", "The ``city.id`` field."
   "did_group_type.id", "``string``", "Yes", "Yes", "The ``did_group_type.id`` field."
   "meta.total_count_gteq", "``Integer``", "Yes", "No", "A filter on the list based on the ``meta.total_count_gteq`` field, where ``gteq`` stands for greater-equal."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "country.name", "The ``country.name`` field."
   "did_group_type.name", "The ``did_group_type.name`` field."
   "prefix", "City ``prefix`` field."
   "is_metered", "The ``is_metered`` field."
   "area_name", "The ``area_name`` field."
   "allow_additional_channels", "The ``allow_additional_channels`` field."

Examples
========

.. tabs::

   .. tab:: Simple request

        .. http:example:: curl

            GET /v3/did_groups HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [{
                    "id": "ac160b14-e670-490f-b158-d3ba552c623f",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "241",
                        "features": [
                            "voice_in",
                            "voice_out",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "Aachen",
                        "allow_additional_channels": true,
                        "service_restrictions": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/stock_keeping_units"
                            }
                        },
                        "address_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/address_requirement",
                                "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/address_requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": false,
                        "needs_registration": true,
                        "is_available": true,
                        "total_count": 21
                    }

                }],
                "meta": {
                    "total_records": 1,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?page%5Bnumber%5D=32&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by country.id, did_group_type.id - Include sku_id

      .. http:example:: curl

            GET /v3/did_groups?filter[country.id]=c8647639-fc9c-47b2-acec-7c9e14465c25&filter[did_group_type.id]=0d51924c-e863-44ff-be59-10547c138955&include=stock_keeping_units HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [{
                    "id": "1d5aad75-b853-4125-9a1a-da3fedfc5674",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "7",
                        "features": [
                            "voice_in",
                            "voice_out",
                            "sms_in",
                            "p2p",
                            "a2p",
                            "cnam_out",
                            "emergency"
                        ],
                        "is_metered": false,
                        "area_name": "Mobile",
                        "allow_additional_channels": true,
                        "service_restrictions": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/stock_keeping_units"
                            },
                            "data": [{
                                    "type": "stock_keeping_units",
                                    "id": "cb17c069-098e-4be1-a7eb-eb4529e8c5f5"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "e194165e-eda7-4718-9bbe-c5c583bd189a"
                                }
                            ]
                        },
                        "address_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/relationships/address_requirement",
                                "related": "https://api.didww.com/v3/did_groups/1d5aad75-b853-4125-9a1a-da3fedfc5674/address_requirement"
                            }
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 99
                    }
                }],
                "included": [{
                        "id": "cb17c069-098e-4be1-a7eb-eb4529e8c5f5",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.3",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "e194165e-eda7-4718-9bbe-c5c583bd189a",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.8",
                            "channels_included_count": 2
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bdid_group_type.id%5D=0d51924c-e863-44ff-be59-10547c138955&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bdid_group_type.id%5D=0d51924c-e863-44ff-be59-10547c138955&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by city.id, prefix - Include sku_id

      .. http:example:: curl

            GET /v3/did_groups?filter[city.id]=e696dec7-9c65-4e99-aab7-55a1f98154f0&include=stock_keeping_units&filter[prefix]=20 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [{
                    "id": "fc271bcc-1f9c-4c19-8174-28b7c55a208a",
                    "type": "did_groups",
                    "attributes": {
                        "prefix": "20",
                        "features": [
                            "voice_in",
                            "voice_out",
                            "t38"
                        ],
                        "is_metered": false,
                        "area_name": "London",
                        "allow_additional_channels": true,
                        "service_restrictions": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/country",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/country"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/city",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/city"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/did_group_type"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/region",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/region"
                            }
                        },
                        "stock_keeping_units": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/relationships/stock_keeping_units",
                                "related": "https://api.didww.com/v3/did_groups/fc271bcc-1f9c-4c19-8174-28b7c55a208a/stock_keeping_units"
                            },
                            "data": [{
                                    "type": "stock_keeping_units",
                                    "id": "0ba87a94-7143-48cb-a0f6-d50a6a0c8cfa"
                                },
                                {
                                    "type": "stock_keeping_units",
                                    "id": "1a86de53-3131-491f-9e4b-3392da45d441"
                                }
                            ]
                        }
                    },
                    "meta": {
                        "available_dids_enabled": true,
                        "needs_registration": false,
                        "is_available": true,
                        "total_count": 932
                    }
                }],
                "included": [{
                        "id": "0ba87a94-7143-48cb-a0f6-d50a6a0c8cfa",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.3",
                            "channels_included_count": 0
                        }
                    },
                    {
                        "id": "1a86de53-3131-491f-9e4b-3392da45d441",
                        "type": "stock_keeping_units",
                        "attributes": {
                            "setup_price": "0.0",
                            "monthly_price": "0.8",
                            "channels_included_count": 2
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2021-12-15"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0&filter%5Bprefix%5D=20&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0&filter%5Bprefix%5D=20&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by nanpa_prefix.id

      .. http:example:: curl

            GET /v3/did_groups?filter[nanpa_prefix.id]=1d968dcf-8ee7-40fa-8073-cdbc027bc3b3 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "b59a0277-9d74-4417-b477-192794496928",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "201",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Hackensack",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/stock_keeping_units"
                                }
                            },
                            "address_requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/address_requirement",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/address_requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 3
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.id%5D=1d968dcf-8ee7-40fa-8073-cdbc027bc3b3&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.id%5D=1d968dcf-8ee7-40fa-8073-cdbc027bc3b3&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Filter by nanpa_prefix.npanxx

      .. http:example:: curl

            GET /v3/did_groups?filter[nanpa_prefix.npanxx]=201221 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "b59a0277-9d74-4417-b477-192794496928",
                        "type": "did_groups",
                        "attributes": {
                            "prefix": "201",
                            "features": [
                                "voice_in"
                            ],
                            "is_metered": false,
                            "area_name": "Hackensack",
                            "allow_additional_channels": true
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/country",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/country"
                                }
                            },
                            "city": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/city",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/city"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/did_group_type",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/did_group_type"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/region",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/region"
                                }
                            },
                            "stock_keeping_units": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/stock_keeping_units",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/stock_keeping_units"
                                }
                            },
                            "address_requirement": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/relationships/address_requirement",
                                    "related": "https://api.didww.com/v3/did_groups/b59a0277-9d74-4417-b477-192794496928/address_requirement"
                                }
                            }
                        },
                        "meta": {
                            "available_dids_enabled": true,
                            "needs_registration": false,
                            "is_available": true,
                            "total_count": 3
                        }
                    }
                ],
                "meta": {
                    "total_records": 1,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.npanxx%5D=201221&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_groups?filter%5Bnanpa_prefix.npanxx%5D=201221&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _did_groups_v34:
 
=========
DID Group
=========
 
Returns a single or a list of DID Groups which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code.

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-did-group.rst
  get-did-groups.rst
  did-group-object.rst





======================
Create DID Reservation
======================

Creates a DID Reservation.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/did_reservations``

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "available_dids", ":ref:`to-one <api_relationships>`", "Linkage for included available DIDs."

Example
=======

.. http:example:: curl

   POST /v3/did_reservations HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
      
    {
      "data": {
        "type": "did_reservations",
        "attributes": {
          "description": "DIDWW"
        },
        "relationships": {
          "available_did": {
            "data": {
              "type": "available_dids",
              "id": "8bc37f63-acd7-4e43-a760-1a1caa6e4683"
            }
          }
        }
      }
    }
        
        
   HTTP/1.1 201 Created
   Content-Type: application/vnd.api+json
	
	{
	  "data": {
	    "id": "80167e78-62a1-4720-bf00-229fa7e1935d",
	    "type": "did_reservations",
	    "links": {
	      "self": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d"
	    },
	    "attributes": {
	      "expires_at": "2018-03-15 12:34:56",
	      "created_at": "2018-03-15 12:14:56",
	      "description": "DIDWW"
	    },
	    "relationships": {
	      "available_did": {
	        "links": {
	          "self": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d/relationships/available_did",
	          "related": "https://api.didww.com/v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d/available_did"
	        }
	      }
	    }
	  }
	}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "201","Yes","Created DID Reservation with not reserved Available DID.Returns :ref:`DID Reservation Object <did_reservation_object_v34>`"
   "202","Yes","Updated DID Reservation with already reserved Available DID. Request updates current reservation if exists. Returns :ref:`DID Reservation Object <did_reservation_object_v34>`" 
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>` " 
   "401","No",":ref:`Unauthorized <api_key>`" 




======================
Delete DID Reservation
======================

Deletes a DID Reservation.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/did_reservations/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the DID Reservation."

Example
=======

.. http:example:: curl

   DELETE /v3/did_reservations/1156df17-bcea-4c9a-9c1d-29320e288c03 HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]
   
   
   HTTP/1.1 204 No Content
   Content-Type: application/vnd.api+json
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "204","Yes","DID Reservation deleted.   "
   "401","No",":ref:`Unauthorized <api_key>`" 
  


.. _did_reservation_object_v34:

======================
DID Reservation Object
======================

DID Reservation Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "expires_at","``DateTime``","Expiration date and time."
   "created_at","``DateTime``","Creation date and time."
   "description","``string``","Description"

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "available_did", "to-one", ":ref:`Available DID Object <available_did_object_v34>`. Returns the available DID linked to the reservation."




===================
Get DID Reservation
===================

Returns a single DID Reservation.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_reservations/``

.. note:: For all returned data attributes, see :doc:`Did Reservation Object <did-reservation-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number of the DID Reservation."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "available_did", ":ref:`Available DID Object <available_did_object_v34>`"
   "available_did.did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "available_did.did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                    "type": "did_reservations",
                    "attributes": {
                        "expires_at": "2022-06-27T10:52:16.564Z",
                        "created_at": "2022-06-27T10:42:16.577Z",
                        "description": "DIDWW"
                    },
                    "relationships": {
                        "available_did": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                            }
                        }
                    }
                },
                "meta": {
                    "available_count": 9,
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Request with available_did include
   
      .. http:example:: curl
      
            GET /v3/did_reservations/80167e78-62a1-4720-bf00-229fa7e1935d?include=available_did HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]      

   
           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                    "type": "did_reservations",
                    "attributes": {
                        "expires_at": "2022-06-27T10:52:16.564Z",
                        "created_at": "2022-06-27T10:42:16.577Z",
                        "description": "DIDWW"
                    },
                    "relationships": {
                        "available_did": {
                            "links": {
                                "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                            },
                            "data": {
                                "type": "available_dids",
                                "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573"
                            }
                        }
                    }
                },
                "included": [
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "available_count": 9,
                    "api_version": "2026-04-16"
                }
            }
   
   
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




====================
Get DID Reservations
====================

Returns a list of DID Reservations.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_reservations``

.. note:: For all returned data attributes, see :doc:`Did Reservation Object <did-reservation-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[did_reservations]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "available_did", ":ref:`Available DID Object <available_did_object_v34>`"
   "available_did.did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "available_did.did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "DID Reservation ``id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/did_reservations HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                        "type": "did_reservations",
                        "attributes": {
                            "expires_at": "2022-06-27T10:52:16.564Z",
                            "created_at": "2022-06-27T10:42:16.577Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                                }
                            }
                        }
                    },
                    {
                        "id": "e85a5b1f-850d-498f-8418-ec74cccc9e9a",
                        "type": "did_reservations",
                        "attributes": {
                            "expires_at": "2022-06-27T10:59:58.131Z",
                            "created_at": "2022-06-27T10:49:58.151Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/available_did"
                                }
                            }
                        }
                    },
                    {
                        "id": "4789767d-d59a-485b-9adb-da14b4859f51",
                        "type": "did_reservations",
                        "attributes": {
                            "expires_at": "2022-06-27T11:00:03.332Z",
                            "created_at": "2022-06-27T10:50:03.344Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/available_did"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 3,
                    "available_count": 7,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_reservations?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_reservations?page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

   .. tab:: Request with available_did include
   
      .. http:example:: curl
      
            GET /v3/did_reservations?include=available_did HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]      

   
           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "09c3c91b-f7bf-4db3-b94a-63824b8b1bfa",
                        "type": "did_reservations",
                        "attributes": {
                            "expires_at": "2022-06-27T10:52:16.564Z",
                            "created_at": "2022-06-27T10:42:16.577Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/09c3c91b-f7bf-4db3-b94a-63824b8b1bfa/available_did"
                                },
                                "data": {
                                    "type": "available_dids",
                                    "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573"
                                }
                            }
                        }
                    },
                    {
                        "id": "e85a5b1f-850d-498f-8418-ec74cccc9e9a",
                        "type": "did_reservations",
                        "attributes": {
                            "expires_at": "2022-06-27T10:59:58.131Z",
                            "created_at": "2022-06-27T10:49:58.151Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/e85a5b1f-850d-498f-8418-ec74cccc9e9a/available_did"
                                },
                                "data": {
                                    "type": "available_dids",
                                    "id": "8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f"
                                }
                            }
                        }
                    },
                    {
                        "id": "4789767d-d59a-485b-9adb-da14b4859f51",
                        "type": "did_reservations",
                        "attributes": {
                            "expires_at": "2022-06-27T11:00:03.332Z",
                            "created_at": "2022-06-27T10:50:03.344Z",
                            "description": "DIDWW"
                        },
                        "relationships": {
                            "available_did": {
                                "links": {
                                    "self": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/relationships/available_did",
                                    "related": "https://api.didww.com/v3/did_reservations/4789767d-d59a-485b-9adb-da14b4859f51/available_did"
                                },
                                "data": {
                                    "type": "available_dids",
                                    "id": "7f396769-5203-470c-9595-b158c6bba7c8"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "44ba95af-4b61-49a8-ae41-6235cc8cb573",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727602"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/44ba95af-4b61-49a8-ae41-6235cc8cb573/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f",
                        "type": "available_dids",
                        "attributes": {
                            "number": "526316907325"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/8559343c-ebd1-4fbf-8dc6-d6cd30ca8c3f/nanpa_prefix"
                                }
                            }
                        }
                    },
                    {
                        "id": "7f396769-5203-470c-9595-b158c6bba7c8",
                        "type": "available_dids",
                        "attributes": {
                            "number": "12124727603"
                        },
                        "relationships": {
                            "did_group": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/did_group",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/did_group"
                                }
                            },
                            "nanpa_prefix": {
                                "links": {
                                    "self": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/relationships/nanpa_prefix",
                                    "related": "https://api.didww.com/v3/available_dids/7f396769-5203-470c-9595-b158c6bba7c8/nanpa_prefix"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 3,
                    "available_count": 7,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/did_reservations?include=available_did&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://api.didww.com/v3/did_reservations?include=available_did&page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }
   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _did_reservation_v34:
 
===============
DID Reservation
===============
 
Returns a single or a list of DID reservations for the account. Allows to create or cancel a DID reservation. DID Reservation default values: 10 DID Numbers, 10 Minutes. 

Supported methods: ``GET``, ``POST``, ``DELETE``.
 
.. toctree:: 
  :titlesonly:
  	
  get-did-reservation.rst
  get-did-reservations.rst
  create-did-reservation.rst
  delete-did-reservation.rst
  did-reservation-object.rst





==================
Coverage Resources
==================
 
The following requests allows you to retrieve the contents of DIDWW inventory.
 
.. toctree:: 
  :titlesonly:
  	
  countries/index
  regions/index
  city/index
  nanpa/index
  did-group-type/index
  did-group/index
  available-did/index
  did-reservation/index


.. _regions_v34:
 
=======
Regions
=======
 
Returns a single or a list of regions included in DIDWW inventory. 

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-region.rst
  get-regions.rst
  region-object.rst



==========
Get Region
==========

Returns a single Region.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/regions/``

.. note:: For all returned data attributes, see :doc:`Region Object <region-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier for the Region"
   "include","``string``","No",":ref:`Inclusion <api_includes>` "   		            
   
Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "8ce33ee2-73da-4baa-85a0-cd607d0e9733",
                    "type": "regions",
                    "attributes": {
                        "name": "Alberta",
                        "iso": "CA-AB"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/relationships/country",
                                "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
                            }
                        }
                    }
                }
            }
            

   .. tab:: Include Country
      
   
      .. http:example:: curl
         
            GET /v3/regions/e2f3f115-11f1-43cf-8279-08b29d94403d?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "8ce33ee2-73da-4baa-85a0-cd607d0e9733",
                    "type": "regions",
                    "attributes": {
                        "name": "Alberta",
                        "iso": "CA-AB"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/relationships/country",
                                "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
                            }
                        }
                    }
                },
                "included": [
                {
                    "id": "fa914558-9c64-4e01-967b-3302bd65a97b",
                    "type": "countries",
                    "attributes": {
                        "name": "Canada",
                        "prefix": "1",
                        "iso": "CA"
                    }
                }
                ]
            }
            
            
    

   

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"


.. _regions_v34_get_regions:

===========
Get Regions
===========

Returns a collection of Regions. :ref:`Pagination <api_pagination>` is disabled.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/regions``

.. note:: For all returned data attributes, see :doc:`Region Object <region-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]","``string``","No",":ref:`Filtering <api_filters>`"
   "fields[regions]","``string``","No",":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value","Description"
   
   "country",":ref:`Country Object <country_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank","Allow Array","Filters by:"
   
   "id","``string``","No","Yes","Region ``id`` field."
   "name","``string``","Yes","Yes","Region ``name`` field. Case insensitive."
   "country.id","``string``","Yes","Yes","A ``country.id`` field."
   "iso","``string``","No","Yes","Region ``iso`` field."

Sorting
-------

.. csv-table::
   :header: "Value","Sort by"
   
   "name","Region ``name`` field."

Examples
========

.. tabs::

   .. tab:: Filter by country.id

        .. http:example:: curl 
        
           GET /v3/regions HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]
           
           
           HTTP/2 200 OK
           Content-Type: application/vnd.api+json
           
           {
           	"data":{

           		"id": "e2f3f115-11f1-43cf-8279-08b29d94403d",
           		"type": "regions",
           		"attributes": {
           			"name": "Alberta",
                    "iso": "CA-AB"
           		},
           		"relationships": {
           		    "country": {
           		        "links": {
           		            "self": "https://api.didww.com/v3/regions/e2f3f115-11f1-43cf-8279-08b29d94403d/relationships/country",
           		            "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
           		           }
           		         }
           		      }
           		   }
           		}

   .. tab:: Filter by country.id
   
        .. http:example:: curl
         
            GET /v3/regions?filter[country.id]=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&sort=-name HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "525dab52-0f4b-43cb-b1f6-83ee97a0b5ff",
                    "type": "regions",
                    "attributes": {
                        "name": "Wyoming",
                        "iso": "US-WY"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/525dab52-0f4b-43cb-b1f6-83ee97a0b5ff/relationships/country",
                                "related": "https://api.didww.com/v3/regions/525dab52-0f4b-43cb-b1f6-83ee97a0b5ff/country"
                            }
                        }
                    }
                }
            }
            

   .. tab:: Include Country Resource
      
   
        .. http:example:: curl
         
            GET /v3/regions?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
                "data": {
                    "id": "8ce33ee2-73da-4baa-85a0-cd607d0e9733",
                    "type": "regions",
                    "attributes": {
                        "name": "Alberta",
                        "iso": "CA-AB"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/relationships/country",
                                "related": "https://api.didww.com/v3/regions/8ce33ee2-73da-4baa-85a0-cd607d0e9733/country"
                            }
                        }
                    }
                },
                "included": [
                {
                    "id": "fa914558-9c64-4e01-967b-3302bd65a97b",
                    "type": "countries",
                    "attributes": {
                        "name": "Canada",
                        "prefix": "1",
                        "iso": "CA"
                    }
                }
                ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"


.. _region_object_v34:

==============
Regions Object
==============

Region Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "name","``string``","Region name (for example Quebec)."
   "iso","``iso``","ISO3166-2 code for `USA <https://www.iso.org/obp/ui/#iso:code:3166:US>`_, `Canada <https://www.iso.org/obp/ui/#iso:code:3166:CA>`_, and `United Kingdom <https://www.iso.org/obp/ui/#iso:code:3166:GB>`_, ``null`` for other countries"

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`. Returns the country assigned to the region."

   

   


.. _nanpa_prefixes_v34:

============
NANPA Prefix
============

Returns a single or a list of NANPA Prefix included in DIDWW inventory.

.. note::
    NANPA Prefixes are available only for all countries with country code +1. 

Supported methods: ``GET``

.. toctree::
  :titlesonly:

  get-nanpa-prefix.rst
  get-nanpa-prefixes.rst
  nanpa-prefixes-object.rst


================
Get NANPA Prefix
================

Returns information about single NANPA prefix.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/nanpa_prefixes/``

.. note:: For all returned data attributes, see :doc:`Nanpa Prefixes Object <nanpa-prefixes-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the NANPA Prefix."
   "include","``string``","No",":ref:`Inclusion <api_includes>` "  

Examples
========

.. tabs::

   .. tab:: GET NANPA Prefix

      .. http:example:: curl

            GET /v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                    "type": "nanpa_prefixes",
                    "attributes": {
                        "npa": "201",
                        "nxx": "221"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                            }
                        },
                        "region": {
                            "links": {
                                "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"


.. _nanpa_v34_get_nanpa:

==================
Get NANPA Prefixes
==================

Returns a collection of NANPA Prefixes.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/nanpa_prefixes``

.. note:: For all returned data attributes, see :doc:`Nanpa Prefixes Object <nanpa-prefixes-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
   "fields[nanpa_prefixes]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "region", ":ref:`Region Object <region_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "NANPA Prefixes ``id`` field."
   "npa", "``string``", "Yes", "Yes", "NANPA Prefixes ``npa`` field."
   "nxx", "``string``", "Yes", "Yes", "NANPA Prefixes ``nxx`` field."
   "npanxx", "``string``", "No", "No", "NANPA Prefixes ``npa`` / ``nxx`` fields."
   "country.id", "``string``", "Yes", "Yes", "A ``country.id`` field."
   "region.id", "``string``", "Yes", "Yes", "A ``region.id`` field."
   "did_group.is_available", "``boolean``", "No", "No", "Availability of DIDs in stock for prefix."
   "did_group.features", "``string``", "No", "Yes", "Availability of DIDs in stock with features for prefix. Can be one/several/all of 'voice_in', 'voice_out', 't38', 'sms_in', 'sms_out'."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "npa", "NANPA Prefixes ``npa`` field."
   "nxx", "NANPA Prefixes ``nxx`` field."

Examples
========

.. tabs::

   .. tab:: GET NANPA Prefixes

        .. http:example:: curl

           GET /v3/nanpa_prefixes HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]

           HTTP/2 200 OK
           Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "221"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "c8770990-8a6f-4e11-8b88-420cc9375931",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "234"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "a5958064-96d7-4594-b9bc-a5b9c3bba01f",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "275"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "fcd178f8-3085-42c2-9831-7ca30fc01789",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "301"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "1ff532b2-fec0-4f13-b661-d688ac29dfb0",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "345"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/region"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 4330,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/nanpa_prefixes?page%5Bnumber%5D=1&page%5Bsize%5D=5",
                    "next": "https://api.didww.com/v3/nanpa_prefixes?page%5Bnumber%5D=2&page%5Bsize%5D=5",
                    "last": "https://api.didww.com/v3/nanpa_prefixes?page%5Bnumber%5D=866&page%5Bsize%5D=5"
                }
            }

   .. tab:: Filter by US country.id

        .. http:example:: curl

            GET /v3/nanpa_prefixes?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "221"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "c8770990-8a6f-4e11-8b88-420cc9375931",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "234"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "a5958064-96d7-4594-b9bc-a5b9c3bba01f",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "275"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "fcd178f8-3085-42c2-9831-7ca30fc01789",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "301"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "1ff532b2-fec0-4f13-b661-d688ac29dfb0",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "345"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/country"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/region"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 1609,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&page%5Bnumber%5D=1&page%5Bsize%5D=5",
                    "next": "https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&page%5Bnumber%5D=2&page%5Bsize%5D=5",
                    "last": "https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&page%5Bnumber%5D=322&page%5Bsize%5D=5"
                }
            }

   .. tab:: Include Country Resource

        .. http:example:: curl

            GET /v3/nanpa_prefixes?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "1d968dcf-8ee7-40fa-8073-cdbc027bc3b3",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "221"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1d968dcf-8ee7-40fa-8073-cdbc027bc3b3/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "c8770990-8a6f-4e11-8b88-420cc9375931",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "234"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/c8770990-8a6f-4e11-8b88-420cc9375931/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "a5958064-96d7-4594-b9bc-a5b9c3bba01f",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "275"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/a5958064-96d7-4594-b9bc-a5b9c3bba01f/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "fcd178f8-3085-42c2-9831-7ca30fc01789",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "301"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/fcd178f8-3085-42c2-9831-7ca30fc01789/region"
                                }
                            }
                        }
                    },
                    {
                        "id": "1ff532b2-fec0-4f13-b661-d688ac29dfb0",
                        "type": "nanpa_prefixes",
                        "attributes": {
                            "npa": "201",
                            "nxx": "345"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/country",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/country"
                                },
                                "data": {
                                    "type": "countries",
                                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                                }
                            },
                            "region": {
                                "links": {
                                    "self": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/relationships/region",
                                    "related": "https://api.didww.com/v3/nanpa_prefixes/1ff532b2-fec0-4f13-b661-d688ac29dfb0/region"
                                }
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                        "type": "countries",
                        "attributes": {
                            "name": "United States",
                            "prefix": "1",
                            "iso": "US"
                        },
                        "relationships": {
                            "regions": {
                                "links": {
                                    "self": "https://api.didww.com/v3/countries/1f6fc2bd-f081-4202-9b1a-d9cb88d942b9/relationships/regions",
                                    "related": "https://api.didww.com/v3/countries/1f6fc2bd-f081-4202-9b1a-d9cb88d942b9/regions"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 4330,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://api.didww.com/v3/nanpa_prefixes?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=5",
                    "next": "https://api.didww.com/v3/nanpa_prefixes?include=country&page%5Bnumber%5D=2&page%5Bsize%5D=5",
                    "last": "https://api.didww.com/v3/nanpa_prefixes?include=country&page%5Bnumber%5D=866&page%5Bsize%5D=5"
                }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"



.. _nanpa_prefix_object_v34:

===================
NANPA Prefix Object
===================

NANPA Prefix Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name","Type","Description"
   
   "npa","``string``","Numbering plan area code"
   "nxx","``string``","Central office code "

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`. Returns the country linked to the NANPA prefix."
   "region", "to-one", ":ref:`Region Object <region_object_v34>`. Returns the region linked to the NANPA prefix."


================================
Delete Emergency Calling Service
================================

Cancels an emergency calling service.

.. note:: Cancellation is allowed when current status is ``new``, ``changes_required``, ``active``, and ``pending_update``.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/emergency_calling_services/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the emergency calling service."

Examples
========

.. tabs::

   .. tab:: Example

    .. http:example:: curl

        DELETE /v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 204 No Content
        Content-Type: application/vnd.api+json

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _emergency_calling_service_object_v34:

================================
Emergency Calling Service Object
================================

Emergency calling service object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Friendly name of the emergency calling service."
   "reference", "``string``", "Emergency calling service reference number."
   "status", "``enum``", "Current status of the emergency calling service. Possible values: ``new``, ``in_process``, ``changes_required``, ``active``, ``pending_update``, ``canceled``."
   "activated_at", "``DateTime``", "Date and time when the service was activated. Can be ``null`` before activation."
   "canceled_at", "``DateTime``", "Date and time when the service was canceled. Can be ``null`` when the service has not been canceled."
   "renew_date", "``date``", "Date when the service is due for renewal. Can be ``null``."
   "created_at", "``DateTime``", "Date and time when the service was created."

Meta Attributes
===============

.. csv-table::
   :header: "Name", "Type", "Description"

   "setup_price", "``string``", "One-time setup price for the emergency calling service."
   "monthly_price", "``string``", "Monthly price for the emergency calling service."

Object Relationships
====================

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", "to-one", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "order", "to-one", ":ref:`Order Object <order_object_v34>`"
   "emergency_requirement", "to-one", "Emergency Requirement object."
   "emergency_verification", "to-one", "Emergency Verification object."
   "dids", "to-many", ":ref:`DID Object <did_object_v34>`"


=============================
Get Emergency Calling Service
=============================

Returns a single Emergency Calling Service owned by your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/emergency_calling_services/{id}``

.. note:: For all returned data attributes, see :doc:`Emergency Calling Service Object <emergency-calling-service-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the emergency calling service."
   "include", "``string``", "No", "Related resources to include in the response. See :ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "order", ":ref:`Order Object <order_object_v34>`"
   "emergency_requirement", ":ref:`Emergency Requirement Object <emergency_requirement_object_v34>`"
   "emergency_verification", ":ref:`Emergency Verification Object <emergency_verification_object_v34>`"
   "dids", ":ref:`DID Object <did_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "type": "emergency_calling_services",
                "attributes": {
                    "name": "E911 Service - New York Office",
                    "reference": "SHB-485120",
                    "status": "active",
                    "activated_at": "2026-01-15T10:30:00.000Z",
                    "canceled_at": null,
                    "renew_date": "2026-07-15",
                    "created_at": "2026-01-10T08:00:00.000Z"
                },
                "relationships": {
                    "country": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
                            "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
                        }
                    },
                    "did_group_type": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
                            "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
                        }
                    },
                    "order": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
                            "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
                        }
                    },
                    "emergency_requirement": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
                            "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
                        }
                    },
                    "emergency_verification": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
                            "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
                        }
                    },
                    "dids": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
                            "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
                        }
                    }
                },
                "meta": {
                    "setup_price": "0.0",
                    "monthly_price": "2.5"
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


==============================
Get Emergency Calling Services
==============================

Returns the list of emergency calling services.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/emergency_calling_services``

.. note:: For all returned data attributes, see :doc:`Emergency Calling Service Object <emergency-calling-service-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[emergency_calling_services]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "order", ":ref:`Order Object <order_object_v34>`"
   "emergency_requirement", ":ref:`Emergency Requirement Object <emergency_requirement_object_v34>`"
   "emergency_verification", ":ref:`Emergency Verification Object <emergency_verification_object_v34>`"
   "dids", ":ref:`DID Object <did_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "status", "``string``", "No", "No", "The ``status`` field. Possible values: ``new``, ``in_process``, ``changes_required``, ``active``, ``pending_update``, ``canceled``."
   "country.id", "``string``", "No", "No", "The ``country.id`` field."
   "did_group_type.id", "``string``", "No", "No", "The ``did_group_type.id`` field."
   "address.id", "``string``", "No", "No", "The ``address.id`` field of the last verification linked to the emergency calling service."
   "identity.id", "``string``", "No", "No", "The ``identity.id`` field of the address used in the last verification linked to the emergency calling service."
   "name", "``string``", "No", "No", "The ``name`` field."
   "reference", "``string``", "No", "No", "The ``reference`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "The ``name`` field."
   "status", "The ``status`` field. Possible values: ``new``, ``in_process``, ``changes_required``, ``active``, ``pending_update``, ``canceled``."
   "country.name", "The related country name."
   "renew_date", "The ``renew_date`` field. Canceled services are excluded from this sort."
   "created_at", "The ``created_at`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/emergency_calling_services HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "type": "emergency_calling_services",
                    "attributes": {
                        "name": "E911 Service - New York Office",
                        "reference": "SHB-485120",
                        "status": "active",
                        "activated_at": "2026-01-15T10:30:00.000Z",
                        "canceled_at": null,
                        "renew_date": "2026-07-15",
                        "created_at": "2026-01-10T08:00:00.000Z"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
                            }
                        },
                        "order": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
                            }
                        },
                        "emergency_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
                            }
                        },
                        "emergency_verification": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_calling_services?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_calling_services?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter by status

    .. http:example:: curl

        GET /v3/emergency_calling_services?filter[status]=active HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "type": "emergency_calling_services",
                    "attributes": {
                        "name": "E911 Service - New York Office",
                        "reference": "SHB-485120",
                        "status": "active",
                        "activated_at": "2026-01-15T10:30:00.000Z",
                        "canceled_at": null,
                        "renew_date": "2026-07-15",
                        "created_at": "2026-01-10T08:00:00.000Z"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
                            }
                        },
                        "order": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
                            }
                        },
                        "emergency_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
                            }
                        },
                        "emergency_verification": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_calling_services?filter%5Bstatus%5D=active&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_calling_services?filter%5Bstatus%5D=active&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter by country.id

    .. http:example:: curl

        GET /v3/emergency_calling_services?filter[country.id]=72f22218-ab1f-4933-a74d-a6467f3f6cb0 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "type": "emergency_calling_services",
                    "attributes": {
                        "name": "E911 Service - New York Office",
                        "reference": "SHB-485120",
                        "status": "active",
                        "activated_at": "2026-01-15T10:30:00.000Z",
                        "canceled_at": null,
                        "renew_date": "2026-07-15",
                        "created_at": "2026-01-10T08:00:00.000Z"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
                            }
                        },
                        "order": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
                            }
                        },
                        "emergency_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
                            }
                        },
                        "emergency_verification": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_calling_services?filter%5Bcountry.id%5D=72f22218-ab1f-4933-a74d-a6467f3f6cb0&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_calling_services?filter%5Bcountry.id%5D=72f22218-ab1f-4933-a74d-a6467f3f6cb0&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Include country while filtered by status

    .. http:example:: curl

        GET /v3/emergency_calling_services?filter[status]=active&include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "type": "emergency_calling_services",
                    "attributes": {
                        "name": "E911 Service - New York Office",
                        "reference": "SHB-485120",
                        "status": "active",
                        "activated_at": "2026-01-15T10:30:00.000Z",
                        "canceled_at": null,
                        "renew_date": "2026-07-15",
                        "created_at": "2026-01-10T08:00:00.000Z"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
                            },
                            "data": {
                                "type": "countries",
                                "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
                            }
                        },
                        "order": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
                            }
                        },
                        "emergency_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
                            }
                        },
                        "emergency_verification": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "included": [
                {
                    "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0",
                    "type": "countries",
                    "attributes": {
                        "name": "United States",
                        "prefix": "1",
                        "iso": "US"
                    },
                    "relationships": {
                        "regions": {
                            "links": {
                                "self": "https://api.didww.com/v3/countries/72f22218-ab1f-4933-a74d-a6467f3f6cb0/relationships/regions",
                                "related": "https://api.didww.com/v3/countries/72f22218-ab1f-4933-a74d-a6467f3f6cb0/regions"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_calling_services?filter%5Bstatus%5D=active&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_calling_services?filter%5Bstatus%5D=active&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

.. _emergency_calling_services_v34:

==========================
Emergency Calling Services
==========================

Returns a single or a list of Calling Services in the account.

Emergency Calling Services are not created directly — they are created automatically when an Emergency Verification is submitted in New Calling Service mode.

Supported methods: ``GET``, ``DELETE``.

.. note::

   Removing a DID from an existing Emergency Calling Service is handled
   through the DID resource, not through emergency verification creation.
   For more information, see :doc:`Update DID
   <../../inventory-resources/did/update-did>`.

.. toctree::
   :maxdepth: 1

   get-emergency-calling-service.rst
   get-emergency-calling-services.rst
   delete-emergency-calling-service.rst
   emergency-calling-service-object.rst


.. _emergency_requirement_object_v34:

============================
Emergency Requirement Object
============================

Emergency requirement object attributes. The JSON:API resource type is
``emergency_requirements``.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "identity_type", "``string``", "Identity type required for emergency registration. Possible values: ``personal``, ``business``, ``any``."
   "address_area_level", "``string``", "Required location proof level for Address. Possible values: ``country``, ``area``, ``city``."
   "personal_area_level", "``string``", "Required location proof level for Personal Identity. Possible values: ``world_wide``, ``country``. Can be ``null``."
   "business_area_level", "``string``", "Required location proof level for Business Identity. Possible values: ``world_wide``, ``country``. Can be ``null``."
   "address_mandatory_fields", "``array[string]``", "Mandatory fields for Address."
   "personal_mandatory_fields", "``array[string]``", "Mandatory fields for Personal Identity."
   "business_mandatory_fields", "``array[string]``", "Mandatory fields for Business Identity."
   "estimate_setup_time", "``string``", "Estimated time to activate the emergency calling service."
   "requirement_restriction_message", "``string``", "Additional restriction message for a specific country or DID group type. Can be ``null``."

Meta Attributes
===============

.. csv-table::
   :header: "Name", "Type", "Description"

   "setup_price", "``string``", "One-time setup price for the emergency calling service, as a decimal string. Always ``0.0`` when priced: activation is not charged on this API. Can be ``null`` when no matching emergency plan rate exists."
   "monthly_price", "``string``", "Monthly price from the customer's matching emergency plan rate, as a decimal string. Can be ``null`` when no matching rate exists."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", "to-one", ":ref:`DID Group Type Object <did_group_type_object_v34>`"


.. |br| raw:: html

   <br />

.. _emergency_requirement_validations_v34:

=================================
Emergency Requirement Validations
=================================

Checks if the :ref:`Address <addresses_object_v34>` and/or
:ref:`Identity <identity_object_v34>` created is valid against the
:ref:`Emergency Requirement <emergency_requirement_object_v34>`. The JSON:API resource
type is ``emergency_requirement_validations``.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/emergency_requirement_validations``

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "emergency_requirement", ":ref:`Emergency Requirement <emergency_requirement_object_v34>`", "Specifies the emergency requirement ID."
   "identity", ":ref:`Identity <identity_object_v34>`", "Specifies the identity ID."
   "address", ":ref:`Address <addresses_object_v34>`", "Specifies the address ID."

Examples
========

.. tabs::

   .. tab:: Validation Request Success

     .. http:example:: curl

        POST /v3/emergency_requirement_validations HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "emergency_requirement_validations",
            "relationships": {
              "emergency_requirement": {
                "data": {
                  "id": "ID_of_Emergency_Requirement",
                  "type": "emergency_requirements"
                }
              },
              "address": {
                "data": {
                  "id": "ID_of_Address",
                  "type": "addresses"
                }
              },
              "identity": {
                "data": {
                  "id": "ID_of_Identity",
                  "type": "identities"
                }
              }
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                "type": "emergency_requirement_validations"
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Validation Request Error

     .. http:example:: curl

        POST /v3/emergency_requirement_validations HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "emergency_requirement_validations",
            "relationships": {
              "emergency_requirement": {
                "data": {
                  "id": "ID_of_Emergency_Requirement",
                  "type": "emergency_requirements"
                }
              },
              "address": {
                "data": {
                  "id": "ID_of_Address",
                  "type": "addresses"
                }
              },
              "identity": {
                "data": {
                  "id": "ID_of_Identity",
                  "type": "identities"
                }
              }
            }
          }
        }

        HTTP/1.1 422 Unprocessable Entity
        Content-Type: application/vnd.api+json

        {
            "errors": [
                {
                    "title": "Address in United States required",
                    "detail": "Address in United States required",
                    "code": "100",
                    "source": {
                        "pointer": "/data"
                    },
                    "status": "422"
                },
                {
                    "title": "Birth Date is required for Personal Identity",
                    "detail": "Birth Date is required for Personal Identity",
                    "code": "100",
                    "source": {
                        "pointer": "/data"
                    },
                    "status": "422"
                }
            ]
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"


=========================
Get Emergency Requirement
=========================

Returns the emergency requirements per single country.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/emergency_requirements/{id}``

.. note:: For all returned data attributes, see :doc:`Emergency Requirement Object <emergency-requirement-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Emergency Requirement."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"

Examples
========

.. http:example:: curl

    GET /v3/emergency_requirements/3e353579-8056-4b9b-bf83-ea57885bee32 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "3e353579-8056-4b9b-bf83-ea57885bee32",
            "type": "emergency_requirements",
            "attributes": {
                "identity_type": "personal",
                "address_area_level": "city",
                "personal_area_level": "country",
                "business_area_level": null,
                "address_mandatory_fields": ["State/Province/Region"],
                "personal_mandatory_fields": ["Birth Date", "Contact email"],
                "business_mandatory_fields": [],
                "estimate_setup_time": "1-2 business days",
                "requirement_restriction_message": null
            },
            "relationships": {
                "country": {
                    "links": {
                        "self": "https://api.didww.com/v3/emergency_requirements/3e353579-8056-4b9b-bf83-ea57885bee32/relationships/country",
                        "related": "https://api.didww.com/v3/emergency_requirements/3e353579-8056-4b9b-bf83-ea57885bee32/country"
                    }
                },
                "did_group_type": {
                    "links": {
                        "self": "https://api.didww.com/v3/emergency_requirements/3e353579-8056-4b9b-bf83-ea57885bee32/relationships/did_group_type",
                        "related": "https://api.didww.com/v3/emergency_requirements/3e353579-8056-4b9b-bf83-ea57885bee32/did_group_type"
                    }
                }
            },
            "meta": {
                "setup_price": "0.0",
                "monthly_price": "0.16"
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"
   "403", "No", "Forbidden. Example detail: ``Emergency plan is not assigned to the Customer``."
   "404", "No", ":ref:`Not Found <api_not_found>`"


==========================
Get Emergency Requirements
==========================

Returns the list of emergency requirements.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/emergency_requirements``

.. note:: For all returned data attributes, see :doc:`Emergency Requirement Object <emergency-requirement-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[emergency_requirements]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "The Emergency Requirement ``id`` field."
   "country.id", "``string``", "No", "No", "The ``country.id`` field."
   "did_group_type.id", "``string``", "No", "No", "The ``did_group_type.id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/emergency_requirements HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "3f3be6a6-a513-4509-bd9b-945e599e16f5",
                    "type": "emergency_requirements",
                    "attributes": {
                        "identity_type": "Any",
                        "address_area_level": "country",
                        "personal_area_level": "world_wide",
                        "business_area_level": "world_wide",
                        "address_mandatory_fields": [],
                        "personal_mandatory_fields": [],
                        "business_mandatory_fields": [],
                        "estimate_setup_time": "1-2 business days",
                        "requirement_restriction_message": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/did_group_type"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                },
                {
                    "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                    "type": "emergency_requirements",
                    "attributes": {
                        "identity_type": "personal",
                        "address_area_level": "city",
                        "personal_area_level": "country",
                        "business_area_level": null,
                        "address_mandatory_fields": ["State/Province/Region"],
                        "personal_mandatory_fields": ["Birth Date", "Contact email"],
                        "business_mandatory_fields": [],
                        "estimate_setup_time": "1-2 business days",
                        "requirement_restriction_message": "USA Local DID emergency registration requirements:\r\n\r\n1. Name, last name and contact phone number.\r\n2. Current address must be from the same city as the DID ordered (street, building number, postal code, city).\r\n\r\nEmergency calling will not be activated until full registration details are provided and approved."
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": null,
                        "monthly_price": null
                    }
                }
            ],
            "meta": {
                "total_records": 2,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_requirements?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_requirements?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter by country.id

    .. http:example:: curl

        GET /v3/emergency_requirements?filter[country.id]=72f22218-ab1f-4933-a74d-a6467f3f6cb0 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                    "type": "emergency_requirements",
                    "attributes": {
                        "identity_type": "personal",
                        "address_area_level": "city",
                        "personal_area_level": "country",
                        "business_area_level": null,
                        "address_mandatory_fields": ["State/Province/Region"],
                        "personal_mandatory_fields": ["Birth Date", "Contact email"],
                        "business_mandatory_fields": [],
                        "estimate_setup_time": "1-2 business days",
                        "requirement_restriction_message": "USA Local DID emergency registration requirements:\r\n\r\n1. Name, last name and contact phone number.\r\n2. Current address must be from the same city as the DID ordered (street, building number, postal code, city).\r\n\r\nEmergency calling will not be activated until full registration details are provided and approved."
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_requirements?filter%5Bcountry.id%5D=72f22218-ab1f-4933-a74d-a6467f3f6cb0&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_requirements?filter%5Bcountry.id%5D=72f22218-ab1f-4933-a74d-a6467f3f6cb0&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter by did_group_type.id

    .. http:example:: curl

        GET /v3/emergency_requirements?filter[did_group_type.id]=8a9bcd12-3456-789a-bcde-f01234567890 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                    "type": "emergency_requirements",
                    "attributes": {
                        "identity_type": "personal",
                        "address_area_level": "city",
                        "personal_area_level": "country",
                        "business_area_level": null,
                        "address_mandatory_fields": ["State/Province/Region"],
                        "personal_mandatory_fields": ["Birth Date", "Contact email"],
                        "business_mandatory_fields": [],
                        "estimate_setup_time": "1-2 business days",
                        "requirement_restriction_message": "USA Local DID emergency registration requirements:\r\n\r\n1. Name, last name and contact phone number.\r\n2. Current address must be from the same city as the DID ordered (street, building number, postal code, city).\r\n\r\nEmergency calling will not be activated until full registration details are provided and approved."
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_requirements?filter%5Bdid_group_type.id%5D=8a9bcd12-3456-789a-bcde-f01234567890&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_requirements?filter%5Bdid_group_type.id%5D=8a9bcd12-3456-789a-bcde-f01234567890&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Include country while filtered by did_group_type.id

    .. http:example:: curl

        GET /v3/emergency_requirements?filter[did_group_type.id]=8a9bcd12-3456-789a-bcde-f01234567890&include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                    "type": "emergency_requirements",
                    "attributes": {
                        "identity_type": "personal",
                        "address_area_level": "city",
                        "personal_area_level": "country",
                        "business_area_level": null,
                        "address_mandatory_fields": ["State/Province/Region"],
                        "personal_mandatory_fields": ["Birth Date", "Contact email"],
                        "business_mandatory_fields": [],
                        "estimate_setup_time": "1-2 business days",
                        "requirement_restriction_message": "USA Local DID emergency registration requirements:\r\n\r\n1. Name, last name and contact phone number.\r\n2. Current address must be from the same city as the DID ordered (street, building number, postal code, city).\r\n\r\nEmergency calling will not be activated until full registration details are provided and approved."
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                            },
                            "data": {
                                "type": "countries",
                                "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                },
                {
                    "id": "a3b4c5d6-7890-4abc-def0-123456789012",
                    "type": "emergency_requirements",
                    "attributes": {
                        "identity_type": "Any",
                        "address_area_level": "country",
                        "personal_area_level": "world_wide",
                        "business_area_level": "world_wide",
                        "address_mandatory_fields": [],
                        "personal_mandatory_fields": [],
                        "business_mandatory_fields": [],
                        "estimate_setup_time": "1-2 business days",
                        "requirement_restriction_message": null
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/a3b4c5d6-7890-4abc-def0-123456789012/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_requirements/a3b4c5d6-7890-4abc-def0-123456789012/country"
                            },
                            "data": {
                                "type": "countries",
                                "id": "b1c2d3e4-f567-4890-abcd-ef0123456789"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_requirements/a3b4c5d6-7890-4abc-def0-123456789012/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_requirements/a3b4c5d6-7890-4abc-def0-123456789012/did_group_type"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "0.2"
                    }
                }
            ],
            "included": [
                {
                    "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0",
                    "type": "countries",
                    "attributes": {
                        "name": "United States",
                        "prefix": "1",
                        "iso": "US"
                    },
                    "relationships": {
                        "regions": {
                            "links": {
                                "self": "https://api.didww.com/v3/countries/72f22218-ab1f-4933-a74d-a6467f3f6cb0/relationships/regions",
                                "related": "https://api.didww.com/v3/countries/72f22218-ab1f-4933-a74d-a6467f3f6cb0/regions"
                            }
                        }
                    }
                },
                {
                    "id": "b1c2d3e4-f567-4890-abcd-ef0123456789",
                    "type": "countries",
                    "attributes": {
                        "name": "Canada",
                        "prefix": "1",
                        "iso": "CA"
                    },
                    "relationships": {
                        "regions": {
                            "links": {
                                "self": "https://api.didww.com/v3/countries/b1c2d3e4-f567-4890-abcd-ef0123456789/relationships/regions",
                                "related": "https://api.didww.com/v3/countries/b1c2d3e4-f567-4890-abcd-ef0123456789/regions"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 2,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_requirements?filter%5Bdid_group_type.id%5D=8a9bcd12-3456-789a-bcde-f01234567890&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_requirements?filter%5Bdid_group_type.id%5D=8a9bcd12-3456-789a-bcde-f01234567890&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "400", "No", "Invalid resource. Example detail: ``emergency_requirements are not supported in 2022-05-10 DIDWW API version``."
   "401", "No", ":ref:`Unauthorized <api_key>`"
   "403", "No", "Forbidden. Example detail: ``Emergency plan is not assigned to the Customer``."


.. |br| raw:: html

   <br />

.. _emergency_requirements_v34:

======================
Emergency Requirements
======================

Returns the list of the emergency requirements per country.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1

  get-emergency-requirement.rst
  get-emergency-requirements.rst
  emergency-requirement-object.rst
  emergency-requirement-validations.rst


=============================
Create Emergency Verification
=============================

Creates a new emergency verification, either for a new Emergency Calling Service or for
resubmitting a rejected or updating an existing one.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/emergency_verifications``

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "callback_url", "``string``", "No", "The HTTP or HTTPS endpoint to where events related to the verification will be delivered."
   "callback_method", "``string``", "No", "The callback method used for verification events. Supported methods: ``post``, ``get``. Required when ``callback_url`` is provided."
   "external_reference_id", "``string``", "No", "Optional identifier for the emergency verification in the customer's external system. Maximum length is 100 characters."

See :ref:`Callback details <callbacks_details_v34>` for information about
``callback_url`` and ``callback_method``.

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "address", ":ref:`Addresses <addresses_object_v34>`", "Specifies the emergency address ID."
   "dids", ":ref:`DID <did_object_v34>`", "Specifies the DID IDs for a new Emergency Calling Service. At least one DID is required when ``emergency_calling_service`` is not provided."
   "emergency_calling_service", ":ref:`Emergency Calling Service <emergency_calling_service_object_v34>`", "Specifies the existing Emergency Calling Service ID when resubmitting or updating the address of an existing service."

.. note::

   - New Calling Service mode uses ``address`` and ``dids`` relationships and does not send ``emergency_calling_service``.
   - Existing Calling Service mode uses ``emergency_calling_service`` and ``address`` relationships and does not send ``dids``.
   - Address updates are allowed only when the Emergency Calling Service status is ``new``, ``changes_required``, or ``active``.
   - Requests return ``422`` when the Emergency Calling Service is in ``pending_update``, ``in_process``, or ``canceled`` status.

Examples
========

.. tabs::

   .. tab:: New Calling Service

    .. http:example:: curl

        POST /v3/emergency_verifications HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
            "data": {
                "type": "emergency_verifications",
                "attributes": {
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "post"
                },
                "relationships": {
                    "address": {
                        "data": {
                            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                            "type": "addresses"
                        }
                    },
                    "dids": {
                        "data": [
                            {
                                "id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c",
                                "type": "dids"
                            },
                            {
                                "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890",
                                "type": "dids"
                            }
                        ]
                    }
                }
            }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
                "type": "emergency_verifications",
                "attributes": {
                    "reference": "SHB-485120",
                    "status": "pending",
                    "reject_reasons": [],
                    "reject_comment": null,
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "post",
                    "created_at": "2026-03-20T12:20:04.584Z",
                    "external_reference_id": "test"
                },
                "relationships": {
                    "address": {
                        "data": {
                            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                            "type": "addresses"
                        }
                    },
                    "emergency_calling_service": {
                        "data": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "type": "emergency_calling_services"
                        }
                    },
                    "dids": {
                        "data": [
                            {
                                "id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c",
                                "type": "dids"
                            },
                            {
                                "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890",
                                "type": "dids"
                            }
                        ]
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Existing Calling Service

    .. http:example:: curl

        POST /v3/emergency_verifications HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
            "data": {
                "type": "emergency_verifications",
                "attributes": {
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "post"
                },
                "relationships": {
                    "address": {
                        "data": {
                            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                            "type": "addresses"
                        }
                    },
                    "emergency_calling_service": {
                        "data": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "type": "emergency_calling_services"
                        }
                    }
                }
            }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
                "type": "emergency_verifications",
                "attributes": {
                    "reference": "SHB-998877",
                    "status": "pending",
                    "reject_reasons": [],
                    "reject_comment": null,
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "post",
                    "created_at": "2026-03-23T09:15:00.000Z",
                    "external_reference_id": "test"
                },
                "relationships": {
                    "address": {
                        "data": {
                            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                            "type": "addresses"
                        }
                    },
                    "emergency_calling_service": {
                        "data": {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                            "type": "emergency_calling_services"
                        }
                    },
                    "dids": {
                        "data": []
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Verification Error

    .. http:example:: curl

        POST /v3/emergency_verifications HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
            "data": {
                "type": "emergency_verifications",
                "attributes": {
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "post"
                },
                "relationships": {
                    "address": {
                        "data": {
                            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                            "type": "addresses"
                        }
                    },
                    "dids": {
                        "data": []
                    }
                }
            }
        }

        HTTP/1.1 422 Unprocessable Entity
        Content-Type: application/vnd.api+json

        {
            "errors": [
                {
                    "title": "can't be blank",
                    "detail": "dids - can't be blank",
                    "code": "100",
                    "source": {
                        "pointer": "/data/relationships/dids"
                    },
                    "status": "422"
                }
            ]
        }

   .. tab:: DID Validation Error

    .. http:example:: curl

        POST /v3/emergency_verifications HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
            "data": {
                "type": "emergency_verifications",
                "attributes": {
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "post"
                },
                "relationships": {
                    "address": {
                        "data": {
                            "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                            "type": "addresses"
                        }
                    },
                    "dids": {
                        "data": [
                            {
                                "id": "2ae7bae7-bf6d-4149-a45c-2d28d636a8d6",
                                "type": "dids"
                            }
                        ]
                    }
                }
            }
        }

        HTTP/1.1 422 Unprocessable Entity
        Content-Type: application/vnd.api+json

        {
            "errors": [
                {
                    "title": "Emergency Rate not found",
                    "detail": "Emergency Rate not found",
                    "code": "100",
                    "source": {
                        "pointer": "/data"
                    },
                    "status": "422"
                },
                {
                    "title": "should have the same Did Group Type",
                    "detail": "dids - should have the same Did Group Type",
                    "code": "100",
                    "source": {
                        "pointer": "/data/relationships/dids"
                    },
                    "status": "422"
                },
                {
                    "title": "should be linked with City ID",
                    "detail": "dids - should be linked with City ID",
                    "code": "100",
                    "source": {
                        "pointer": "/data/relationships/dids"
                    },
                    "status": "422"
                },
                {
                    "title": "does not support Emergency feature",
                    "detail": "dids/2ae7bae7-bf6d-4149-a45c-2d28d636a8d6 - does not support Emergency feature",
                    "code": "100",
                    "source": {
                        "pointer": "/data/relationships/dids/2ae7bae7-bf6d-4149-a45c-2d28d636a8d6"
                    },
                    "status": "422"
                }
            ]
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "400", "No", "Invalid resource for earlier API versions."
   "401", "No", ":ref:`Unauthorized <api_key>`"
   "403", "No", "Forbidden. Example detail: ``Emergency plan is not assigned to the customer``."


.. _emergency_verification_object_v34:

=============================
Emergency Verification Object
=============================

Emergency verification object attributes. The JSON:API resource type is
``emergency_verifications``.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "reference", "``string``", "Emergency verification reference number."
   "status", "``string``", "The status of the emergency verification. Possible values: ``pending``, ``approved``, ``rejected``."
   "reject_reasons", "``array[string]``", "The reasons for verification rejection. Empty array when not rejected."
   "reject_comment", "``string``", "Additional comment provided upon rejection. Returns ``null`` when not rejected."
   "callback_url", "``string``", "The HTTP or HTTPS endpoint to where events related to the verification will be delivered."
   "callback_method", "``string``", "The callback method used for verification events. Supported methods: ``post``, ``get``."
   "created_at", "``DateTime``", "Date and time when the verification was created."
   "external_reference_id", "``string``", "Optional identifier for the emergency verification in the customer's external system. Maximum length is 100 characters."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "address", "to-one", ":ref:`Addresses Object <addresses_object_v34>`"
   "emergency_calling_service", "to-one", ":ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`"
   "dids", "to-many", ":ref:`DID Object <did_object_v34>`"


==========================
Get Emergency Verification
==========================

Returns a single emergency verification status and reason if the verification was rejected.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/emergency_verifications/{id}``

.. note:: For all returned data attributes, see :doc:`Emergency Verification Object <emergency-verification-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Emergency Verification."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "address", ":ref:`Addresses Object <addresses_object_v34>`"
   "emergency_calling_service", ":ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`"
   "dids", ":ref:`DID Object <did_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Approved Verification

    .. http:example:: curl

        GET /v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
                "type": "emergency_verifications",
                "attributes": {
                    "reference": "SHB-991234",
                    "status": "approved",
                    "reject_reasons": [],
                    "reject_comment": null,
                    "callback_url": null,
                    "callback_method": null,
                    "created_at": "2026-01-10T09:00:00.000Z",
                    "external_reference_id": null
                },
                "relationships": {
                    "address": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/address",
                            "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/address"
                        }
                    },
                    "emergency_calling_service": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/emergency_calling_service",
                            "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/emergency_calling_service"
                        }
                    },
                    "dids": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/dids",
                            "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/dids"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Rejected Verification

    .. http:example:: curl

        GET /v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "40c315d2-255c-410f-9af7-6b288c3f8ba4",
                "type": "emergency_verifications",
                "attributes": {
                    "reference": "EGE-764403",
                    "status": "rejected",
                    "reject_reasons": [
                        "The provided address does not match the DID area",
                        "Identity document has expired"
                    ],
                    "reject_comment": "Additional info from operator",
                    "callback_url": "https://example.com/callbacks/emergency",
                    "callback_method": "get",
                    "created_at": "2026-02-15T14:00:00.000Z",
                    "external_reference_id": null
                },
                "relationships": {
                    "address": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/address",
                            "related": "https://api.didww.com/v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/address"
                        }
                    },
                    "emergency_calling_service": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/emergency_calling_service",
                            "related": "https://api.didww.com/v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/emergency_calling_service"
                        }
                    },
                    "dids": {
                        "links": {
                            "self": "https://api.didww.com/v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/dids",
                            "related": "https://api.didww.com/v3/emergency_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/dids"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"
   "403", "No", "Forbidden. Example detail: ``Emergency plan is not assigned to the customer``."
   "404", "No", ":ref:`Not Found <api_not_found>`"


===========================
Get Emergency Verifications
===========================

Returns the emergency verifications status and reason if the verification was rejected.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/emergency_verifications``

.. note:: For all returned data attributes, see :doc:`Emergency Verification Object <emergency-verification-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[emergency_verifications]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "address", ":ref:`Addresses Object <addresses_object_v34>`"
   "emergency_calling_service", ":ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`"
   "dids", ":ref:`DID Object <did_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "status", "``string``", "No", "No", "The ``status`` field. Possible values: ``pending``, ``approved``, ``rejected``."
   "emergency_calling_service.id", "``string``", "No", "No", "The ``emergency_calling_service.id`` field."
   "external_reference_id", "``string``", "Yes", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "created_at", "The ``created_at`` field."
   "external_reference_id", "The ``external_reference_id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/emergency_verifications HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
                    "type": "emergency_verifications",
                    "attributes": {
                        "reference": "SHB-485120",
                        "status": "pending",
                        "reject_reasons": [],
                        "reject_comment": null,
                        "callback_url": "https://example.com/callbacks/emergency",
                        "callback_method": "post",
                        "created_at": "2026-03-20T12:20:04.584Z",
                        "external_reference_id": null
                    },
                    "relationships": {
                        "address": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address"
                            }
                        },
                        "emergency_calling_service": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/emergency_calling_service",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/emergency_calling_service"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids"
                            }
                        }
                    }
                },
                {
                    "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
                    "type": "emergency_verifications",
                    "attributes": {
                        "reference": "SHB-991234",
                        "status": "approved",
                        "reject_reasons": [],
                        "reject_comment": null,
                        "callback_url": null,
                        "callback_method": null,
                        "created_at": "2026-01-10T09:00:00.000Z",
                        "external_reference_id": null
                    },
                    "relationships": {
                        "address": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/address",
                                "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/address"
                            }
                        },
                        "emergency_calling_service": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/emergency_calling_service",
                                "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/emergency_calling_service"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/dids"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 2,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_verifications?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_verifications?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter by status

    .. http:example:: curl

        GET /v3/emergency_verifications?filter[status]=pending HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
                    "type": "emergency_verifications",
                    "attributes": {
                        "reference": "SHB-485120",
                        "status": "pending",
                        "reject_reasons": [],
                        "reject_comment": null,
                        "callback_url": "https://example.com/callbacks/emergency",
                        "callback_method": "post",
                        "created_at": "2026-03-20T12:20:04.584Z",
                        "external_reference_id": null
                    },
                    "relationships": {
                        "address": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address"
                            }
                        },
                        "emergency_calling_service": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/emergency_calling_service",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/emergency_calling_service"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_verifications?filter%5Bstatus%5D=pending&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_verifications?filter%5Bstatus%5D=pending&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Include emergency_calling_service

    .. http:example:: curl

        GET /v3/emergency_verifications?filter[status]=pending&include=emergency_calling_service HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
                    "type": "emergency_verifications",
                    "attributes": {
                        "reference": "SHB-485120",
                        "status": "pending",
                        "reject_reasons": [],
                        "reject_comment": null,
                        "callback_url": "https://example.com/callbacks/emergency",
                        "callback_method": "post",
                        "created_at": "2026-03-20T12:20:04.584Z",
                        "external_reference_id": null
                    },
                    "relationships": {
                        "address": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address"
                            }
                        },
                        "emergency_calling_service": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/emergency_calling_service",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/emergency_calling_service"
                            },
                            "data": {
                                "type": "emergency_calling_services",
                                "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids"
                            }
                        }
                    }
                }
            ],
            "included": [
                {
                    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "type": "emergency_calling_services",
                    "attributes": {
                        "name": "E911 Service - New York Office",
                        "reference": "SHB-485120",
                        "status": "in_process",
                        "activated_at": null,
                        "canceled_at": null,
                        "renew_date": null,
                        "created_at": "2026-03-20T12:20:00.000Z"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
                            }
                        },
                        "did_group_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
                            }
                        },
                        "order": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
                            }
                        },
                        "emergency_requirement": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
                            }
                        },
                        "emergency_verification": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
                            }
                        },
                        "dids": {
                            "links": {
                                "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
                                "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
                            }
                        }
                    },
                    "meta": {
                        "setup_price": "0.0",
                        "monthly_price": "2.5"
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/emergency_verifications?filter%5Bstatus%5D=pending&include=emergency_calling_service&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/emergency_verifications?filter%5Bstatus%5D=pending&include=emergency_calling_service&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"
   "400", "No", "Invalid resource for earlier API versions."


.. |br| raw:: html

   <br />

.. _emergency_verifications_v34:

=======================
Emergency Verifications
=======================

Returns a single or a list of Emergency Verifications in the account. Allows create a
callback / webhook method to receive notifications associated with verification statuses.

Supported methods: ``GET``, ``POST``, ``PATCH``

.. toctree::
  :maxdepth: 1

  get-emergency-verification.rst
  get-emergency-verifications.rst
  create-emergency-verification.rst
  update-emergency-verification.rst
  emergency-verification-object.rst


=============================
Update Emergency Verification
=============================

Update the settings of a single Emergency Verification owned by your account.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/emergency_verifications/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Emergency Verification."

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "external_reference_id", "``string``", "No", "Optional identifier for the emergency verification in the customer's external system. Maximum length is 100 characters."

Examples
========

.. tabs::

   .. tab:: Update external_reference_id

    .. http:example:: curl

        PATCH /v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
            "type": "emergency_verifications",
            "attributes": {
              "external_reference_id": "test"
            }
          }
        }

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
            "type": "emergency_verifications",
            "attributes": {
              "reference": "SHB-991234",
              "status": "approved",
              "reject_reasons": [],
              "reject_comment": null,
              "callback_url": null,
              "callback_method": null,
              "created_at": "2026-01-10T09:00:00.000Z",
              "external_reference_id": "test"
            },
            "relationships": {
              "address": {
                "links": {
                  "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/address",
                  "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/address"
                }
              },
              "emergency_calling_service": {
                "links": {
                  "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/emergency_calling_service",
                  "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/emergency_calling_service"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/dids",
                  "related": "https://api.didww.com/v3/emergency_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/dids"
                }
              }
            }
          },
          "meta": {
            "api_version": "2026-04-16"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

===================
Emergency Resources
===================

Emergency Resources allow customers to register their DID numbers for emergency calling
services (E911/E112) via API.

The emergency registration requirements are unique to each country and type of DID number.
DIDWW customers have an obligation to provide valid address and identity information in
order to activate emergency calling for their DID numbers.

To review the emergency registration requirements for each individual country and number
type you can use the :doc:`Emergency Requirements <emergency-requirements/index>`
resource.

All verifications will be reviewed by the DIDWW Emergency Team. Once approved, when the
Emergency Calling Service status becomes ``active``, emergency routing is enabled for the
DIDs associated with the verification and the calling service.

.. raw:: html

   <h2 id="how-to-register-emergency-calling-service">How to Register Emergency Calling Service<a class="headerlink" href="#how-to-register-emergency-calling-service" title="Link to this heading"></a></h2>

For the full step-by-step guide, see :doc:`Register Emergency Calling Service <../../examples/register-emergency-calling-service>`.

To create an emergency calling registration for your DIDs, the following steps are
required:

1. Check the :doc:`Emergency Requirements <emergency-requirements/index>` for the country
   and DID group type you want to register.
2. Create an Identity. Two types of identities are supported:

   a. Personal Identity
   b. Business Identity

3. Create an Address.
4. :doc:`Validate <emergency-requirements/emergency-requirement-validations>` the
   identity and address against the emergency requirement.
5. Submit an :doc:`Emergency Verification <emergency-verifications/index>` in New
   Calling Service mode. Provide the address and the DIDs to register. A new
   :doc:`Emergency Calling Service <emergency-calling-services/index>` will be created
   automatically.
6. The verification will be reviewed by the DIDWW Emergency Team.
7. Once the :doc:`Emergency Verification <emergency-verifications/index>` is approved and
   the associated :doc:`Emergency Calling Service <emergency-calling-services/index>`
   status changes to ``active``, emergency routing is enabled for the DIDs specified in
   the Emergency Verification.
8. If rejected, the status changes to ``changes_required``. Review the ``reject_reasons``
   field and resubmit a new verification with corrected data.

.. raw:: html

   <h2 id="updating-an-existing-emergency-calling-service">Updating an Existing Emergency Calling Service<a class="headerlink" href="#updating-an-existing-emergency-calling-service" title="Link to this heading"></a></h2>

For the full step-by-step guide, see :doc:`Update Emergency Calling Service <../../examples/update-emergency-calling-service>`.

To update the address on an already active :doc:`Emergency Calling Services
<emergency-calling-services/index>` resource:

1. Submit a new :doc:`Emergency Verification <emergency-verifications/index>` in
   Existing Calling Service mode. Provide the new address and the existing
   ``emergency_calling_service`` relationship.
2. The calling service status changes to ``pending_update`` while under review.
3. Once approved, the service becomes ``active`` with the updated address.

.. note::

   Adding or removing DIDs from an existing Emergency Calling Service is only possible
   through the DID resource.

.. raw:: html

   <h2 id="requirement-address-area-level">Requirement Address Area Level<a class="headerlink" href="#requirement-address-area-level" title="Link to this heading"></a></h2>

The Emergency Requirement enforces that the registered :ref:`Address <addresses_v34>`
must be from a specific geographic area.

The ``address_area_level`` attribute may be one of the following:

.. csv-table::
   :header: "Value", "Description"

   "country", "Address must be within the requirement country"
   "area", "Address must be within the locality or region covered by the phone number's prefix"
   "city", "Address must be from the same city as the registered DIDs"

.. raw:: html

   <h2 id="requirement-identity-area-level">Requirement Identity Area Level<a class="headerlink" href="#requirement-identity-area-level" title="Link to this heading"></a></h2>

The Emergency Requirement may enforce that the :ref:`Identity <identities_v34>` must be
from a specific country.

The ``personal_area_level`` and/or ``business_area_level`` attributes may be one of the
following:

.. csv-table::
   :header: "Value", "Description"

   "world_wide", "Identity from any country can be used"
   "country", "Identity must be within the requirement country"

.. raw:: html

   <h2 id="requirement-mandatory-fields">Requirement Mandatory Fields<a class="headerlink" href="#requirement-mandatory-fields" title="Link to this heading"></a></h2>

The Emergency Requirement may require certain optional :ref:`Identity <identities_v34>`
or :ref:`Address <addresses_v34>` fields to be filled in.

If the requirement has ``personal_mandatory_fields``, ``business_mandatory_fields``, or
``address_mandatory_fields``, the corresponding attributes of the
:ref:`Identity <identities_v34>` or :ref:`Address <addresses_v34>` must be provided.

Following mandatory values can be included in ``personal_mandatory_fields`` and/or
``business_mandatory_fields``:

.. csv-table::
   :header: "Attribute", "Description"

   "birth_date", "Birth Date of a Person"
   "personal_tax_id", "Personal Tax Number"
   "id_number", "Proof of ID"
   "vat_id", "VAT / TAX Number"
   "company_reg_number", "Company Registration Number"
   "contact_email", "Contact email address"
   "country", "Country of Tax Residence"
   "company_representative_date_of_birth", "Company Representative Date of Birth"

Following mandatory values can be included in ``address_mandatory_fields``:

.. csv-table::
   :header: "Attribute", "Description"

   "area", "State / Province / Region"

.. raw:: html

   <h2 id="emergency-calling-service-status-values">Emergency Calling Service Status Values<a class="headerlink" href="#emergency-calling-service-status-values" title="Link to this heading"></a></h2>

.. csv-table::
   :header: "Status", "Description"

   "new", "Service created, awaiting first verification submission"
   "in_process", "Verification submitted and under review by DIDWW Emergency Team"
   "changes_required", "Verification was rejected and a new verification must be submitted"
   "pending_update", "Active service with an updated verification under review"
   "active", "Service is approved and emergency calling is operational"
   "canceled", "Service has been permanently canceled"

.. raw:: html

   <h2 id="emergency-resources-overview">Emergency Resources Overview<a class="headerlink" href="#emergency-resources-overview" title="Link to this heading"></a></h2>

- :doc:`Emergency Requirements <emergency-requirements/index>` - Read-only. Describes
  registration requirements per country and DID group type, including required identity
  type, address area level, mandatory fields, estimated setup time, and pricing.
- :doc:`Emergency Requirement Validations <emergency-requirements/emergency-requirement-validations>` -
  Write-only. Checks whether an Address and / or Identity satisfies a selected Emergency
  Requirement before an Emergency Verification is submitted.
- :doc:`Emergency Calling Services <emergency-calling-services/index>` - Read and delete.
  The main entity representing an active emergency subscription tied to a customer's
  DIDs.
- :doc:`Emergency Verifications <emergency-verifications/index>` - Read, create, and update.
  Verification requests submitted for review. Supports callbacks on status change and
  updating ``external_reference_id``.

.. toctree::
   :maxdepth: 2
   :hidden:

   emergency-requirements/index
   emergency-calling-services/index
   emergency-verifications/index




=============
Create Export
=============

.. attention::

    Please note that the Inbound/Outbound CDR export is available for current + 2 last months.

Creates a single Export. DIDWW performs deletion of CDR Export in 1 month after completion.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/exports``

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "filters", ":ref:`CDR Export Filters Object <export_filters_object_v34>`", "False", "Yes", "Filters"
   "callback_url", "``string``", "True", "No", "The HTTP or HTTPS endpoint to where events related to export will be delivered."
   "callback_method", "``string``", "True", "No", "The HTTP Method used for export events. ``post`` and ``get`` are supported methods."
   "external_reference_id", "``string``", "True", "No", "Optional identifier for the export in the customer's external system. Maximum length is 100 characters."

See :ref:`Callback details <callbacks_details_v34>` for information about **callback_url** and **callback_method**.

Filters by Export Type
----------------------

.. tabs::

   .. tab:: cdr_in

	.. csv-table::
		:header: "Name", "Type", "Is Required?", "Description"

		"from", "``string``", "Yes", "Start date and time of the CDR range."
		"to", "``string``", "Yes", "End date and time of the CDR range."
		"did_number", "``string``", "No", "CDR export for a specified DID number. If the 'did_number' parameter is not used, CDRs are exported for all owned DID numbers."

   .. tab:: cdr_out

	.. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "from", "``string``", "Yes", "Start date and time of the CDR range."
	   "to", "``string``", "Yes", "End date and time of the CDR range."
	   "voice_out_trunk.id", "``string``", "No", "ID of voice out trunk."

Examples
========

.. tabs::

    .. tab:: Inbound CDR Example

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "export_type": "cdr_in",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "did_number": "123456789"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "33bdfff7-4de3-4c58-8c90-b99930fb984a",
                "type": "exports",
                "attributes": {
                  "status": "pending",
                  "created_at": "2025-12-16T06:39:44.465Z",
                  "external_reference_id": null,
                  "url": null,
                  "callback_url": null,
                  "callback_method": null,
                  "export_type": "cdr_in",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "did_number": "123456789"
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

    .. tab:: Inbound CDR Example with Callback

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "get",
                  "export_type": "cdr_in",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "did_number": "123456789"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "d4f37476-8ece-4add-bbcb-cc72a7908fe2",
                "type": "exports",
                "attributes": {
                  "status": "pending",
                  "created_at": "2025-12-16T06:54:30.122Z",
                  "external_reference_id": null,
                  "url": null,
                  "callback_url": "http://example.com",
                  "callback_method": "get",
                  "export_type": "cdr_in",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "did_number": "123456789"
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

    .. tab:: Outbound CDR Example

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "export_type": "cdr_out",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "88a29a27-11fe-4db0-a508-eca1d7cf0b68",
                "type": "exports",
                "attributes": {
                  "status": "pending",
                  "created_at": "2025-12-21T07:37:13.085Z",
                  "external_reference_id": null,
                  "url": null,
                  "callback_url": null,
                  "callback_method": null,
                  "export_type": "cdr_out",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

    .. tab:: Outbound CDR Example with Callback

        .. http:example:: curl

            POST /v3/exports HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "exports",
                "attributes": {
                  "export_type": "cdr_out",
                  "callback_url": "http://example.com",
                  "callback_method": "get",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "67e4f27f-d5eb-4b80-8924-39486aee6ed4",
                "type": "exports",
                "attributes": {
                  "status": "pending",
                  "created_at": "2025-12-21T07:42:02.546Z",
                  "external_reference_id": null,
                  "url": null,
                  "callback_url": "http://example.com",
                  "callback_method": "get",
                  "export_type": "cdr_out",
                  "filters": {
                    "from": "2025-12-01T00:00:00Z",
                    "to": "2025-12-31T23:59:59Z",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "422", "No", ":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _export_filters_object_v34:

=====================
Export Filters Object
=====================

Export Filters keys.

Attributes
==========

.. tabs::

   .. tab:: cdr_in

      .. csv-table::
         :header: "Name", "Type", "Nullable", "Description"

         "from", "``string``", "False", "Start date and time of the CDR range."
         "to", "``string``", "False", "End date and time of the CDR range."
         "did_number", "``string``", "False", "Filters CDRs by DID number."

   .. tab:: cdr_out

      .. csv-table::
         :header: "Name", "Type", "Nullable", "Description"

         "from", "``string``", "False", "Start date and time of the CDR range."
         "to", "``string``", "False", "End date and time of the CDR range."
         "voice_out_trunk.id", "``string``", "False", "Filters CDRs by Outbound Trunk."


.. _export_object_v34:

=============
Export Object
=============

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Nullable", "Description"

   "status", "``string``", "False", "Status can be ``pending``, ``processing``, or ``completed``."
   "created_at", "``DateTime``", "False", "Timestamp when export request was created."
   "url", "``string``", "True", "The URL of the CSV file for downloading. Available only when status is ``completed``."
   "callback_url", "``string``", "True", "The HTTP or HTTPS endpoint to where events related to export will be delivered."
   "callback_method", "``string``", "True", "The callback method used for export events. ``post`` and ``get`` are supported methods."
   "external_reference_id", "``string``", "True", "Optional identifier for the export in the customer's external system. Maximum length is 100 characters."
   "export_type", "``string``", "False", "Defines CDR export type."
   "filters", ":ref:`CDR Export Filters Object <export_filters_object_v34>`", "True", "Filters used to create the export."




======================
Get CSV File of Export
======================

Returns a single .csv.gz file for corresponding Export.

.. attention::

    | Please note that the file is available for Download Only! It can not be read as in previous versions due to .csv file being Archived as .gz format archive for compression of space.
    | To receive the CDR export file, a query should be sent to /v3/exports/{filename}.csv.gz, and the {filename} can be obtained from the response of :ref:`Get Exports <get_exports_v34>` URL attribute or :ref:`Get Export <get_export_v34>` following by export ID.

Exported File Format
====================

The exported file contains call detail records (CDRs) in CSV format.

Inbound CDRs
------------

:download:`Inbound CDR sample <inbound_cdr_sample.csv>`

.. csv-table::
   :header: "Column", "Type", "Description"

   "Date/Time Start (UTC)","``string``","Call start timestamp in UTC."
   "Date/Time Connect (UTC)","``string``","Call answer timestamp in UTC."
   "Date/Time End (UTC)","``string``","Call end timestamp in UTC."
   "Status","``string``","Call status."
   "Source","``string``","Source number."
   "Source Name","``string``","Caller name."
   "Destination DID","``string``","Destination DID number."
   "Duration (sec)","``integer``","Call duration in seconds."
   "Attempt","``integer``","Call attempt number."
   "Disconnect Code","``string``","Disconnect code."
   "Response","``string``","SIP response or system response."
   "Disconnect Initiator","``string``","Entity that initiated call termination."
   "Voice IN Trunk","``string``","Voice In trunk identifier or name."
   "Destination","``string``","Destination number."
   "Trunk Group","``string``","Associated trunk group."
   "Capacity Group","``string``","Associated capacity group."
   "Toll-free (USD)","``string``","Toll-free cost in USD."
   "PSTN (USD)","``string``","PSTN cost in USD."
   "Metered (USD)","``string``","Metered cost in USD."
   "CNAM IN (USD)","``string``","CNAM lookup cost in USD."
   "Total (USD)","``string``","Total cost in USD."
   "Call ID","``string``","Unique call identifier."

Outbound CDRs
-------------

:download:`Outbound CDR sample <outbound_cdr_sample.csv>`

.. csv-table::
   :header: "Column", "Type", "Description"

   "Date/Time Start (UTC)","``string``","Call start timestamp in UTC."
   "Date/Time Connect (UTC)","``string``","Call answer timestamp in UTC."
   "Date/Time End (UTC)","``string``","Call end timestamp in UTC."
   "Status","``string``","Call status."
   "Source","``string``","Source number."
   "CLI","``string``","Calling Line Identification."
   "Destination Number","``string``","Destination number."
   "Call Duration (sec)","``integer``","Call duration in seconds."
   "Billing Duration (sec)","``integer``","Billed duration in seconds."
   "Disconnect Code","``string``","Disconnect code."
   "Disconnect Reason","``string``","Disconnect reason description."
   "Voice OUT Trunk","``string``","Voice Out trunk identifier or name."
   "Destination Country","``string``","Destination country."
   "Network","``string``","Destination network."
   "Call Type","``string``","Call type classification."
   "Rate (USD)","``string``","Rate per unit in USD."
   "Charged (USD)","``string``","Charged amount in USD."
   "P-Charge-Info","``string``","Charging information header."
   "Call ID","``string``","Unique call identifier."

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/exports/{filename}.csv.gz``

.. note:: For all returned data attributes, see :doc:`Export Object <export-object>`.

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filename", "``string``", "Yes", "Unique filename of completed CDR Export."
   
Examples
========

.. http:example:: curl

	GET /v3/exports/a4f6b765-f20c-45c7-98d2-80c2f3a41517.csv.gz HTTP/1.1
	Host: api.didww.com
	Api-Key: [API token]
	
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", "Not Found (without body)"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _get_export_v34:

==========
Get Export
==========

Returns a single Export.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/exports/:id``

.. note:: For all returned data attributes, see :doc:`Export Object <export-object>`.

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of CDR Export."

Examples
========

.. http:example:: curl

	GET /v3/exports/77ebb57f-7b01-4178-bc84-9d1a8d2ae850 HTTP/1.1
	Host: api.didww.com
	Content-Type: application/vnd.api+json
	Accept: application/vnd.api+json
	Api-Key: [API token]
	
	
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	
        {
           "data":    {
              "id": "77ebb57f-7b01-4178-bc84-9d1a8d2ae850",
              "type": "exports",
              "attributes":       {
                 "status": "completed",
                 "created_at": "2025-04-02T10:00:00.000Z",
                 "external_reference_id": null,
                 "url": "https://api.didww.com/v3/exports/[filename].csv.gz",
                 "callback_url": null,
                 "callback_method": null,
                 "export_type": "cdr_out",
                 "filters": {
                    "from": "2025-03-01 00:00:00",
                    "to": "2025-03-31 23:59:59",
                    "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                 }
              }
           },
           "meta": {"api_version": "2026-04-16"}
        }
	
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _get_exports_v34:

===========
Get Exports
===========

Returns a collection of Exports.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/exports``

.. note:: For all returned data attributes, see :doc:`Export Object <export-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[exports]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"
   "page[number]", "``integer``", "No", ":ref:`Page number <api_pagination>`."
   "page[size]", "``integer``", "No", ":ref:`Page size <api_pagination>`."

Filters
-------

The ``external_reference_id`` filter applies to all export types. Other filters differ depending on the ``export_type`` :ref:`Data attribute <get_exports_v34_data_attributes>`.

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

.. tabs::

   .. tab:: cdr_in

      .. csv-table::
         :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

         "from", "``string``", "No", "No", "The start date and time of the CDR range."
         "to", "``string``", "No", "No", "The end date and time of the CDR range."
         "did_number", "``string``", "Yes", "No", "The DID number used to filter inbound CDR exports."

   .. tab:: cdr_out

      .. csv-table::
         :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

         "from", "``string``", "No", "No", "The start date and time of the CDR range."
         "to", "``string``", "No", "No", "The end date and time of the CDR range."
         "voice_out_trunk.id", "``string``", "Yes", "No", "The outbound trunk identifier used to filter outbound CDR exports."

Sorting
-------

.. csv-table::
   :header: "Value", "Description"

   "status", "The ``status`` field. Possible values: ``pending``, ``processing``, ``completed``."
   "created_at", "The ``created_at`` field."

.. _get_exports_v34_data_attributes:

Examples
========

.. tabs::

   .. tab:: cdr_in

      .. http:example:: curl

         GET /v3/exports HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "6fee87b1-5f86-470c-80ca-9c3922653de9",
               "type": "exports",
               "attributes": {
                 "status": "processing",
                 "created_at": "2025-12-13T20:02:07.798Z",
                 "external_reference_id": null,
                 "url": null,
                 "callback_url": null,
                 "callback_method": null,
                 "export_type": "cdr_in",
                 "filters": {
                   "from": "2025-12-01 00:00:00",
                   "to": "2025-12-31 23:59:59",
                   "did_number": "123456789"
                 }
               }
             },
             {
               "id": "33bdfff7-4de3-4c58-8c90-b99930fb984a",
               "type": "exports",
               "attributes": {
                 "status": "processing",
                 "created_at": "2025-12-16T06:39:44.465Z",
                 "external_reference_id": null,
                 "url": null,
                 "callback_url": null,
                 "callback_method": null,
                 "export_type": "cdr_in",
                 "filters": {
                   "from": "2025-12-01 00:00:00",
                   "to": "2025-12-31 23:59:59",
                   "did_number": "123456789"
                 }
               }
             },
             {
               "id": "d4f37476-8ece-4add-bbcb-cc72a7908fe2",
               "type": "exports",
               "attributes": {
                 "status": "processing",
                 "created_at": "2025-12-16T06:54:30.122Z",
                 "external_reference_id": null,
                 "url": null,
                 "callback_url": "http://example.com",
                 "callback_method": "get",
                 "export_type": "cdr_in",
                 "filters": {
                   "from": "2025-12-01 00:00:00",
                   "to": "2025-12-31 23:59:59",
                   "did_number": "123456789"
                 }
               }
             }
           ],
           "meta": {
             "total_records": 3,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/exports?page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/exports?page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab:: cdr_out

      .. http:example:: curl

         GET /v3/exports HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "88a29a27-11fe-4db0-a508-eca1d7cf0b68",
               "type": "exports",
               "attributes": {
                 "status": "completed",
                 "created_at": "2025-12-21T07:37:13.085Z",
                 "external_reference_id": null,
                 "url": "https://api.didww.com/v3/exports/a8bf7c0e-0c08-44ca-b0e2-db34a1d2006a.csv.gz",
                 "callback_url": null,
                 "callback_method": null,
                 "export_type": "cdr_out",
                 "filters": {
                   "from": "2025-12-01 00:00:00",
                   "to": "2025-12-31 23:59:59",
                   "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                 }
               }
             },
             {
               "id": "67e4f27f-d5eb-4b80-8924-39486aee6ed4",
               "type": "exports",
               "attributes": {
                 "status": "completed",
                 "created_at": "2025-12-21T07:42:02.546Z",
                 "external_reference_id": null,
                 "url": "https://api.didww.com/v3/exports/b15d6a4b-3c99-4bee-af6b-f5f37ce30511.csv.gz",
                 "callback_url": "http://example.com",
                 "callback_method": "get",
                 "export_type": "cdr_out",
                 "filters": {
                   "from": "2025-12-01 00:00:00",
                   "to": "2025-12-31 23:59:59",
                   "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                 }
               }
             },
             {
               "id": "77165c85-0a37-43d1-b3f8-c76d2eb50315",
               "type": "exports",
               "attributes": {
                 "status": "completed",
                 "created_at": "2025-12-21T07:54:35.789Z",
                 "external_reference_id": null,
                 "url": "https://api.didww.com/v3/exports/94593896-818a-4a00-b89b-e4d825f4c0d5.csv.gz",
                 "callback_url": "http://example.com",
                 "callback_method": "get",
                 "export_type": "cdr_out",
                 "filters": {
                   "from": "2025-12-01 00:00:00",
                   "to": "2025-12-31 23:59:59",
                   "voice_out_trunk.id": "457bf47d-446d-41cd-91c3-dfbda7bf0753"
                 }
               }
             }
           ],
           "meta": {
             "total_records": 3,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/exports?page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/exports?page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }
	
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _export_v34:

======
Export
======

DIDWW API v3 Export functionality allows to create and download non-realtime .csv files with Call Detail Records (CDRs). Deletion of created CDR Export is done in 1 month after completion.

.. note::
   Real-time CDR mechanism for repetitive CDRs data transfer is available :ref:`here <cdr_streaming>`.

Supported methods: ``GET``, ``POST``.

.. toctree:: 
  :titlesonly:
  	
  get-export.rst
  get-exports.rst
  get-csv-file-of-export.rst
  create-export.rst
  export-object.rst
  export-filters-object.rst



.. _balance_object_v34:

==============
Balance Object
==============

JSONAPI object that represents the user’s balance and has following attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"
   
   "balance","``string``","Prepaid balance" 
   "credit","``string``","Available credit   " 
   "total_balance","``string``","The net balance (balance+credit)." 

   
   
   
   
   

   





===========
Get Balance
===========

Returns the prepaid balance as well as the available credit on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/balance``

.. note:: For all returned data attributes, see :doc:`Balance Object <balance-object>`.

Example
=======

.. http:example:: curl

    GET /v3/balance HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
      "data": {
        "id": "94441ce5-86fa-47bd-8ce7-b5e267d0603a",
        "type": "balances",
        "attributes": {
          "balance": "50.00",
          "credit": "10.00",
          "total_balance": "60.00"
        }
      }
    }
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _balance_v34:

=======
Balance
=======

Returns the prepaid balance as well as the available credit on your account. 

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-balance.rst
  balance-object.rst
  
  


.. _capacity_pool_object_v34:

====================
Capacity Pool Object
====================

Capacity Pool Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Name of the Capacity Pool."
   "renew_date", "``date``", "Channel renewal date."
   "total_channels_count", "``integer``", "Total number of channels in the Capacity Pool."
   "assigned_channels_count", "``integer``", "Number of channels used in Shared Capacity Groups and/or assigned to DID numbers."
   "minimum_limit", "``integer``", "Minimum number of channels to be kept in the Capacity Pool."
   "minimum_qty_per_order", "``integer``", "Minimum number of channels per Order."
   "setup_price", "``string``", "Non Recurring Cost (one-time activation fee)."
   "monthly_price", "``string``", "Monthly Recurring Cost (ongoing monthly fee)."
   "metered_rate", "``string``", "Metered channel price per minute."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "countries", "to-many", ":ref:`Country Object <country_object_v34>`. Returns the countries available for the Capacity Pool."
   "shared_capacity_groups", "to-many", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`. Returns the shared capacity groups linked to the Capacity Pool."
   "qty_based_pricings", "to-many", ":ref:`Quantity Based Price Object <quantity_based_price_object_v34>`. Returns the quantity-based pricing tiers for the Capacity Pool."



=================
Get Capacity Pool
=================

Returns a single Capacity Pool.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/capacity_pools/``

.. note:: For all returned data attributes, see :doc:`Capacity Pool Object <capacity-pool-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number allocated to this Capacity Pool."
   "include","``string``","No",":ref:`Inclusion <api_includes>`. "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "countries", ":ref:`Country Object <country_object_v34>`"
   "shared_capacity_groups", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`"
   "qty_based_pricings", ":ref:`Quantity Based Price Object <quantity_based_price_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 10,
              "assigned_channels_count": 6,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                }
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                }
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          }
        }
        
   .. tab:: Include Countries
   
     .. http:example:: curl
   
        GET /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f?include=countries HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 10,
              "assigned_channels_count": 6,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                },
                "data": [
                  {
                    "type": "countries",
                    "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8"
                  },
                  {
                    "type": "countries",
                    "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                  }
                ]
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                }
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          },
          "included": [
            {
              "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8",
              "type": "countries",
              "attributes": {
                "name": "United Kingdom",
                "prefix": "44",
                "iso": "GB"
              }
            },
            {
              "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
              "type": "countries",
              "attributes": {
                "name": "United States",
                "prefix": "1",
                "iso": "US"
              }
            }
          ]
        }
        
   .. tab:: Include Shared Capacity Groups
   
     .. http:example:: curl
   
        GET /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f?include=shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 10,
              "assigned_channels_count": 6,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                }
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                },
                "data": [
                  {
                    "type": "shared_capacity_groups",
                    "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc"
                  }
                ]
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          },
          "included": [
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Sample group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ]
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



==================
Get Capacity Pools
==================

Returns a list of Capacity Pools.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/capacity_pools``

.. note:: For all returned data attributes, see :doc:`Capacity Pool Object <capacity-pool-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include","``string``", "No", ":ref:`Inclusion <api_includes>` "
   "filter[<filter_name>]","``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[capacity_pools]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>` "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "countries", ":ref:`Country Object <country_object_v34>`"
   "shared_capacity_groups", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`"
   "qty_based_pricings", ":ref:`Quantity Based Price Object <quantity_based_price_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Capacity Pool ``id`` field. "

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by"

   "name", "The ``name`` field."
   "renew_date", "The ``renew_date`` field."
   "total_channels_count", "The ``total_channels_count`` field."
   "assigned_channels_count", "The ``assigned_channels_count`` field."
   "minimum_limit", "The ``minimum_limit`` field."
   "minimum_qty_per_order", "The ``minimum_qty_per_order`` field."
   "setup_price", "The ``setup_price`` field."
   "monthly_price", "The ``monthly_price`` field."
   "metered_rate", "The ``metered_rate`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/capacity_pools HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "ca1315c5-1915-4fc7-9441-de78e1f38ef9",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 136,
                "assigned_channels_count": 136,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "25.0",
                "monthly_price": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/qty_based_pricings"
                  }
                }
              }
            },
            {
              "id": "daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d",
              "type": "capacity_pools",
              "attributes": {
                "name": "Standard",
                "renew_date": "2018-07-21",
                "total_channels_count": 2,
                "assigned_channels_count": 2,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "15.0",
                "monthly_price": "15.0",
                "metered_rate": "0.01"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Include Countries
   
     .. http:example:: curl
   
        GET /v3/capacity_pools?include=countries HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "ca1315c5-1915-4fc7-9441-de78e1f38ef9",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 136,
                "assigned_channels_count": 136,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "25.0",
                "monthly_price": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/countries"
                  },
                  "data": [
                    {
                      "type": "countries",
                      "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8"
                    }
                  ]
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/qty_based_pricings"
                  }
                }
              }
            },
            {
              "id": "daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d",
              "type": "capacity_pools",
              "attributes": {
                "name": "Standard",
                "renew_date": "2018-07-21",
                "total_channels_count": 2,
                "assigned_channels_count": 2,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "15.0",
                "monthly_price": "15.0",
                "metered_rate": "0.01"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/countries"
                  },
                  "data": [
                    {
                      "type": "countries",
                      "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9"
                    }
                  ]
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "7eda11bb-0e66-4146-98e7-57a5281f56c8",
              "type": "countries",
              "attributes": {
                "name": "United Kingdom",
                "prefix": "44",
                "iso": "GB"
              }
            },
            {
              "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
              "type": "countries",
              "attributes": {
                "name": "United States",
                "prefix": "1",
                "iso": "US"
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Include Shared Capacity Groups
   
     .. http:example:: curl
   
        GET /v3/capacity_pools?include=shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "ca1315c5-1915-4fc7-9441-de78e1f38ef9",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 136,
                "assigned_channels_count": 136,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "25.0",
                "monthly_price": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/shared_capacity_groups"
                  },
                  "data": [
                    {
                      "type": "shared_capacity_groups",
                      "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc"
                    }
                  ]
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/ca1315c5-1915-4fc7-9441-de78e1f38ef9/qty_based_pricings"
                  }
                }
              }
            },
            {
              "id": "daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d",
              "type": "capacity_pools",
              "attributes": {
                "name": "Standard",
                "renew_date": "2018-07-21",
                "total_channels_count": 2,
                "assigned_channels_count": 2,
                "minimum_limit": 0,
                "minimum_qty_per_order": 1,
                "setup_price": "15.0",
                "monthly_price": "15.0",
                "metered_rate": "0.01"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/daae37a3-c4fc-40a7-b5e6-6ec9d08ed74d/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Sample group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/capacity_pools?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

.. _capacity_pools_v34:

=============
Capacity Pool
=============

.. note::

    To get familiar with Capacity and its options, please read this article: :ref:`Flexible Capacity <flexible_capacity>`

Returns a single or a list of the Capacity Pools which includes information about channels quantity, supported Countries, Shared Capacity Groups. 

Supported methods: ``GET``, ``PATCH``.

.. toctree::
  :maxdepth: 1
  
  get-capacity-pool.rst
  get-capacity-pools.rst
  update-capacity-pool.rst
  capacity-pool-object.rst
  
  
  
  



====================
Update Capacity Pool
====================

Allows to update the existing Capacity Pool. By using this endpoint it is possible to remove Unassigned Channels from the Capacity Pool.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/capacity_pools/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID number allocated to this Capacity Pool."
   "include","``string``","No",":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Title", "Type", "Nullable", "Description"

   "total_channels_count", "``integer``","False", "Total number of channels in the Capacity Pool."

Examples
========

.. tabs::

   .. tab:: Sample 1
   
     .. http:example:: curl
   
        PATCH /v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "total_channels_count": 8
            }
          }
        }
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
            "type": "capacity_pools",
            "attributes": {
              "name": "Extended",
              "renew_date": "2018-07-21",
              "total_channels_count": 8,
              "assigned_channels_count": 7,
              "minimum_limit": 5,
              "minimum_qty_per_order": 1,
              "setup_price": "25.0",
              "monthly_price": "25.0",
              "metered_rate": "0.02"
            },
            "relationships": {
              "countries": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                }
              },
              "shared_capacity_groups": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                }
              },
              "qty_based_pricings": {
                "links": {
                  "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                  "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                }
              }
            }
          }
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _did_history_object_v34:

==================
DID History Object
==================

JSONAPI object that represents a DID history record from the last ``90`` days and has the following attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "did_number","``string``","DID number related to the history record."
   "action","``string``","Action performed on the DID. Allowed values: ``assigned``, ``renewed``, ``canceled``, ``removed``, ``billing_cycles_count_changed``, ``restored``."
   "method","``string``","Method used to perform the action. Allowed values: ``system``, ``api2``, ``api3``, ``staff``, ``user_panel``."
   "created_at","``string``","Date and time when the history record was created in ISO 8601 format."

Available action values
-----------------------

.. csv-table::
   :header: "Value", "Description"

   "assigned","Assigned DID event."
   "renewed","Renewed DID event."
   "canceled","Canceled DID event."
   "removed","Removed DID event."
   "billing_cycles_count_changed","Billing cycles count change event."
   "restored","Restored DID event."

Available method values
-----------------------

.. csv-table::
   :header: "Value", "Description"

   "system","Action performed by the system."
   "api2","Action performed through API v2."
   "api3","Action performed through API v3."
   "staff","Action performed by staff."
   "user_panel","Action performed from the user panel."

Meta
----

The ``meta`` member is returned for ``billing_cycles_count_changed`` records.

.. csv-table::
   :header: "Name", "Type", "Description"

   "from","``string``","Previous billing cycles count value."
   "to","``string``","New billing cycles count value."


=================
Get DID Histories
=================

Returns a list of DID history records for your account. Only records from the last ``90`` days are available. The data is sourced from events shown on the billing Histories page, and older records in that ``90``-day window are backfilled with UUID values.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_history``

.. note:: For all returned data attributes, see :doc:`Did History Object <did-history-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``","No",":ref:`Filtering <api_filters>`"
   "fields[did_history]","``string``","No",":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"
   "page[number]","``integer``","No",":ref:`Page number <api_pagination>`."
   "page[size]","``integer``","No",":ref:`Page size <api_pagination>`. Pagination defaults to ``50`` records per page."

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id","``string``","No","Yes","The DID history UUID."
   "did_number","``string``","No","No","The DID number."
   "action","``string``","No","No","The action value."
   "method","``string``","No","No","The method value."
   "created_at_gteq","``string``","No","No","Records created on or after the specified date and time."
   "created_at_lteq","``string``","No","No","Records created on or before the specified date and time."

Available Action Values
-----------------------

.. csv-table::
   :header: "Value", "Description"

   "assigned", "DID assignment event."
   "renewed", "DID renewal event."
   "canceled", "DID cancellation event."
   "removed", "DID release or removal event."
   "billing_cycles_count_changed", "Billing cycles count change event."
   "restored", "DID restoration event."

.. note:: The ``meta.from`` and ``meta.to`` values are returned only for ``billing_cycles_count_changed`` records.

Available Method Values
-----------------------

.. csv-table::
   :header: "Value", "Description"

   "system","Action performed by the system."
   "api2","Action performed through API v2."
   "api3","Action performed through API v3."
   "staff","Action performed by staff."
   "user_panel","Action performed from the user panel."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "created_at","Creation timestamp"

Examples
========

.. tabs::

   .. tab:: Simple Request

      .. http:example:: curl

         GET /v3/did_history HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
                     "type": "did_history",
                     "attributes": {
                         "did_number": "437xxxxxxxxx",
                         "action": "removed",
                         "method": "api3",
                         "created_at": "2026-03-06T15:11:00.326Z"
                     }
                 },
                 {
                     "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                     "type": "did_history",
                     "attributes": {
                         "did_number": "437xxxxxxxxx",
                         "action": "renewed",
                         "method": "api2",
                         "created_at": "2026-04-16T11:30:00.000Z"
                     }
                 },
                 {
                     "id": "9e3b65e9-fdc4-1810-9e93-b7127ab59ee6",
                     "type": "did_history",
                     "attributes": {
                         "did_number": "437xxxxxxxxx",
                         "action": "billing_cycles_count_changed",
                         "method": "staff",
                         "created_at": "2026-04-03T17:42:45.728Z"
                     },
                     "meta": {
                         "from": "empty",
                         "to": "5"
                     }
                 }
             ],
             "links": {
                 "first": "https://api.didww.com/v3/did_history?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                 "last": "https://api.didww.com/v3/did_history?page%5Bnumber%5D=1&page%5Bsize%5D=50"
             },
             "meta": {
                 "total_records": 3,
                 "api_version": "2026-04-16"
             }
         }

   .. tab:: Filter by Timeframe

      .. http:example:: curl

         GET /v3/did_history?filter[created_at_gteq]=2026-03-01T00:00:00Z&filter[created_at_lteq]=2026-04-01T00:00:00Z HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
                     "type": "did_history",
                     "attributes": {
                         "did_number": "437xxxxxxxxx",
                         "action": "removed",
                         "method": "api3",
                         "created_at": "2026-03-06T15:11:00.326Z"
                     }
                 },
                 {
                     "id": "9e3b65e9-fdc4-1810-9e93-b7127ab59ee6",
                     "type": "did_history",
                     "attributes": {
                         "did_number": "437xxxxxxxxx",
                         "action": "billing_cycles_count_changed",
                         "method": "staff",
                         "created_at": "2026-04-03T17:42:45.728Z"
                     },
                     "meta": {
                         "from": "empty",
                         "to": "5"
                     }
                 }
             ],
             "links": {
                 "first": "https://api.didww.com/v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                 "last": "https://api.didww.com/v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z&page%5Bnumber%5D=1&page%5Bsize%5D=50"
             },
             "meta": {
                 "total_records": 2,
                 "api_version": "2026-04-16"
             }
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "400","No","Invalid filter value, invalid sort criteria, or the ``created_at`` filter date is outside the last 90 days."
   "401","No",":ref:`Unauthorized <api_key>`"


===============
Get DID History
===============

Returns a single DID history record from the last ``90`` days.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/did_history/{id}``

.. note:: For all returned data attributes, see :doc:`Did History Object <did-history-object>`.

URI Path Parameters
-------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id","``string``","Yes","Unique ID of the DID history record."

Examples
========

.. tabs::

   .. tab:: Action: Removed

      .. http:example:: curl

         GET /v3/did_history/9e3b65e9-fdc4-1810-9e93-b7127ab6b976 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
                 "type": "did_history",
                 "attributes": {
                     "did_number": "437xxxxxxxxx",
                     "action": "removed",
                     "method": "api3",
                     "created_at": "2026-03-06T15:11:00.326Z"
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

   .. tab:: Action: Billing Cycles Count Changed

      .. http:example:: curl

         GET /v3/did_history/9e3b65e9-fdc4-1810-9e93-b7127ab6b976 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
                 "type": "did_history",
                 "attributes": {
                     "did_number": "437xxxxxxxxx",
                     "action": "billing_cycles_count_changed",
                     "method": "staff",
                     "created_at": "2026-03-06T15:11:00.326Z"
                 },
                 "meta": {
                     "from": "3",
                     "to": "5"
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"


.. _did_history_v34:

===========
DID History
===========

Returns DID history records for your account.

.. note:: Only records from the last ``90`` days are available.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1

  get-did-history.rst
  get-did-histories.rst
  did-history-object.rst


.. _did_object_v34:

==========
DID Object
==========

DID Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "blocked", "``boolean``", "Identifier for a blocked DID. Blocked DIDs are numbers that have expired, have been cancelled or have been suspended by DIDWW."
   "awaiting_registration", "``boolean``", "Identifier for a DID that is awaiting registration."
   "pending_removal", "``boolean``", "Indicates whether the DID is pending removal."
   "terminated", "``boolean``", "Identifier for terminated DIDs that will be removed from service at the end of the billing cycle."
   "description", "``string``", "Custom DID description for customers reference."
   "number", "``string``", "The actual DID number in the format [country code][area code][subscriber number]."
   "capacity_limit", "``integer``", "The capacity limit (maximum number of simultaneous calls) for this DID."
   "channels_included_count", "``integer``", "The number of channels included with this DID."
   "dedicated_channels_count", "``integer``", "The number of channels from Capacity Pool."
   "expires_at", "``DateTime``", "DateTime when the DID expired or will expire. DateTime is in the ISO 8601 format 'yyyy-MM-dd'T'HH:mm:ss.SSS'Z', where 'SSS' are milliseconds and 'Z' denotes Zulu time (UTC)"
   "created_at", "``DateTime``", "DID created at DateTime."
   "billing_cycles_count", "``integer``", "Specifies how many renewal cycles remain before the DID expires. A value of **null** indicates unlimited automatic renewals; setting it to **0** disables auto-renewal. Each billing period decrements this count by one (max value: 999)."
   "emergency_enabled", "``boolean``", "Indicates whether the DID is assigned to an Emergency Calling Service."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "order", "to-one", ":ref:`Order Object <order_object_v34>`"
   "voice_in_trunk", "to-one", ":ref:`Inbound Trunk Object <voice_in_trunk_object_v34>`"
   "voice_in_trunk_group", "to-one", ":ref:`Inbound Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "capacity_pool", "to-one", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`"
   "shared_capacity_group", "to-one", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`"
   "did_group", "to-one", ":ref:`DID Group Object <did_group_object_v34>`"
   "address_verification", "to-one", ":ref:`Address Verifications Object <address_verifications_object_v34>`"
   "identity", "to-one", ":ref:`Identity Object <identity_object_v34>`. Represents the main identity assigned to the DID, or the porting identity as a fallback."
   "emergency_calling_service", "to-one", ":ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`. Returns the Emergency Calling Service assigned to the DID."
   "emergency_verification", "to-one", "Emergency Verification resource. Returns the Emergency Verification related to the DID."



=======
Get DID
=======

Returns a single DID owned by your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/dids/{id}``

.. note:: For all returned data attributes, see :doc:`Did Object <did-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the DID."
   "include", "``string``", "No", "Related resources to include in the response. See :ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "order", ":ref:`Order Object <order_object_v34>`"
   "voice_in_trunk", ":ref:`Trunk Object <voice_in_trunk_object_v34>`"
   "voice_in_trunk.voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "voice_in_trunk.pop", ":ref:`POP Object <pop_object_v34>`"
   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`"
   "shared_capacity_group", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`"
   "did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "identity", ":ref:`Identity Object <identity_object_v34>`"
   "emergency_calling_service", ":ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`"
   "emergency_verification", ":ref:`Emergency Verification Object <emergency_verification_object_v34>`"
   "did_group.country", ":ref:`Country Object <country_object_v34>`"
   "did_group.city", ":ref:`City Object <city_object_v34>`"
   "did_group.region", ":ref:`Region Object <region_object_v34>`"
   "did_group.did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "order", ":ref:`Order Object <order_object_v34>`"
   "voice_in_trunk", ":ref:`Trunk Object <voice_in_trunk_object_v34>`"
   "voice_in_trunk.voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "voice_in_trunk.pop", ":ref:`POP Object <pop_object_v34>`"
   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`"
   "shared_capacity_group", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`"
   "did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "identity", ":ref:`Identity Object <identity_object_v34>`"
   "emergency_calling_service", "Emergency Calling Service resource"
   "emergency_verification", "Emergency Verification resource"
   "did_group.country", ":ref:`Country Object <country_object_v34>`"
   "did_group.city", ":ref:`City Object <city_object_v34>`"
   "did_group.region", ":ref:`Region Object <region_object_v34>`"
   "did_group.did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/dids/44957076-778a-4802-b60c-d22db0cda284 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "44957076-778a-4802-b60c-d22db0cda284",
            "type": "dids",
            "attributes": {
              "blocked": false,
              "capacity_limit": 1,
              "description": "string",
              "terminated": false,
              "awaiting_registration": false,
              "number": "437xxxxxxxxx",
              "expires_at": "2017-06-25T08:21:41.795Z",
              "channels_included_count": 2,
              "created_at": "2017-06-25T08:21:41.795Z",
              "pending_removal": false,
              "dedicated_channels_count": 0,
              "emergency_enabled": false
            },
            "relationships": {
              "did_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/did_group",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/did_group"
                }
              },
              "order": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/order",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/order"
                }
              },
              "voice_in_trunk": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk"
                }
              },
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk_group"
                }
              },
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/capacity_pool"
                }
              },
              "shared_capacity_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/shared_capacity_group",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/shared_capacity_group"
                }
              },
              "address_verification": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/address_verification",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/address_verification"
                }
              },
              "emergency_calling_service": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/emergency_calling_service",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/emergency_calling_service"
                }
              },
              "emergency_verification": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/emergency_verification",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/emergency_verification"
                }
              },
              "identity": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/identity",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/identity"
                }
              }
            }
          },
          "meta": {
            "api_version": "2026-04-16"
          }
        }

   .. tab:: Request with did_group Include

    .. http:example:: curl

        GET /v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d?include=did_group HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d",
            "type": "dids",
            "attributes": {
              "blocked": false,
              "capacity_limit": 1,
              "description": "string",
              "terminated": false,
              "awaiting_registration": false,
              "number": "437xxxxxxxxx",
              "expires_at": "2017-06-25T08:21:41.795Z",
              "channels_included_count": 2,
              "created_at": "2017-06-25T08:21:41.795Z",
              "pending_removal": false,
              "dedicated_channels_count": 0,
              "emergency_enabled": false
            },
            "relationships": {
              "did_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/did_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/did_group"
                },
                "data": {
                  "type": "did_groups",
                  "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca"
                }
              },
              "order": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/order",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/order"
                }
              },
              "voice_in_trunk": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk"
                }
              },
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk_group"
                }
              },
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/capacity_pool"
                }
              },
              "shared_capacity_group": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/shared_capacity_group",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/shared_capacity_group"
                }
              },
              "address_verification": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/address_verification",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/address_verification"
                }
              },
              "emergency_calling_service": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/emergency_calling_service",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/emergency_calling_service"
                }
              },
              "emergency_verification": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/emergency_verification",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/emergency_verification"
                }
              },
              "identity": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/identity",
                  "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/identity"
                }
              }
            }
          },
          "included": [
            {
              "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca",
              "type": "did_groups",
              "links": {
                "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca"
              },
              "attributes": {
                "prefix": "721",
                "local_prefix": "",
                "features": [
                  "voice_in"
                ],
                "is_metered": false,
                "area_name": "National",
                "allow_additional_channels": true
              }
            }
          ],
          "meta": {
            "api_version": "2026-04-16"
          }
        }

   .. tab:: Request with identity Include

    .. http:example:: curl

        GET /v3/dids/44957076-778a-4802-b60c-d22db0cda284?include=identity HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "44957076-778a-4802-b60c-d22db0cda284",
            "type": "dids",
            "attributes": {
              "blocked": false,
              "capacity_limit": 1,
              "description": "string",
              "terminated": false,
              "awaiting_registration": false,
              "number": "437xxxxxxxxx",
              "expires_at": "2017-06-25T08:21:41.795Z",
              "channels_included_count": 2,
              "created_at": "2017-06-25T08:21:41.795Z",
              "pending_removal": false,
              "dedicated_channels_count": 0,
              "emergency_enabled": false
            },
            "relationships": {
              "identity": {
                "links": {
                  "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/identity",
                  "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/identity"
                },
                "data": {
                  "type": "identities",
                  "id": "9f1d6db1-2a8d-4c72-b7d6-8f3b2d7e6b41"
                }
              }
            }
          },
          "included": [
            {
              "id": "9f1d6db1-2a8d-4c72-b7d6-8f3b2d7e6b41",
              "type": "identities",
              "links": {
                "self": "https://api.didww.com/v3/identities/9f1d6db1-2a8d-4c72-b7d6-8f3b2d7e6b41"
              },
              "attributes": {
                "first_name": "John",
                "last_name": "Doe",
                "birth_date": "1985-02-10",
                "email": "john.doe@example.com"
              }
            }
          ],
          "meta": {
            "api_version": "2026-04-16"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`"



========
Get DIDs
========

Returns a list of DIDs owned by your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/dids``

.. note:: For all returned data attributes, see :doc:`Did Object <did-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]","``string``, ``boolean``","No",":ref:`Filtering <api_filters>`"
   "fields[dids]","``string``","No",":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "order", ":ref:`Order Object <order_object_v34>`"
   "voice_in_trunk", ":ref:`Trunk Object <voice_in_trunk_object_v34>`"
   "voice_in_trunk.voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "voice_in_trunk.pop", ":ref:`POP Object <pop_object_v34>`"
   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`"
   "shared_capacity_group", ":ref:`Shared Capacity Group Object <shared_capacity_group_object_v34>`"
   "did_group", ":ref:`DID Group Object <did_group_object_v34>`"
   "identity", ":ref:`Identity Object <identity_object_v34>`"
   "emergency_calling_service", ":ref:`Emergency Calling Service Object <emergency_calling_service_object_v34>`"
   "emergency_verification", ":ref:`Emergency Verification Object <emergency_verification_object_v34>`"
   "did_group.country", ":ref:`Country Object <country_object_v34>`"
   "did_group.city", ":ref:`City Object <city_object_v34>`"
   "did_group.region", ":ref:`Region Object <region_object_v34>`"
   "did_group.did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "did_group.stock_keeping_units", ":ref:`Stock Keeping Unit Object <stock_keeping_unit_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "number", "``string``", "Yes", "Yes", "The DID ``number`` field."
   "description", "``string``", "Yes", "Yes", "The ``description`` field."
   "terminated", "``boolean``", "No", "No", "The ``terminated`` field."
   "awaiting_registration", "``boolean``", "No", "No", "The ``awaiting_registration`` field."
   "pending_removal", "``boolean``", "No", "No", "The ``pending_removal`` field."
   "blocked", "``boolean``", "No", "No", "The ``blocked`` field."
   "billing_cycles_count", "``integer``", "Yes", "No", "The ``billing_cycles_count`` field."
   "did_group.id", "``string``", "Yes", "Yes", "The ID field of ``did_group`` relationship."
   "country.id", "``string``", "Yes", "Yes", "The ID field of ``country`` relationship."
   "region.id", "``string``", "Yes", "Yes", "The ID field of ``region`` relationship."
   "city.id", "``string``", "Yes", "Yes", "The ID field of ``city`` relationship."
   "order.id", "``string``", "Yes", "Yes", "The ID field of ``order`` relationship."
   "voice_in_trunk.id", "``string``", "Yes", "Yes", "The ID field of ``voice_in_trunk`` relationship."
   "voice_in_trunk_group.id", "``string``", "Yes", "Yes", "The ID field of ``voice_in_trunk_group`` relationship."
   "shared_capacity_group.id", "``string``", "Yes", "Yes", "The ID field of ``shared_capacity_group`` relationship."
   "capacity_pool.id", "``string``", "Yes", "Yes", "The ID field of ``capacity_pool`` relationship."
   "order.reference", "``string``", "No", "Yes", "The reference field of ``order`` relationship."
   "did_group.features", "``string``", "No", "Yes", "DID Group ``features`` field. Can be one or several of ``voice_in``, ``voice_out``, ``t38``, ``sms_in``, ``p2p``, ``a2p``, ``emergency``, and ``cnam_out``. Example: ``voice_in,emergency``."
   "address_verification.id", "``string``", "Yes", "Yes", "The ID field of ``address_verification`` relationship."
   "emergency_enabled", "``boolean``", "No", "No", "Filters by the ``emergency_enabled`` field. Returns DIDs that have emergency calling enabled when ``true``, or disabled when ``false``."
   "emergency_calling_service.id", "``string``", "Yes", "Yes", "The ID field of ``emergency_calling_service`` relationship."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "blocked", "Blocked status"
   "awaiting_registration", "Awaiting registration status"
   "terminated", "Termination status"
   "capacity_limit", "Capacity limit"
   "billing_cycles_count", "Billing cycles count"
   "description", "Description text"
   "number", "DID number"
   "expires_at", "Expiration timestamp"
   "channels_included_count", "Included channels count"
   "dedicated_channels_count", "Dedicated channels count"
   "created_at", "Creation timestamp"
   "emergency_enabled", "Emergency calling enabled status"

Examples
========

.. tabs::

   .. tab:: Simple Request

      .. http:example:: curl

         GET /v3/dids HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

           {
             "data": [
               {
                 "id": "ac40fb08-ac14-4a6c-8f20-fe650870c266",
                 "type": "dids",
                 "attributes": {
                   "blocked": false,
                   "capacity_limit": 1,
                   "description": "string",
                   "terminated": false,
                   "awaiting_registration": false,
                   "number": "437xxxxxxxxx",
                   "expires_at": "2017-06-25T08:21:41.795Z",
                   "channels_included_count": 2,
                   "created_at": "2017-06-25T08:21:41.795Z",
                   "pending_removal": false,
                   "dedicated_channels_count": 0,
                   "emergency_enabled": false
                 },
                 "relationships": {
                   "did_group": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/did_group",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/did_group"
                     }
                   },
                   "order": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/order",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/order"
                     }
                   },
                   "voice_in_trunk": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk"
                     }
                   },
                   "voice_in_trunk_group": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk_group",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk_group"
                     }
                   },
                   "capacity_pool": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/capacity_pool",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/capacity_pool"
                     }
                   },
                   "shared_capacity_group": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/shared_capacity_group",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/shared_capacity_group"
                     }
                   },
                   "address_verification": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/address_verification",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/address_verification"
                     }
                   },
                   "emergency_calling_service": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/emergency_calling_service",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/emergency_calling_service"
                     }
                   },
                   "emergency_verification": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/emergency_verification",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/emergency_verification"
                     }
                   },
                   "identity": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/identity",
                       "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/identity"
                     }
                   }
                 }
               },
               {
                 "id": "b37f0fcf-24d0-4799-8e81-a69bcc889f2e",
                 "type": "dids",
                 "attributes": {
                   "blocked": false,
                   "capacity_limit": 1,
                   "description": "string",
                   "terminated": false,
                   "awaiting_registration": false,
                   "number": "437xxxxxxxxx",
                   "expires_at": "2017-06-25T08:21:41.795Z",
                   "channels_included_count": 2,
                   "created_at": "2017-06-25T08:21:41.795Z",
                   "pending_removal": false,
                   "dedicated_channels_count": 0,
                   "emergency_enabled": false
                 },
                 "relationships": {
                   "did_group": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/did_group",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/did_group"
                     }
                   },
                   "order": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/order",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/order"
                     }
                   },
                   "voice_in_trunk": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/voice_in_trunk",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/voice_in_trunk"
                     }
                   },
                   "voice_in_trunk_group": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/voice_in_trunk_group",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/voice_in_trunk_group"
                     }
                   },
                   "capacity_pool": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/capacity_pool",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/capacity_pool"
                     }
                   },
                   "shared_capacity_group": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/shared_capacity_group",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/shared_capacity_group"
                     }
                   },
                   "address_verification": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/address_verification",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/address_verification"
                     }
                   },
                   "emergency_calling_service": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/emergency_calling_service",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/emergency_calling_service"
                     }
                   },
                   "emergency_verification": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/emergency_verification",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/emergency_verification"
                     }
                   },
                   "identity": {
                     "links": {
                       "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/identity",
                       "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/identity"
                     }
                   }
                 }
               }
             ],
             "meta": {
               "total_records": 2,
               "api_version": "2026-04-16"
             },
             "links": {
               "first": "https://api.didww.com/v3/dids?page%5Bnumber%5D=1&page%5Bsize%5D=50",
               "last": "https://api.didww.com/v3/dids?page%5Bnumber%5D=1&page%5Bsize%5D=50"
             }
           }

   .. tab:: Request with did_group Include

      .. http:example:: curl

         GET /v3/dids?include=did_group HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d",
               "type": "dids",
               "attributes": {
                 "blocked": false,
                 "capacity_limit": 1,
                 "description": "string",
                 "terminated": false,
                 "awaiting_registration": false,
                 "number": "437xxxxxxxxx",
                 "expires_at": "2017-06-25T08:21:41.795Z",
                 "channels_included_count": 2,
                 "created_at": "2017-06-25T08:21:41.795Z",
                 "pending_removal": false,
                 "dedicated_channels_count": 0,
                 "emergency_enabled": false
               },
               "relationships": {
                 "did_group": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/did_group",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/did_group"
                   },
                   "data": {
                     "type": "did_groups",
                     "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca"
                   }
                 },
                 "order": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/order",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/order"
                   }
                 },
                 "voice_in_trunk": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk"
                   }
                 },
                 "voice_in_trunk_group": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/voice_in_trunk_group",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/voice_in_trunk_group"
                   }
                 },
                 "capacity_pool": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/capacity_pool",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/capacity_pool"
                   }
                 },
                 "shared_capacity_group": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/shared_capacity_group",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/shared_capacity_group"
                   }
                 },
                 "address_verification": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/address_verification",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/address_verification"
                   }
                 },
                 "emergency_calling_service": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/emergency_calling_service",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/emergency_calling_service"
                   }
                 },
                 "emergency_verification": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/emergency_verification",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/emergency_verification"
                   }
                 },
                 "identity": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/relationships/identity",
                     "related": "https://api.didww.com/v3/dids/2b1f91d7-8f7a-4933-b1e4-43bbe6aff89d/identity"
                   }
                 }
               }
             }
           ],
           "included": [
             {
               "id": "d04b6466-3d98-4be1-aac5-93ee241f57ca",
               "type": "did_groups",
               "links": {
                 "self": "https://api.didww.com/v3/did_groups/d04b6466-3d98-4be1-aac5-93ee241f57ca"
               },
               "attributes": {
                 "prefix": "721",
                 "local_prefix": "",
                 "features": [
                   "voice_in"
                 ],
                 "is_metered": false,
                 "area_name": "National",
                 "allow_additional_channels": true
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/dids?include=did_group&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/dids?include=did_group&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab:: Request with emergency_calling_service Include

      .. http:example:: curl

         GET /v3/dids?include=emergency_calling_service HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "ac40fb08-ac14-4a6c-8f20-fe650870c266",
               "type": "dids",
               "attributes": {
                 "blocked": false,
                 "capacity_limit": 1,
                 "description": "string",
                 "terminated": false,
                 "awaiting_registration": false,
                 "number": "437xxxxxxxxx",
                 "expires_at": "2017-06-25T08:21:41.795Z",
                 "channels_included_count": 2,
                 "created_at": "2017-06-25T08:21:41.795Z",
                 "pending_removal": false,
                 "dedicated_channels_count": 0,
                 "emergency_enabled": true
               },
               "relationships": {
                 "did_group": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/did_group",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/did_group"
                   }
                 },
                 "order": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/order",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/order"
                   }
                 },
                 "voice_in_trunk": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk"
                   }
                 },
                 "voice_in_trunk_group": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk_group",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk_group"
                   }
                 },
                 "capacity_pool": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/capacity_pool",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/capacity_pool"
                   }
                 },
                 "shared_capacity_group": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/shared_capacity_group",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/shared_capacity_group"
                   }
                 },
                 "address_verification": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/address_verification",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/address_verification"
                   }
                 },
                 "emergency_calling_service": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/emergency_calling_service",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/emergency_calling_service"
                   },
                   "data": {
                     "type": "emergency_calling_services",
                     "id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
                   }
                 },
                 "emergency_verification": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/emergency_verification",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/emergency_verification"
                   }
                 },
                 "identity": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/identity",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/identity"
                   }
                 }
               }
             }
           ],
           "included": [
             {
               "id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
               "type": "emergency_calling_services",
               "links": {
                 "self": "https://api.didww.com/v3/emergency_calling_services/7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/dids?include=emergency_calling_service&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/dids?include=emergency_calling_service&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab:: Request with identity Include

      .. http:example:: curl

         GET /v3/dids?include=identity HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "ac40fb08-ac14-4a6c-8f20-fe650870c266",
               "type": "dids",
               "attributes": {
                 "blocked": false,
                 "capacity_limit": 1,
                 "description": "string",
                 "terminated": false,
                 "awaiting_registration": false,
                 "number": "437xxxxxxxxx",
                 "expires_at": "2017-06-25T08:21:41.795Z",
                 "channels_included_count": 2,
                 "created_at": "2017-06-25T08:21:41.795Z",
                 "pending_removal": false,
                 "dedicated_channels_count": 0,
                 "emergency_enabled": false
               },
               "relationships": {
                 "identity": {
                   "links": {
                     "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/identity",
                     "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/identity"
                   },
                   "data": {
                     "type": "identities",
                     "id": "9f1d6db1-2a8d-4c72-b7d6-8f3b2d7e6b41"
                   }
                 }
               }
             }
           ],
           "included": [
             {
               "id": "9f1d6db1-2a8d-4c72-b7d6-8f3b2d7e6b41",
               "type": "identities",
               "links": {
                 "self": "https://api.didww.com/v3/identities/9f1d6db1-2a8d-4c72-b7d6-8f3b2d7e6b41"
               },
               "attributes": {
                 "first_name": "John",
                 "last_name": "Doe",
                 "birth_date": "1985-02-10",
                 "email": "john.doe@example.com"
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/dids?include=identity&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/dids?include=identity&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

.. _dids_v34:

===
DID
===

Returns a single or a list of DID Numbers owned by the account. Allows modifying the settings of a single DID. 

Supported methods: ``GET``, ``PATCH``.

.. toctree::
  :maxdepth: 1
  
  get-did.rst
  get-dids.rst
  update-did.rst
  did-object.rst
  
  
  


.. |br| raw:: html

   <br />

==========
Update DID
==========

Update the settings of a single DID owned by your account. Using this endpoint you can cancel, restore or renew DID. 

To cancel a DID, attribute ``terminated`` must be ``true``, to renew or restore DID attribute ``terminated`` must be ``false``.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/dids/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id","``string``", "Yes", "Unique ID number allocated to this DID"
   "include","``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Name","Description"

   "voice_in_trunk",":ref:`Trunk Object <voice_in_trunk_object_v34>`"

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "terminated", "``boolean``", "Optional", "If set to ``true``, it will cancel a DID number. To renew or restore a DID number, the attribute must be set to ``false``."
   "description", "``string``", "Optional", "A DID number description."
   "billing_cycles_count", "``integer``", "Optional", "The number of Billing Cycles that this DID Number will renew until expiration. |br|  If set to ``0``, then DID will not be renewed. |br|  If set to ``null``, then DID will be renewed infinitely. |br|  After each renew value will be decreased by 1 if it is set. |br|  Maximum value of ``billing_cycles_count`` is 999."
   "dedicated_channels_count", "``integer``", "Optional", "Amount of dedicated channels to assign."
   "capacity_limit", "``integer``", "Optional", "Limits incoming capacity per DID number according to entered value. If set as ``null``, assigned capacity is not limited."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch
   
     .. http:example:: curl

			PATCH /v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
			{
			  "data": {
			    "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
			    "type": "dids",
			    "attributes": {
			      "terminated": false,
			      "description": "string",
			      "capacity_limit": 1
			    }
			  }
			}       
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			  "data": {
			    "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": 1,
			      "description": "string",
			      "terminated": false,
			      "awaiting_registration": false,
			      "number": "437xxxxxxxxx",
			      "expires_at": "2017-06-25T08:21:41.795Z",
			      "channels_included_count": 2,
			      "created_at": "2017-06-25T08:21:41.795Z",
			      "dedicated_channels_count": 0
			    }
			  },
			  "relationships": {
			    "did_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/did_group",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/did_group"
			      }
			    },
			    "order": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/order",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/order"
			      }
			    },
			    "voice_in_trunk": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/voice_in_trunk",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/voice_in_trunk"
			      }
			    },
			    "voice_in_trunk_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/voice_in_trunk_group",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/voice_in_trunk_group"
			      }
			    },
			    "capacity_pool": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/capacity_pool",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/capacity_pool"
			      }
			    },
			    "shared_capacity_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/shared_capacity_group",
			        "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/shared_capacity_group"
			      }
			    }
			  }
			}
        

   .. tab:: Assign Voice IN Trunk
   
    .. http:example:: curl

			PATCH /v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
			
			{
			  "data": {
			    "id": "3505b18a-3019-47bc-95d1-0f9ec7766fd5",
			    "type": "dids",
			    "relationships": {
			      "voice_in_trunk": {
			        "data": {
			          "type": "voice_in_trunks",
			          "id": "c80d096a-c8cf-4449-aa6d-8bac39130fe0"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "3505b18a-3019-47bc-95d1-0f9ec7766fd5",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": 1,
			      "description": "string",
			      "terminated": false,
			      "awaiting_registration": false,
			      "number": "437xxxxxxxxx",
			      "expires_at": "2017-06-25T08:21:41.795Z",
			      "channels_included_count": 2,
			      "created_at": "2017-06-25T08:21:41.795Z",
			      "dedicated_channels_count": 0
			    },
			    "relationships": {
			      "did_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/did_group",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/did_group"
			        }
			      },
			      "order": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/order",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/order"
			        }
			      },
			      "voice_in_trunk": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/voice_in_trunk",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/voice_in_trunk"
			        }
			      },
			      "voice_in_trunk_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/voice_in_trunk_group",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/voice_in_trunk_group"
			        }
			      },
			      "capacity_pool": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/capacity_pool",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/capacity_pool"
			        }
			      },
			      "shared_capacity_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/relationships/shared_capacity_group",
			          "related": "https://api.didww.com/v3/dids/3505b18a-3019-47bc-95d1-0f9ec7766fd5/shared_capacity_group"
			        }
			      }
			    }
			  }
			}
	
			
   .. tab:: Assign Voice IN Trunk Group
   
    .. http:example:: curl

			PATCH /v3/dids/3e3f57ec-0541-473a-af63-103216d19db3 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "id": "3e3f57ec-0541-473a-af63-103216d19db3",
			    "type": "dids",
			    "relationships": {
			      "voice_in_trunk_group": {
			        "data": {
			          "type": "voice_in_trunk_groups",
			          "id": "1dc6e448-d9d8-4da8-a34b-21459b03112f"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "3e3f57ec-0541-473a-af63-103216d19db3",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": 1,
			      "description": "string",
			      "terminated": false,
			      "awaiting_registration": false,
			      "number": "437xxxxxxxxx",
			      "expires_at": "2017-06-25T08:21:41.795Z",
			      "channels_included_count": 2,
			      "created_at": "2017-06-25T08:21:41.795Z",
			      "dedicated_channels_count": 0
			    }
			  },
			  "relationships": {
			    "did_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/did_group",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/did_group"
			      }
			    },
			    "order": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/order",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/order"
			      }
			    },
			    "voice_in_trunk": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/voice_in_trunk",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/voice_in_trunk"
			      }
			    },
			    "voice_in_trunk_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/voice_in_trunk_group",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/voice_in_trunk_group"
			      }
			    },
			    "capacity_pool": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/capacity_pool",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/capacity_pool"
			      }
			    },
			    "shared_capacity_group": {
			      "links": {
			        "self": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/relationships/shared_capacity_group",
			        "related": "https://api.didww.com/v3/dids/3e3f57ec-0541-473a-af63-103216d19db3/shared_capacity_group"
			      }
			    }
			  }
			}

   .. tab:: Assign Dedicated Capacity
   
    .. http:example:: curl

			PATCH /v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "attributes": {
			      "dedicated_channels_count": 2
			    },
			    "relationships": {
			      "capacity_pool": {
			        "data": {
			          "type": "capacity_pools",
			          "id": "1eb75a47-38b6-4ec2-8990-fe249ffd7b92"
			        }
			      }
			    }
			  }
			}			
			
			
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2019-05-21T08:25:02.223Z",
			      "number": "4474183XXXXX",
			      "expires_at": "2019-06-21T08:25:13.367Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 2
			    },
			    "relationships": {
			      "did_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/did_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/did_group"
			        }
			      },
			      "order": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/order",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/order"
			        }
			      },
			      "voice_in_trunk": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk"
			        }
			      },
			      "voice_in_trunk_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk_group"
			        }
			      },
			      "capacity_pool": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/capacity_pool",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/capacity_pool"
			        }
			      },
			      "shared_capacity_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/shared_capacity_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/shared_capacity_group"
			        }
			      }
			    }
			  }
			}
			
   .. tab:: Assign Shared Capacity
   
    .. http:example:: curl		
			
			PATCH /v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "relationships": {
			      "shared_capacity_group": {
			        "data": {
			          "type": "shared_capacity_groups",
			          "id": "8a581244-de83-4c46-ac0a-32659279169e"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
			
			{
			  "data": {
			    "id": "a8d13b71-8f0b-4393-8992-ff5e4e7521f9",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2019-05-21T08:25:02.223Z",
			      "number": "4474183XXXXX",
			      "expires_at": "2019-06-21T08:25:13.367Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 2
			    },
			    "relationships": {
			      "did_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/did_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/did_group"
			        }
			      },
			      "order": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/order",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/order"
			        }
			      },
			      "voice_in_trunk": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk"
			        }
			      },
			      "voice_in_trunk_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/voice_in_trunk_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/voice_in_trunk_group"
			        }
			      },
			      "capacity_pool": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/capacity_pool",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/capacity_pool"
			        }
			      },
			      "shared_capacity_group": {
			        "links": {
			          "self": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/relationships/shared_capacity_group",
			          "related": "https://api.didww.com/v3/dids/a8d13b71-8f0b-4393-8992-ff5e4e7521f9/shared_capacity_group"
			        }
			      }
			    }
			  }
			}

   .. tab:: Remove Trunk
   
    .. http:example:: curl	
    
			PATCH /v3/dids/1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "dids",
			    "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
			    "relationships": {
			      "voice_in_trunk": {
			        "data": null
			      }
			    }
			  }
			}
			
			
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

   .. tab:: Remove Identity

    .. http:example:: curl

			PATCH /v3/dids/1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "dids",
			    "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
			    "relationships": {
			      "address_verification": {
			        "data": null
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			  "data": {
			    "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2019-05-21T08:25:02.223Z",
			      "number": "4474183XXXXX",
			      "expires_at": "2019-06-21T08:25:13.367Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 2
			    }

   .. tab:: Unassign Emergency Calling Service

    .. http:example:: curl

			PATCH /v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "dids",
			    "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa",
			    "relationships": {
			      "emergency_calling_service": {
			        "data": null
			      }
			    }
			  }
			}

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			  "data": {
			    "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa",
			    "type": "dids",
			    "attributes": {
			      "blocked": false,
			      "capacity_limit": null,
			      "description": null,
			      "terminated": false,
			      "awaiting_registration": false,
			      "created_at": "2026-01-10T08:00:00.000Z",
			      "number": "12125550100",
			      "expires_at": "2026-07-15T00:00:00.000Z",
			      "channels_included_count": 2,
			      "dedicated_channels_count": 0
			    }
			  }
			}

    .. note::

       Unassigning a DID from its Emergency Calling Service does not cancel the
       service. A service left with no remaining DIDs is automatically canceled
       within a few hours, and DIDWW notifies the customer.

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 

   
   
   
   
   

   



.. |br| raw:: html

   <br />

===================
Inventory Resources
===================

The following requests allows you to retrieve resources and services related to your DIDWW account.

.. toctree::
   :maxdepth: 2

   balance/index
   order/index
   did/index
   did-history/index
   voice-in-trunks/index
   voice-in-trunk-groups/index
   voice-out-trunks/index
   capacity-pool/index
   shared-capacity-group/index


.. |br| raw:: html

   <br />

.. _orders_v34:

======
Orders
======

Returns a single or a list of orders placed in this account. Allows you to create a new order or delete an existing one. 

Supported methods: ``GET``, ``POST``, ``DELETE``. 

.. toctree::
  :maxdepth: 1
  
  get-order.rst
  get-orders.rst
  create-order.rst
  cancel-order.rst
  order-object.rst
  
  
  




=========
Get Order
=========

Returns a single Order.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/orders/{id}``

.. note:: For all returned data attributes, see :doc:`Order Object <order-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Order."

Examples
========

.. tabs::

   .. tab:: DID Order

    .. http:example:: curl

        GET /v3/orders/d9fb4666-cf4b-4409-8144-cb7535924db8 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "d9fb4666-cf4b-4409-8144-cb7535924db8",
                "type": "orders",
                "attributes": {
                    "amount": "6.0",
                    "status": "completed",
                    "created_at": "2023-10-26T11:06:28.989Z",
                    "description": "DID",
                    "reference": "EBX-118849",
                    "external_reference_id": null,
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "5.0",
                                "prorated_mrc": false,
                                "billed_from": "2023-10-26",
                                "billed_to": "2023-11-26",
                                "did_group_id": "2ef40a84-dfd4-45bb-8519-b4a7ebb74453"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Emergency Order

    .. http:example:: curl

        GET /v3/orders/103e98b9-509c-4dcb-8c6d-88fa491948df HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "103e98b9-509c-4dcb-8c6d-88fa491948df",
                "type": "orders",
                "attributes": {
                    "amount": "3.0",
                    "status": "completed",
                    "created_at": "2026-03-05T13:44:19.396Z",
                    "description": "Emergency",
                    "reference": "OUZ-611729",
                    "external_reference_id": null,
                    "items": [
                        {
                            "type": "emergency_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "1.5",
                                "mrc": "1.5",
                                "prorated_mrc": false,
                                "billed_from": "2026-03-05",
                                "billed_to": "2026-04-04",
                                "emergency_calling_service_id": "dba34c89-6cd5-403c-b284-f7d5ae33c5d7"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




============
Cancel Order
============

Cancels a pending order on DIDWW side. It is used to cancel an order that has not yet been completed and is in ``pending`` status. It will also remove DID numbers in this order.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/orders/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id","``string``", "Yes", "Unique ID identifier of the Order."

Example
=======

.. http:example:: curl

    DELETE /v3/orders/1b3ac4b7-315c-4416-afb8-24d8e7c4ec0c HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _orders_v34_create_order:

.. |br| raw:: html

   <br />

============
Create Order
============

Creates a new DID order to purchase phone numbers (DIDs) based on availability, reservations, or predefined stock-keeping units (SKUs). This request allows you to order specific available DIDs, reserve numbers from a particular region, or request multiple DIDs in bulk.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/orders``

.. note:: For all returned data attributes, see :doc:`Order Object <order-object>`.

Body
====

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "allow_back_ordering", "``boolean``", "No", "Specifies whether back-ordering is allowed. The default value is ``true``. If true, the system allows ordering DIDs that are not currently available. If false, only currently available DIDs can be ordered."
   "items", "``Array<CreateOrderItem>``", "Yes", "Array of items to be ordered. Each item must contain one of the valid order item attributes."
   "callback_url", "``string``", "No", "The HTTP or HTTPS endpoint to which order related events will be delivered."
   "callback_method", "``string``", "No", "The HTTP method used for order events. Supported methods: ``post``, ``get``."
   "external_reference_id", "``string``", "No", "Optional identifier for the order in the customer's external system. Maximum length is 100 characters."

.. note::
  - If ``allow_back_ordering`` is omitted, the request behaves as if ``allow_back_ordering = true``.
  - ``allow_back_ordering = true``: Proceeds with the order when items are not in stock.
  - ``allow_back_ordering = false``: Does not proceed with the order when items are not in stock.
  - Insufficient balance validation for ``POST /v3/orders`` is based on the current order amount only. Existing pending orders are not included in this validation. If the customer's available balance covers the current order amount, the order can be created successfully even when other pending orders already exist.

See :ref:`Callback details <callbacks_details_v34>` for information about **callback_url** and **callback_method**.

Order Item
----------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "type","``string``","No","Item object type: ``did_order_items`` for DIDs and ``capacity_order_items`` for Channels."
   "attributes","One of :ref:`DID Order Item Attributes <20210322_did_order_item_attributes_v34>`, |br| :ref:`Capacity Order Item Attributes <20210322_capacity_order_item_attributes_v34>`","No","Order Item Attributes object."

.. _20210322_did_order_item_attributes_v34:

.. _20210322_capacity_order_item_attributes_v34:

Order Item Attributes
---------------------

.. tabs::

   .. tab:: DID

      .. csv-table::
         :header: "Name", "Type", "Is Required?", "Description"

         "sku_id", "``string``", "Yes", "The Stock Keeping Unit (SKU) ID representing the DID product being ordered. Must be used with one of the optional parameters: ``qty``, ``available_did_id`` or ``did_reservation_id``."
         "qty", "``integer``", "Conditional", "The quantity of DIDs to be ordered. Required when ordering multiple DIDs in bulk. Not needed if ordering a specific ``available_did_id`` or ``did_reservation_id``."
         "did_reservation_id", "``string``", "No", "The ID of a previously reserved DID. Use this to complete the purchase of a reserved DID."
         "nanpa_prefix_id", "``string``", "No", "The ID representing a North American Numbering Plan (NANPA) prefix (NPA-NXX group). Used for ordering numbers from a specific region."
         "billing_cycles_count", "``integer``", "No", "The number of billing cycles for which the DID will automatically renew before expiration. Each billing cycle follows the DID service billing period. For monthly billing, ``1`` renews the DID for one month, ``12`` renews it for twelve months, and ``0`` disables automatic renewal. Allowed values: ``0`` to ``999``."
         "available_did_id", "``string``", "No", "The ID of a specific available DID to be ordered. Used when ordering a known available number."
         "prorate_days_qty", "``integer``", "No", "The number of service days to be included in the order, if prorated billing is applicable."

   .. tab:: Capacity

      .. csv-table::
         :header: "Name", "Type", "Is Required?", "Description"

         "qty", "``integer``", "No", "Quantity of DIDs."
         "capacity_pool_id", "``string``", "Yes", "Capacity Pool ID."

.. attention::
    Please note that the ``prorate_days_qty`` attribute will be ignored if prorated billing is not enabled for your DIDWW account. To enable this billing option, please contact the Sales department via email at `sales@didww.com <mailto:sales@didww.com>`_.

Examples
========

.. tabs::

   .. tab:: Simple request

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "sku_id": "a78bb6d8-b05e-4e12-afe6-ad84ac979088"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "9eeaab6c-b758-41b8-af86-8978a86603a2",
            "type": "orders",
            "attributes": {
              "reference": "FZH-374899",
              "external_reference_id": null,
              "amount": "79.2",
              "status": "pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 15,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "d01704b0-6522-47d5-8865-3398c417ed1d"
                  }
                }
              ]
            }
          }
        }

   .. tab:: allow_back_ordering = false

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 15,
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "79.2",
              "status": "pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "external_reference_id": null,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 15,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }

   .. tab:: Available DID ID

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "available_did_id": "7f44285d-20ef-4773-953f-ba012adafed3",
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "10.0",
              "status": "pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "external_reference_id": null,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }

   .. tab:: DID Reservation ID

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "did_reservation_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3",
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "10.0",
              "status": "pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "external_reference_id": null,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }
        
   .. tab:: Callback Example

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": true,
              "callback_url": "http://example.com",
              "callback_method": "get",
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "76b20d6b-f9a8-47bf-8715-bc5fbfd59f55",
                "type": "orders",
                "attributes": {
                    "amount": "0.5",
                    "status": "pending",
                    "created_at": "2021-09-06T16:54:28.659Z",
                    "description": "DID",
                    "reference": "TQR-660582",
                    "external_reference_id": null,
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "0.5",
                                "prorated_mrc": false,
                                "billed_from": null,
                                "billed_to": null,
                                "did_group_id": "fce19421-b6b4-4f31-99f4-699bc0300bbc"
                            }
                        }
                    ],
                    "callback_method": "get",
                    "callback_url": "http://example.com"
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Purchasing Capacity

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "items": [
                {
                  "type": "capacity_order_items",
                  "attributes": {
                    "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228",
                    "qty": 1
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "21.33",
              "status": "completed",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "Capacity",
              "reference": "NXH-560588",
              "external_reference_id": null,
              "items": [
                {
                  "type": "capacity_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "20.0",
                    "mrc": "1.33",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228"
                  }
                }
              ]
            }
          }
        }

   .. tab:: nanpa_prefix_id

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "nanpa_prefix_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3",
                    "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
            "type": "orders",
            "attributes": {
              "amount": "10.0",
              "status": "pending",
              "created_at": "2017-06-25T14:56:31.513Z",
              "description": "DID",
              "reference": "NXH-560588",
              "external_reference_id": null,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "qty": 1,
                    "nrc": "5.00",
                    "mrc": "5.00",
                    "prorated_mrc": true,
                    "billed_from": "2018-08-15",
                    "billed_to": "2018-09-15",
                    "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
                  }
                }
              ]
            }
          }
        }
        
   .. tab:: Available DID with prorate_days_qty

    .. http:example:: curl

        POST /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "orders",
            "attributes": {
              "allow_back_ordering": false,
              "items": [
                {
                  "type": "did_order_items",
                  "attributes": {
                    "available_did_id": "6c82282c-8193-43ca-9876-8ddef1ade253",
                    "sku_id": "644c2449-0e23-4a67-9f81-565ad5137bb6",
                    "prorate_days_qty": 10
                  }
                }
              ]
            }
          }
        }

        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json

                {
            "data": {
                "id": "3276e7e6-559a-4344-95d8-1a83657f46ba",
                "type": "orders",
                "attributes": {
                    "amount": "0.03",
                    "status": "pending",
                    "created_at": "2022-03-04T07:45:24.471Z",
                    "description": "DID",
                    "reference": "EHF-778400",
                    "external_reference_id": null,
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "0.03",
                                "prorated_mrc": true,
                                "billed_from": null,
                                "billed_to": null,
                                "did_group_id": "239e74ad-9da1-4802-90dd-e1ce148da19e"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Order Insufficient balance

      |br| When ``POST /v3/orders`` fails because the current order amount is greater than the customer's available balance, the API returns an insufficient balance error.

      The error includes ``meta.total_cost`` and ``meta.available_balance``. Both values are returned as strings.

      .. http:example:: curl

         POST /v3/orders HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "type": "orders",
             "attributes": {
               "allow_back_ordering": false,
               "items": [
                 {
                   "type": "did_order_items",
                   "attributes": {
                     "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7",
                     "qty": 1
                   }
                 }
               ]
             }
           }
         }

         HTTP/1.1 400 Bad Request
         Content-Type: application/vnd.api+json

         {
           "errors": [
             {
               "title": "Insufficient balance",
               "detail": "Insufficient balance",
               "code": "400",
               "status": "400",
               "meta": {
                 "available_balance": "1.5",
                 "total_cost": "5.67"
               }
             }
           ]
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "400","No",":ref:`Insufficient Balance Error Object <api_insufficient_balance_error_object>`"
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

==========
Get Orders
==========

Returns a collection of Orders.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/orders``

.. note:: For all returned data attributes, see :doc:`Order Object <order-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``, ``DateTime`` ", "No", ":ref:`Filtering <api_filters>`"
   "fields[orders]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Order ``id`` field."
   "status", "``Array[String]``", "Yes", "Yes", "Order ``status`` field. |br| Possible values: |br| ``pending`` |br| ``completed`` |br| ``canceled``"
   "created_at_gteq", "``DateTime``", "No", "No", "The ``created_at_gteq`` field."
   "created_at_lteq", "``DateTime``", "No", "No", "The ``created_at_lteq`` field."
   "reference", "``Array[String]``", "No", "Yes", "Order ``reference`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "status", "The ``status`` field. |br| Possible values: |br| ``pending`` |br| ``completed`` |br| ``canceled``"
   "amount", "The ``amount`` field."
   "created_at", "The ``created_at`` field."
   "description", "The ``description`` field."

Examples
========

.. tabs::

   .. tab:: DID Order Items

    .. http:example:: curl

        GET /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "d9fb4666-cf4b-4409-8144-cb7535924db8",
                    "type": "orders",
                    "attributes": {
                        "amount": "6.0",
                        "status": "completed",
                        "created_at": "2023-10-26T11:06:28.989Z",
                        "description": "DID",
                        "reference": "EBX-118849",
                        "external_reference_id": null,
                        "items": [
                            {
                                "type": "did_order_items",
                                "attributes": {
                                    "qty": 1,
                                    "nrc": "0.0",
                                    "mrc": "5.0",
                                    "prorated_mrc": false,
                                    "billed_from": "2023-10-26",
                                    "billed_to": "2023-11-26",
                                    "did_group_id": "2ef40a84-dfd4-45bb-8519-b4a7ebb74453"
                                }
                            }
                        ],
                        "callback_method": null,
                        "callback_url": null
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/orders?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/orders?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Emergency Order Items

    .. http:example:: curl

        GET /v3/orders HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "103e98b9-509c-4dcb-8c6d-88fa491948df",
                    "type": "orders",
                    "attributes": {
                        "amount": "3.0",
                        "status": "completed",
                        "created_at": "2026-03-05T13:44:19.396Z",
                        "description": "Emergency",
                        "reference": "OUZ-611729",
                        "external_reference_id": null,
                        "items": [
                            {
                                "type": "emergency_order_items",
                                "attributes": {
                                    "qty": 1,
                                    "nrc": "1.5",
                                    "mrc": "1.5",
                                    "prorated_mrc": false,
                                    "billed_from": "2026-03-05",
                                    "billed_to": "2026-04-04",
                                    "emergency_calling_service_id": "dba34c89-6cd5-403c-b284-f7d5ae33c5d7"
                                }
                            }
                        ],
                        "callback_method": null,
                        "callback_url": null
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/orders?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/orders?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _order_object_v34:

============
Order Object
============

Order Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "reference", "``string``", "Order Reference number."
   "amount", "``string``", "Total order amount."
   "status", "``enum``", "Status of the Order. |br| Possible values: |br| ``pending`` |br| ``completed`` |br| ``canceled``"
   "description", "``string``", "Description of the Order."
   "external_reference_id", "``string``", "Optional identifier for the order in the customer's external system. Maximum length is 100 characters."
   "created_at", "``DateTime``", "Date and time of Order creation."
   "items", "``Array<OrderItem>``", "Ordered items array."
   "callback_url", "``string``", "The HTTP or HTTPS endpoint to where events related to order will be delivered."
   "callback_method", "``string``", "The HTTP Method used for order events. ``post`` and ``get`` are supported methods. Can be ``null`` for orders created by the Emergency Calling activation flow."

Order Item
----------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "type", "``string``", "No", "Item object type: ``did_order_items`` for DIDs, ``capacity_order_items`` for channels, or ``emergency_order_items`` for Emergency Calling charges. In earlier API versions, emergency charges may be returned as ``generic_order_items`` for backward compatibility."
   "attributes", "One of :ref:`DID Order Item Attributes <did_order_item_attributes_v34>`, |br| :ref:`Capacity Order Item Attributes <capacity_order_item_attributes_v34>`, |br| :ref:`Emergency Order Item Attributes <emergency_order_item_attributes_v34>`", "No", "Order Item Attributes object."

.. _did_order_item_attributes_v34:

.. _capacity_order_item_attributes_v34:

.. _emergency_order_item_attributes_v34:

Order Item Attributes
---------------------

.. tabs::

   .. tab:: DID

		.. csv-table::
		   :header: "Name", "Type", "Description"

		   "qty", "``integer``", "Quantity of services."
		   "nrc", "``string``", "One-time activation fee (Non Recurring Cost)."
		   "mrc", "``string``", "Ongoing monthly fees (Monthly Recurring Cost)."
		   "prorated_mrc", "``boolean``", "If true, MRC will be charged prorated amount for the services acquired in the middle of the billing cycle. |br| If false, MRC will be charged full amount for the full billing cycle."
		   "billed_from", "``date``", "Billing cycle start date."
		   "billed_to", "``date``", "Billing cycle end date."
		   "did_group_id", "``string``", "DID Group ID."

   .. tab:: Capacity

		.. csv-table::
		   :header: "Name", "Type", "Description"

		   "qty", "``integer``", "Quantity of services."
		   "nrc", "``string``", "One-time activation fee (Non Recurring Cost)."
		   "mrc", "``string``", "Ongoing monthly fees (Monthly Recurring Cost)."
		   "prorated_mrc", "``boolean``", "If true, MRC will be charged prorated amount for the services acquired in the middle of the billing cycle. |br| If false, MRC will be charged full amount for the full billing cycle."
		   "billed_from", "``date``", "Billing cycle start date."
		   "billed_to", "``date``", "Billing cycle end date."
		   "capacity_pool_id", "``string``", "Capacity Pool ID."

   .. tab:: Emergency

		.. csv-table::
		   :header: "Name", "Type", "Description"

		   "qty", "``integer``", "Quantity of services."
		   "nrc", "``string``", "One-time activation fee (Non Recurring Cost)."
		   "mrc", "``string``", "Ongoing monthly fees (Monthly Recurring Cost)."
		   "prorated_mrc", "``boolean``", "If true, MRC is charged as a prorated amount for services acquired in the middle of the billing cycle. If false, MRC is charged in full for the billing cycle."
		   "billed_from", "``date``", "Billing cycle start date."
		   "billed_to", "``date``", "Billing cycle end date."
		   "emergency_calling_service_id", "``string``", "Emergency Calling Service ID associated with the order item."


.. |br| raw:: html

   <br />

.. _voice_in_trunks_v34:

==============
Inbound Trunks
==============

Returns a list of all of the inbound trunks configured by the account. Allows create, edit or delete a trunk.

This section also includes, available POPs, Codecs and Disconnect codes supported by DIDWW. 

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  get-voice-in-trunk.rst
  get-voice-in-trunks.rst
  create-voice-in-trunk.rst
  update-voice-in-trunk.rst
  delete-voice-in-trunk.rst
  voice-in-trunk-object.rst
  get-pops.rst
  pop-object.rst
  codecs.rst
  rerouting-disconnect-codes.rst
  
  
  
  




=================
Get Inbound Trunk
=================

Returns inbound trunks owned by the account. Several type of trunks can be retrieved: SIP, PSTN.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunks/``

.. note:: For all returned data attributes, see :doc:`Inbound Trunk Object <voice-in-trunk-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."
   "sort","``string``","No",":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Name","Description"

   "voice_in_trunk_group",":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "pop",":ref:`POP Object <pop_object_v34>`"

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "pop", ":ref:`POP Object <pop_object_v34>`"

Examples
========

.. tabs::

   .. tab:: SIP Trunk

    .. http:example:: curl

        GET /v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "df78e081-b7d1-4769-80ce-f349af4f612e",
            "type": "voice_in_trunks",
            "attributes": {
              "priority": 1,
              "capacity_limit": 10,
              "weight": 2,
              "name": "Office",
              "cli_format": "e164",
              "cli_prefix": "+",
              "description": null,
              "ringing_timeout": 30,
              "created_at": "2017-06-25T08:21:41.795Z",
              "external_reference_id": null,
              "configuration": {
                "type": "sip_configurations",
                "attributes": {
                  "username": "username",
                  "host": "example.com",
                  "port": null,
                  "codec_ids": [
                    9,
                    7
                  ],
                  "rx_dtmf_format_id": 1,
                  "tx_dtmf_format_id": 1,
                  "resolve_ruri": true,
                  "auth_enabled": true,
                  "auth_user": "username",
                  "auth_password": "password",
                  "auth_from_user": "Office",
                  "auth_from_domain": "example.com",
                  "sst_enabled": false,
                  "sst_min_timer": 600,
                  "sst_max_timer": 900,
                  "sst_accept_501": true,
                  "sip_timer_b": 8000,
                  "dns_srv_failover_timer": 2000,
                  "rtp_ping": false,
                  "rtp_timeout": 30,
                  "force_symmetric_rtp": false,
                  "symmetric_rtp_ignore_rtcp": false,
                  "rerouting_disconnect_code_ids": [
                    58,
                    59,
                    1505
                  ],
                  "sst_session_expires": null,
                  "sst_refresh_method_id": 1,
                  "transport_protocol_id": 1,
                  "max_transfers": 5,
                  "max_30x_redirects": 0,
                  "media_encryption_mode": "disabled",
                  "stir_shaken_mode": "disabled",
                  "allowed_rtp_ips": null,
                  "network_protocol_priority": "any",
                  "enabled_sip_registration": true,
                  "use_did_in_ruri": true,
                  "diversion_relay_policy": "as_is",
                  "diversion_inject_mode": "did_number",
                  "cnam_lookup": true
                }
              }
            },
            "relationships": {
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/voice_in_trunk_group"
                }
              },
              "pop": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/relationships/pop",
                  "related": "https://api.didww.com/v3/voice_in_trunks/df78e081-b7d1-4769-80ce-f349af4f612e/pop"
                }
              }
            }
          },
          "meta": {
            "api_version": "2026-04-16"
          }
        }

   .. tab:: PSTN

    .. http:example:: curl

        GET /v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "84746865-b1c0-414d-86c7-62c85c22fd69",
            "type": "voice_in_trunks",
            "attributes": {
              "priority": 1,
              "capacity_limit": 5,
              "weight": 65535,
              "name": "Office Mobile",
              "cli_format": "e164",
              "cli_prefix": null,
              "description": null,
              "ringing_timeout": null,
              "created_at": "2017-06-25T08:21:41.795Z",
              "external_reference_id": null,
              "configuration": {
                "type": "pstn_configurations",
                "attributes": {
                  "dst": "1xxxxxxxxx"
                }
              }
            },
            "relationships": {
              "voice_in_trunk_group": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/relationships/voice_in_trunk_group",
                  "related": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/voice_in_trunk_group"
                }
              },
              "pop": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/relationships/pop",
                  "related": "https://api.didww.com/v3/voice_in_trunks/84746865-b1c0-414d-86c7-62c85c22fd69/pop"
                }
              }
            }
          },
          "meta": {
            "api_version": "2026-04-16"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _trunk_codecs_v34:

======
Codecs
======

.. csv-table::
   :header: "Codec ID", "Codec Name"

   "6", "telephone-event "
   "7", "G723"
   "8", "G729"
   "9", "PCMU"
   "10", "PCMA"
   "12", "speex"
   "13", "GSM"
   "14", "G726-32"
   "15", "G721"
   "16", "G726-24"
   "17", "G726-40"
   "18", "G726-16"
   "19", "L16"


.. |br| raw:: html

   <br />
   
====================
Create Inbound Trunk
====================

You can create several type of inbound trunks: SIP, PSTN.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_in_trunks``

Body Parameters
---------------

.. csv-table::
   :header: "Name", "Type","Nullable", "Is Required?", "Description"

   "type", "``string``", "No","Yes", "Trunks "
   "attributes", "``object``","No", "Yes", "Trunk configuration complex object."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "priority", "``integer``", "No", "Yes", "The priority of this target host. |br| DIDWW will attempt to contact the target trunk with the lowest-numbered priority; |br| target trunk with the same priority will be tried in an order defined by the weight field. |br| The range is 0-65535. See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "weight", "``integer``", "No", "Yes", "A trunk selection mechanism. |br| The weight field specifies a relative weight for entries with the same priority. |br| Larger weights will be given a proportionately higher probability of being selected. |br| The range of this number is 0-65535. |br| In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. |br| See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "capacity_limit", "``integer``", "No", "No", "Maximum number of simultaneous calls for the trunk."
   "ringing_timeout", "``integer``", "No", "No", "Ring time in seconds. Supported values are integers from 1 to 32. If ``null``, the timeout is undefined. |br| If the call is not connected within this time, the transaction is ended with the disconnect code **Ringing timeout**."
   "name", "``string``", "No", "Yes", "Friendly name of the trunk."
   "external_reference_id", "``string``", "Yes", "No", "Optional identifier for the inbound trunk in the customer's external system. Maximum length is 100 characters."
   "cli_format", "``string``", "No", "No", "**RAW** - Do not alter CLI (default). |br| **E164** - Attempt to convert CLI to E.164 format. |br| **Local** - Attempt to convert CLI to Localized format. |br| **CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID**."
   "cli_prefix", "``string``", "No", "No", "You may prefix the CLI with an optional ``+`` sign followed by up to 6 characters, including digits and ``#``."
   "description", "``string``", "No", "No", "Optional description of the trunk."
   "configuration", "One of :ref:`sip_configurations <trunk_attributes_v34>`, |br| :ref:`pstn_configurations <trunk_attributes_v34>`", "N/A", "Yes", "Trunk configuration complex object."

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "pop", ":ref:`POP Object <pop_object_v34>`"

.. _trunk_attributes_v34:

Attributes Configuration
------------------------

.. tabs::

   .. tab:: SIP
   
	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``sip_configurations``", "No","Yes", "SIP configuration complex object. "
	   "attributes", ":ref:`sip_configuration_attributes <trunk_attributes_v34>`","No", "Yes", "SIP configuration attributes object."
      
   .. tab:: PSTN

	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``pstn_configurations``", "No","Yes", "PSTN configuration complex object."
	   "attributes", ":ref:`pstn_configuration_attributes <trunk_attributes_v34>`","No", "Yes", "PSTN configuration attributes object."

Configuration Attributes
------------------------

.. tabs::

   .. tab:: SIP

	.. csv-table::
	   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

	   "username", "``string``", "No", "Yes", "User part of R-URI in INVITE request. |br| You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. |br| For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format"
	   "host", "``string``", "No", "Yes", "Host part of R-URI in INVITE request."
	   "port", "``integer``", "No", "No", "Port part of R-URI in INVITE request (is not mandatory). |br| If port is null, SRV record will be resolved (or A record if SRV is unavailable)."
	   "codec_ids", "``array``", "No", "No", ":ref:`Codecs <trunk_codecs_v34>`."
	   "rx_dtmf_format_id", "``integer``", "No", "No", "The method id for receiving DTMF signals from customers equipment. |br| Possible values: |br| 1 - RFC 2833 |br| 2 - SIP INFO application/dtmf-relay OR application/dtmf |br| 3 - RFC 2833 OR SIP INFO"
	   "tx_dtmf_format_id", "``integer``", "No", "No", "The method of sending DTMF signals to customers equipment. |br| Possible values: |br| 1 - Disable sending |br| 2 - RFC 2833 |br| 3 - SIP INFO application/dtmf-relay |br| 4 - SIP INFO application/dtmf"
	   "resolve_ruri", "``boolean``", "No", "No", "Replace host part of the R-URI by resolved IP address."
	   "auth_enabled", "``boolean``", "No", "No", "Enable authorization for the SIP server."
	   "auth_user", "``string``", "No", "No", "Optional authorization user for the SIP server."
	   "auth_password", "``string``", "No", "No", "Optional authorization password for the SIP server."
	   "auth_from_user", "``string``", "No", "No", "Specify user in a **from** field instead of CallerID (overrides CallerID). |br| Some equipment require **from**; to be equivalent to **Auth user**."
	   "auth_from_domain", "``string``", "No", "No", "Sets default **from** domain in SIP messages. Some equipment may require specific **From** Domain."
	   "sst_enabled", "``boolean``", "No", "No", "Enable SIP Session timers customization. |br| SIP session timers are used to make sure that a session (dialog) is still alive, |br| even though there may have been a long time since the last in-dialog message. |br| If the other end is not responding, the dialog will be hung up automatically. |br| SIP session timers need to be supported by all end points for it to work. |br| It’s a SIP extension, standardized by the IETF. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_min_timer", "``integer``", "No", "No", "Minimal SIP Session timer value (Default 600 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_max_timer", "``integer``", "No", "No", "Maximal SIP Session timer value (Default 900 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_accept_501", "``boolean``", "No", "No", "Do not drop the call after receiving SIP 501 response for non-critical messages."
	   "sip_timer_b", "``integer``", "No", "No", "INVITE transaction timeout (Default 8000ms). |br| See `RFC 3261 Section 17.1.1.2 <https://tools.ietf.org/html/rfc3261#section-17.1.1.2>`_ for more details."
	   "dns_srv_failover_timer", "``integer``", "No", "No", "Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms)."
	   "rtp_ping", "``boolean``", "No", "No", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."
	   "rtp_timeout", "``integer``", "No", "No", "Disconnect the call if the RTP packets do not arrive within the specified time."
	   "force_symmetric_rtp", "``boolean``", "No", "No", "Forced to work in Symmetric RTP / COMEDIA mode."
	   "symmetric_rtp_ignore_rtcp", "``boolean``", "No", "No", "Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. |br| Only RTP packets will be considered."
	   "rerouting_disconnect_code_ids", "``array``", "No", "No", ":ref:`Rerouting disconnect codes <disconnect_codes_v34>`."
	   "sst_session_expires", "``integer``", "No", "No", "Session-Expires header value. Optional, should be in range with **sst_min_timer** and **sst_max_timer**. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_refresh_method_id", "``integer``", "No", "No", "SIP method which will be used for session update. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details. |br| Possible values: |br| 1 - Invite |br| 2 - Update |br| 3 - Update fallback Invite"
	   "transport_protocol_id", "``integer``", "No", "No", "The transport layer that will be responsible for the actual transmission of SIP requests and responses: |br| 1 - UDP |br| 2 - TCP |br| 3 - TLS."
	   "max_transfers", "``integer``", "No", "No", "Max count of the **REFER** requests."
	   "max_30x_redirects", "``integer``", "No", "No", "Max count of 301/302 redirects."
	   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_, `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
	   "stir_shaken_mode", "``string``", "No", "No", "Stir/Shaken mode. |br| See :ref:`STIR/SHAKEN <service_did_stir_shaken>`  for more details. |br| Possible Values: |br| 'disabled' - Do not send identity |br| 'original' - Transit Identity header as is |br| 'pai' - Add PAI, P-Attestation-Indicator, P-Origination-ID |br| 'original_pai' - Transit Identity Header as is + Add PAI, P-Attestation Indicator, P-Origination-ID |br| 'verstat' - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID"
	   "allowed_rtp_ips", "Array of ``strings``", "No", "No", "The allowed RTP IPs. Array from 0 to 10 items: IPv4 or IPv6, single or subnet."
	   "network_protocol_priority", "``string``", "No", "No", "Network protocol priority for SIP routing. |br| Possible values: |br| ``force_ipv4`` - Use IPv4 exclusively. |br| ``force_ipv6`` - Use IPv6 exclusively. |br| ``any`` - Use either IPv4 or IPv6. |br| ``prefer_ipv4`` - Prefer IPv4 but fall back to IPv6. |br| ``prefer_ipv6`` - Prefer IPv6 but fall back to IPv4."
	   "enabled_sip_registration", "``boolean``", "No", "No", "Enables SIP registration for the trunk."
	   "use_did_in_ruri", "``boolean``", "No", "No", "Uses the called DID in the R-URI. This attribute works only when ``enabled_sip_registration`` is ``true``."
	   "diversion_relay_policy", "``string``", "No", "No", "Controls how Diversion information is relayed. |br| Possible values: |br| ``none`` - Do not relay the Diversion header. |br| ``as_is`` - Relay the Diversion header as received. |br| ``sip`` - Relay the Diversion header as a SIP URI. |br| ``tel`` - Relay the Diversion header as a TEL URI."
	   "diversion_inject_mode", "``string``", "No", "No", "Controls how Diversion information is injected. |br| Possible values: |br| ``none`` - Do not add a Diversion header. |br| ``did_number`` - Add a Diversion header using the DID number in E.164 format."
	   "cnam_lookup", "``boolean``", "No", "No", "Enables inbound CNAM lookup."

   .. tab:: PSTN
	
	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "dst", "``string``", "No","Yes", "Phone number's."

Examples
========

.. tabs::

    .. tab:: SIP
   
        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
        
            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": "1",
                  "weight": "2",
                  "capacity_limit": 10,
                  "ringing_timeout": 30,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": "true",
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": "false",
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": "true",
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": "false",
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": "false",
                      "symmetric_rtp_ignore_rtcp": "false",
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null,
                      "network_protocol_priority": "prefer_ipv4",
                      "diversion_relay_policy": "sip",
                      "diversion_inject_mode": "did_number",
                      "cnam_lookup": true
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "f36d1d17-bd16-42b9-af42-0cfe166bf3ec",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null,
                      "network_protocol_priority": "prefer_ipv4",
                      "diversion_relay_policy": "sip",
                      "diversion_inject_mode": "did_number",
                      "cnam_lookup": true
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/f36d1d17-bd16-42b9-af42-0cfe166bf3ec/pop"
                    }
                  }
                }
            }
            }
      
    .. tab:: SIP with registration

        When ``enabled_sip_registration`` is ``true``, do not send ``host`` or ``port`` in the create request.

        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": "1",
                  "weight": "2",
                  "name": "Office Registration",
                  "capacity_limit": 10,
                  "ringing_timeout": 30,
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "office-registration",
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": "false",
                      "auth_enabled": true,
                      "auth_user": "office-registration",
                      "auth_password": "password",
                      "auth_from_user": "OfficeRegistration",
                      "auth_from_domain": "example.com",
                      "sst_enabled": "false",
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": "true",
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": "false",
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": "false",
                      "symmetric_rtp_ignore_rtcp": "false",
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null,
                      "network_protocol_priority": "prefer_ipv4",
                      "enabled_sip_registration": true,
                      "use_did_in_ruri": true,
                      "diversion_relay_policy": "sip",
                      "diversion_inject_mode": "did_number",
                      "cnam_lookup": true
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "5b59c2b0-2a3b-4a17-b8f9-d4df5e8ad2b1",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office Registration",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2026-04-27T09:15:00.000Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "office-registration",
                      "host": null,
                      "port": null,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": false,
                      "auth_enabled": true,
                      "auth_user": "office-registration",
                      "auth_password": "password",
                      "auth_from_user": "OfficeRegistration",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null,
                      "network_protocol_priority": "prefer_ipv4",
                      "enabled_sip_registration": true,
                      "use_did_in_ruri": true,
                      "diversion_relay_policy": "sip",
                      "diversion_inject_mode": "did_number",
                      "cnam_lookup": true
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/5b59c2b0-2a3b-4a17-b8f9-d4df5e8ad2b1/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/5b59c2b0-2a3b-4a17-b8f9-d4df5e8ad2b1/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/5b59c2b0-2a3b-4a17-b8f9-d4df5e8ad2b1/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/5b59c2b0-2a3b-4a17-b8f9-d4df5e8ad2b1/pop"
                    }
                  }
                }
              }
            }

            
    .. tab:: PSTN
   
        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
            
            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "name": "Office Mobile",
                  "capacity_limit": 5,
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "1xxxxxxxxx"
                    }
                  }
                }
              }
            }
            
            
            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "28b360b9-0d35-4c94-bbfd-1c33a7680b34",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 5,
                  "weight": 65535,
                  "name": "Office Mobile",
                  "cli_format": "e164",
                  "cli_prefix": null,
                  "description": null,
                  "ringing_timeout": null,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "1xxxxxxxxx"
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/28b360b9-0d35-4c94-bbfd-1c33a7680b34/pop"
                    }
                  }
                }
              }
            }

    .. tab:: SIP with POP
   
        .. http:example:: curl

            POST /v3/voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]             
            
            {
              "data": {
                "type": "voice_in_trunks",
                "attributes": {
                  "name": "Office SIP",
                  "capacity_limit": 18,
                  "cli_format": "e164",
                  "cli_prefix": "+1",
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": "true",
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": "false",
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_refresh_method_id": 1,
                      "sst_accept_501": "true",
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": "false",
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": "false",
                      "symmetric_rtp_ignore_rtcp": "false",
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "port": 5060,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "pop": {
                    "data": {
                      "type": "pops",
                      "id": "240416e4-aeb2-4ca5-9df2-f37f01e930cf"
                    }
                  }
                }
              }
            }      
            
            
            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "7adfab4e-83bc-45e2-84e6-60342a505713",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 18,
                  "weight": 65535,
                  "name": "Office SIP",
                  "cli_format": "e164",
                  "cli_prefix": "+1",
                  "description": null,
                  "ringing_timeout": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/389deacb-5be5-46d7-8cbd-aba11f66d6c2/pop"
                    },
                    "data": {
                      "type": "pops",
                      "id": "240416e4-aeb2-4ca5-9df2-f37f01e930cf"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "240416e4-aeb2-4ca5-9df2-f37f01e930cf",
                  "type": "pops",
                  "links": {
                    "self": "https://api.didww.com/v3/pops/240416e4-aeb2-4ca5-9df2-f37f01e930cf"
                  },
                  "attributes": {
                    "name": "USA, NY"
                  }
                }
              ]
            }    
            
            
Other Responses
===============
            
.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



====================
Delete Inbound Trunk
====================

Deletes the inbound trunk.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/voice_in_trunks/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."

Example
=======

.. http:example:: curl

    DELETE /v3/voice_in_trunks/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    




========
Get POPs
========

Returns a list of PoPs (Points of Presence). Each PoP has a unique identification number. Pagination is disabled.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/pops``

.. note:: For all returned data attributes, see :doc:`Pop Object <pop-object>`.

Example
=======

.. http:example:: curl

    GET /v3/pops HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    
    {
      "data": [
        {
          "id": "f5ffe21a-7b8f-4404-928f-88522d9bf153",
          "type": "pops",
          "attributes": {
            "name": "USA, NY"
          }
        },
        {
          "id": "c4c214f5-5f70-4f8d-8ebe-2aa203bfdd0b",
          "type": "pops",
          "attributes": {
            "name": "DE, FRA"
          }
        }
      ],
      "meta": {
        "total_records": 2
      },
      "links": {
        "first": "https://api.didww.com/v3/pops?&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
        "next": "https://api.didww.com/v3/pops?&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
      }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 



.. |br| raw:: html

   <br />

==================
Get Inbound Trunks
==================

Returns the collection of inbound Trunks.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunks``

.. note:: For all returned data attributes, see :doc:`Inbound Trunk Object <voice-in-trunk-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]","``string``, ``DateTime`` ", "No", ":ref:`Filtering <api_filters>`"
   "fields[voice_in_trunks]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``", "No", ":ref:`Sorting <api_sorting>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Trunk ``id`` field. "
   "name", "``string``", "Yes", "Yes", "Trunk ``name`` field.  "
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."
   "configuration.type", "``string``", "Yes", "Yes", "The type of configuration (SIP, PSTN, etc)"

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "The ``name`` field."
   "priority", "The ``priority`` field."
   "capacity_limit", "The ``capacity_limit`` field."
   "weight", "The ``weight`` field."
   "cli_format", "The ``cli_format`` field."
   "cli_prefix", "The ``cli_prefix`` field."
   "description", "The ``description`` field."
   "ringing_timeout", "The ``ringing_timeout`` field."
   "created_at", "The ``created_at`` field."

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "pop", ":ref:`POP Object <pop_object_v34>`"

Example
=======

.. http:example:: curl

        GET /v3/voice_in_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
    
    
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "2d7f943f-07c4-4b27-8792-e85806368218",
              "type": "voice_in_trunks",
              "attributes": {
                "priority": 1,
                "capacity_limit": 10,
                "weight": 2,
                "name": "Office",
                "cli_format": "e164",
                "cli_prefix": "+",
                "description": null,
                "ringing_timeout": 30,
                "created_at": "2017-06-25T08:21:41.795Z",
                "external_reference_id": null,
                "configuration": {
                  "type": "sip_configurations",
                  "attributes": {
                    "username": "username",
                    "host": "example.com",
                    "port": null,
                    "codec_ids": [
                      9,
                      7
                    ],
                    "rx_dtmf_format_id": 1,
                    "tx_dtmf_format_id": 1,
                    "resolve_ruri": true,
                    "auth_enabled": true,
                    "auth_user": "username",
                    "auth_password": "password",
                    "auth_from_user": "Office",
                    "auth_from_domain": "example.com",
                    "sst_enabled": false,
                    "sst_min_timer": 600,
                    "sst_max_timer": 900,
                    "sst_accept_501": true,
                    "sip_timer_b": 8000,
                    "dns_srv_failover_timer": 2000,
                    "rtp_ping": false,
                    "rtp_timeout": 30,
                    "force_symmetric_rtp": false,
                    "symmetric_rtp_ignore_rtcp": false,
                    "rerouting_disconnect_code_ids": [
                      58,
                      59,
                      1505
                    ],
                    "sst_session_expires": null,
                    "sst_refresh_method_id": 1,
                    "transport_protocol_id": 1,
                    "max_transfers": 5,
                    "max_30x_redirects": 7,
                    "media_encryption_mode": "disabled",
                    "stir_shaken_mode": "disabled",
                    "allowed_rtp_ips": null,
                    "network_protocol_priority": "any",
                    "enabled_sip_registration": true,
                    "use_did_in_ruri": true,
                    "diversion_relay_policy": "as_is",
                    "diversion_inject_mode": "did_number",
                    "cnam_lookup": true
                  }
                }
              },
              "relationships": {
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunks/2d7f943f-07c4-4b27-8792-e85806368218/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/voice_in_trunks/2d7f943f-07c4-4b27-8792-e85806368218/voice_in_trunk_group"
                  }
                }
              }
            },
            {
              "id": "34b95e8c-9b78-4e64-aea8-9e5764d8f16f",
              "type": "voice_in_trunks",
              "attributes": {
                "priority": 1,
                "capacity_limit": 5,
                "weight": 65535,
                "name": "Office Mobile",
                "cli_format": "e164",
                "cli_prefix": null,
                "description": null,
                "ringing_timeout": null,
                "created_at": "2017-06-25T08:21:41.795Z",
                "external_reference_id": null,
                "configuration": {
                  "type": "pstn_configurations",
                  "attributes": {
                    "dst": "1xxxxxxxxx"
                  }
                }
              },
              "relationships": {
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunks/34b95e8c-9b78-4e64-aea8-9e5764d8f16f/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/voice_in_trunks/34b95e8c-9b78-4e64-aea8-9e5764d8f16f/voice_in_trunk_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/voice_in_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/voice_in_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }


.. _pop_object_v34:

==========
POP Object
==========

POP Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "POP name "



.. _disconnect_codes_v34:

==========================
Rerouting Disconnect Codes
==========================

.. csv-table::
   :header: "ID", "Code", "Description"

   "56", "400", "Bad Request"
   "57", "401", "Unauthorized"
   "58", "402", "Payment Required"
   "59", "403", "Forbidden"
   "60", "404", "Not Found"
   "64", "408", "Request Timeout"
   "65", "409", "Conflict"
   "66", "410", "Gone"
   "67", "412", "Conditional Request Failed"
   "68", "413", "Request Entity Too Large"
   "69", "414", "Request-URI Too Long"
   "70", "415", "Unsupported Media Type"
   "71", "416", "Unsupported URI Scheme"
   "72", "417", "Unknown Resource-Priority"
   "73", "420", "Bad Extension"
   "74", "421", "Extension Required"
   "75", "422", "Session Interval Too Small"
   "76", "423", "Interval Too Brief"
   "77", "424", "Bad Location Information"
   "78", "428", "Use Identity Header"
   "79", "429", "Provide Referrer Identity"
   "80", "433", "Anonymity Disallowed"
   "81", "436", "Bad Identity-Info"
   "82", "437", "Unsupported Certificate"
   "83", "438", "Invalid Identity Header"
   "84", "480", "Temporarily Unavailable"
   "86", "482", "Loop Detected"
   "87", "483", "Too Many Hops"
   "88", "484", "Address Incomplete"
   "89", "485", "Ambiguous"
   "90", "486", "Busy Here"
   "91", "487", "Request Terminated"
   "92", "488", "Not Acceptable Here"
   "96", "494", "Security Agreement Required"
   "97", "500", "Server Internal Error"
   "98", "501", "Not Implemented"
   "99", "502", "Bad Gateway"
   "100", "503", "Service Unavailable"
   "101", "504", "Server Time-out"
   "102", "505", "Version Not Supported"
   "103", "513", "Message Too Large"
   "104", "580", "Precondition Failure"
   "105", "600", "Busy Everywhere"
   "106", "603", "Decline"
   "107", "604", "Does Not Exist Anywhere"
   "108", "606", "Not Acceptable"
   "1505", "", "Ringing timeout"


.. |br| raw:: html

   <br />

====================
Update Inbound Trunk
====================

Updates an inbound trunk.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/voice_in_trunks/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``","Yes", "Unique ID identifier of Trunk. "

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "priority", "``integer``", "No", "Yes", "The priority of this target host. |br| DIDWW will attempt to contact the target trunk with the lowest-numbered priority; |br| target trunk with the same priority will be tried in an order defined by the weight field. |br| The range is 0-65535. See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "weight", "``integer``", "No", "Yes", "A trunk selection mechanism. |br| The weight field specifies a relative weight for entries with the same priority. |br| Larger weights will be given a proportionately higher probability of being selected. |br| The range of this number is 0-65535. |br| In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. |br| See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "capacity_limit", "``integer``", "No", "No", "Maximum number of simultaneous calls for the trunk."
   "ringing_timeout", "``integer``", "No", "No", "Ring time in seconds. Supported values are integers from 1 to 32. If ``null``, the timeout is undefined. |br| If the call is not connected within this time, the transaction is ended with the disconnect code **Ringing timeout**."
   "name", "``string``", "No", "Yes", "Friendly name of the trunk."
   "external_reference_id", "``string``", "Yes", "No", "Optional identifier for the inbound trunk in the customer's external system. Maximum length is 100 characters."
   "cli_format", "``string``", "No", "No", "**RAW** - Do not alter CLI (default). |br| **E164** - Attempt to convert CLI to E.164 format. |br| **Local** - Attempt to convert CLI to Localized format. |br| **CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID**."
   "cli_prefix", "``string``", "No", "No", "You may prefix the CLI with an optional ``+`` sign followed by up to 6 characters, including digits and ``#``."
   "description", "``string``", "No", "No", "Optional description of the trunk."
   "configuration", "One of :ref:`sip_configurations <trunk_attributes_v34>`, |br| :ref:`pstn_configurations <trunk_attributes_v34>`", "N/A", "Yes", "Trunk configuration complex object."

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunk_group", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "pop", ":ref:`POP Object <pop_object_v34>`"

.. _trunk_attrs_updt_v34:

Attributes Configuration
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``sip_configurations``", "No","Yes", "SIP configuration complex object. "
	   "attributes", ":ref:`sip_configuration_attributes <trunk_attributes_v34>`","No", "Yes", "SIP configuration attributes object."
    
   .. tab:: PSTN

	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``pstn_configurations``", "No","Yes", "PSTN configuration complex object."
	   "attributes", ":ref:`pstn_configuration_attributes <trunk_attributes_v34>`","No", "Yes", "PSTN configuration attributes object."

Configuration Attributes
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

	   "username", "``string``", "No", "Yes", "User part of R-URI in INVITE request. |br| You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. |br| For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format"
	   "host", "``string``", "No", "Yes", "Host part of R-URI in INVITE request."
	   "port", "``integer``", "No", "No", "Port part of R-URI in INVITE request (is not mandatory). |br| If port is null, SRV record will be resolved (or A record if SRV is unavailable)."
	   "codec_ids", "``array``", "No", "No", ":ref:`Codecs <trunk_codecs_v34>`."
	   "rx_dtmf_format_id", "``integer``", "No", "No", "The method id for receiving DTMF signals from customers equipment. |br| Possible values: |br| 1 - RFC 2833 |br| 2 - SIP INFO application/dtmf-relay OR application/dtmf |br| 3 - RFC 2833 OR SIP INFO"
	   "tx_dtmf_format_id", "``integer``", "No", "No", "The method of sending DTMF signals to customers equipment. |br| Possible values: |br| 1 - Disable sending |br| 2 - RFC 2833 |br| 3 - SIP INFO application/dtmf-relay |br| 4 - SIP INFO application/dtmf"
	   "resolve_ruri", "``boolean``", "No", "No", "Replace host part of the R-URI by resolved IP address."
	   "auth_enabled", "``boolean``", "No", "No", "Enable authorization for the SIP server."
	   "auth_user", "``string``", "No", "No", "Optional authorization user for the SIP server."
	   "auth_password", "``string``", "No", "No", "Optional authorization password for the SIP server."
	   "auth_from_user", "``string``", "No", "No", "Specify user in a **from** field instead of CallerID (overrides CallerID). |br| Some equipment require **from**; to be equivalent to **Auth user**."
	   "auth_from_domain", "``string``", "No", "No", "Sets default **from** domain in SIP messages. Some equipment may require specific **From** Domain."
	   "sst_enabled", "``boolean``", "No", "No", "Enable SIP Session timers customization. |br| SIP session timers are used to make sure that a session (dialog) is still alive, |br| even though there may have been a long time since the last in-dialog message. |br| If the other end is not responding, the dialog will be hung up automatically. |br| SIP session timers need to be supported by all end points for it to work. |br| It’s a SIP extension, standardized by the IETF. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_min_timer", "``integer``", "No", "No", "Minimal SIP Session timer value (Default 600 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_max_timer", "``integer``", "No", "No", "Maximal SIP Session timer value (Default 900 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_accept_501", "``boolean``", "No", "No", "Do not drop the call after receiving SIP 501 response for non-critical messages."
	   "sip_timer_b", "``integer``", "No", "No", "INVITE transaction timeout (Default 8000ms). |br| See `RFC 3261 Section 17.1.1.2 <https://tools.ietf.org/html/rfc3261#section-17.1.1.2>`_ for more details."
	   "dns_srv_failover_timer", "``integer``", "No", "No", "Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms)."
	   "rtp_ping", "``boolean``", "No", "No", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."
	   "rtp_timeout", "``integer``", "No", "No", "Disconnect the call if the RTP packets do not arrive within the specified time."
	   "force_symmetric_rtp", "``boolean``", "No", "No", "Forced to work in Symmetric RTP / COMEDIA mode."
	   "symmetric_rtp_ignore_rtcp", "``boolean``", "No", "No", "Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. |br| Only RTP packets will be considered."
	   "rerouting_disconnect_code_ids", "``array``", "No", "No", ":ref:`Rerouting disconnect codes <disconnect_codes_v34>`."
	   "sst_session_expires", "``integer``", "No", "No", "Session-Expires header value. Optional, should be in range with **sst_min_timer** and **sst_max_timer**. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_refresh_method_id", "``integer``", "No", "No", "SIP method which will be used for session update. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details. |br| Possible values: |br| 1 - Invite |br| 2 - Update |br| 3 - Update fallback Invite"
	   "transport_protocol_id", "``integer``", "No", "No", "The transport layer that will be responsible for the actual transmission of SIP requests and responses: |br| 1 - UDP |br| 2 - TCP |br| 3 - TLS."
	   "max_transfers", "``integer``", "No", "No", "Max count of the **REFER** requests."
	   "max_30x_redirects", "``integer``", "No", "No", "Max count of 301/302 redirects."
	   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_, `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
	   "stir_shaken_mode", "``string``", "No", "No", "Stir/Shaken mode. |br| See :ref:`STIR/SHAKEN <service_did_stir_shaken>`  for more details. |br| Possible Values: |br| 'disabled' - Do not send identity |br| 'original' - Transit Identity header as is |br| 'pai' - Add PAI, P-Attestation-Indicator, P-Origination-ID |br| 'original_pai' - Transit Identity Header as is + Add PAI, P-Attestation Indicator, P-Origination-ID |br| 'verstat' - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID"
	   "allowed_rtp_ips", "Array of ``strings``", "No", "No", "The allowed RTP IPs. Array from 0 to 10 items: IPv4 or IPv6, single or subnet."
	   "network_protocol_priority", "``string``", "No", "No", "Network protocol priority for SIP routing. |br| Possible values: |br| ``force_ipv4`` - Use IPv4 exclusively. |br| ``force_ipv6`` - Use IPv6 exclusively. |br| ``any`` - Use either IPv4 or IPv6. |br| ``prefer_ipv4`` - Prefer IPv4 but fall back to IPv6. |br| ``prefer_ipv6`` - Prefer IPv6 but fall back to IPv4."
	   "enabled_sip_registration", "``boolean``", "No", "No", "Enables SIP registration for the trunk."
	   "use_did_in_ruri", "``boolean``", "No", "No", "Uses the called DID in the R-URI. This attribute works only when ``enabled_sip_registration`` is ``true``."
	   "diversion_relay_policy", "``string``", "No", "No", "Controls how Diversion information is relayed. |br| Possible values: |br| ``none`` - Do not relay the Diversion header. |br| ``as_is`` - Relay the Diversion header as received. |br| ``sip`` - Relay the Diversion header as a SIP URI. |br| ``tel`` - Relay the Diversion header as a TEL URI."
	   "diversion_inject_mode", "``string``", "No", "No", "Controls how Diversion information is injected. |br| Possible values: |br| ``none`` - Do not add a Diversion header. |br| ``did_number`` - Add a Diversion header using the DID number in E.164 format."
	   "cnam_lookup", "``boolean``", "No", "No", "Enables inbound CNAM lookup."

   .. tab:: PSTN

        .. csv-table::
            :header: "Name", "Type","Nullable", "Is Required?", "Description"

            "dst", "``string``", "No","Yes", "Phone number's."

Examples
========

.. tabs::

    .. tab:: SIP
   
        .. http:example:: curl

            PATCH /v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
        
            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "voice_in_trunks",
                "attributes": {
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "new_username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null,
                      "network_protocol_priority": "prefer_ipv6",
                      "enabled_sip_registration": true,
                      "use_did_in_ruri": true,
                      "diversion_relay_policy": "tel",
                      "diversion_inject_mode": "did_number",
                      "cnam_lookup": true
                    }
                  }
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "new_username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null,
                      "network_protocol_priority": "prefer_ipv6",
                      "enabled_sip_registration": true,
                      "use_did_in_ruri": true,
                      "diversion_relay_policy": "tel",
                      "diversion_inject_mode": "did_number",
                      "cnam_lookup": true
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/pop"
                    }
                  }
                }
              }
            }      
            
    .. tab:: PSTN
   
        .. http:example:: curl

            PATCH /v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
            
            {
              "data": {
                "id": "989d8259-9c4f-4449-97b7-a3480b1cffff",
                "type": "voice_in_trunks",
                "attributes": {
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "7xxxxxxxx"
                    }
                  }
                }
              }
            }
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "989d8259-9c4f-4449-97b7-a3480b1cffff",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 5,
                  "weight": 65535,
                  "name": "Office Mobile",
                  "cli_format": "e164",
                  "cli_prefix": null,
                  "description": null,
                  "ringing_timeout": null,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                      "dst": "7xxxxxxxx"
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/vocie_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/989d8259-9c4f-4449-97b7-a3480b1cffff/pop"
                    }
                  }
                }
              }
            }

            
    .. tab:: SIP with POP
   
        .. http:example:: curl

            PATCH /v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d?include=pop HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]             
            
            {
              "data": {
                "id": "081ad751-d790-4e70-9c92-7c18f6b50a6d",
                "type": "voice_in_trunks",
                "attributes": {
                  "name": "New trunk"
                },
                "relationships": {
                  "pop": {
                    "data": {
                      "type": "pops",
                      "id": "cb5ea690-e3a3-4781-a4f3-3bd0123284dd"
                    }
                  }
                }
              }
            }
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "081ad751-d790-4e70-9c92-7c18f6b50a6d",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "New trunk",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        58,
                        59
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0,
                      "media_encryption_mode": "disabled",
                      "stir_shaken_mode": "disabled",
                      "allowed_rtp_ips": null
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/voice_in_trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/relationships/pop",
                      "related": "https://api.didww.com/v3/voice_in_trunks/081ad751-d790-4e70-9c92-7c18f6b50a6d/pop"
                    },
                    "data": {
                      "type": "pops",
                      "id": "cb5ea690-e3a3-4781-a4f3-3bd0123284dd"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "cb5ea690-e3a3-4781-a4f3-3bd0123284dd",
                  "type": "pops",
                  "attributes": {
                    "name": "US, NY"
                  }
                }
              ]
            }

    .. tab:: SIP with all rerouting disconnect codes

        .. http:example:: curl

            PATCH /v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "trunks",
                "attributes": {
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "rerouting_disconnect_code_ids": [
                        56,
                        57,
                        58,
                        59,
                        60,
                        64,
                        65,
                        66,
                        67,
                        68,
                        69,
                        70,
                        71,
                        72,
                        73,
                        74,
                        75,
                        76,
                        77,
                        78,
                        79,
                        80,
                        81,
                        82,
                        83,
                        84,
                        86,
                        87,
                        88,
                        89,
                        90,
                        91,
                        92,
                        96,
                        97,
                        98,
                        99,
                        100,
                        101,
                        102,
                        103,
                        104,
                        105,
                        106,
                        107,
                        108,
                        1505
                      ]
                    }
                  }
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "57a939dd-1600-41a6-80b1-f624e22a1f4c",
                "type": "trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 10,
                  "weight": 2,
                  "name": "Office",
                  "cli_format": "e164",
                  "cli_prefix": "+",
                  "description": "custom description",
                  "ringing_timeout": 30,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "external_reference_id": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "username": "new_username",
                      "host": "example.com",
                      "port": 5060,
                      "codec_ids": [
                        9,
                        7
                      ],
                      "rx_dtmf_format_id": 1,
                      "tx_dtmf_format_id": 1,
                      "resolve_ruri": true,
                      "auth_enabled": true,
                      "auth_user": "username",
                      "auth_password": "password",
                      "auth_from_user": "Office",
                      "auth_from_domain": "example.com",
                      "sst_enabled": false,
                      "sst_min_timer": 600,
                      "sst_max_timer": 900,
                      "sst_accept_501": true,
                      "sip_timer_b": 8000,
                      "dns_srv_failover_timer": 2000,
                      "rtp_ping": false,
                      "rtp_timeout": 30,
                      "force_symmetric_rtp": false,
                      "symmetric_rtp_ignore_rtcp": false,
                      "rerouting_disconnect_code_ids": [
                        56,
                        57,
                        58,
                        59,
                        60,
                        64,
                        65,
                        66,
                        67,
                        68,
                        69,
                        70,
                        71,
                        72,
                        73,
                        74,
                        75,
                        76,
                        77,
                        78,
                        79,
                        80,
                        81,
                        82,
                        83,
                        84,
                        86,
                        87,
                        88,
                        89,
                        90,
                        91,
                        92,
                        96,
                        97,
                        98,
                        99,
                        100,
                        101,
                        102,
                        103,
                        104,
                        105,
                        106,
                        107,
                        108,
                        1505
                      ],
                      "sst_session_expires": null,
                      "sst_refresh_method_id": 1,
                      "transport_protocol_id": 2,
                      "max_transfers": 0,
                      "max_30x_redirects": 0
                    }
                  }
                },
                "relationships": {
                  "trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/trunk_group",
                      "related": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/trunk_group"
                    }
                  },
                  "pop": {
                    "links": {
                      "self": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/relationships/pop",
                      "related": "https://api.didww.com/v3/trunks/57a939dd-1600-41a6-80b1-f624e22a1f4c/pop"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }
            
Other Responses
===============
            
.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 
            
            
            


.. |br| raw:: html

   <br />

.. _voice_in_trunk_object_v34:

====================
Inbound Trunk Object
====================

Json API object with type ``voice_in_trunks``. You can get several type of inbound trunks: SIP, PSTN.

Request
=======

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "priority","``integer``","The priority of this target host. |br| DIDWW will attempt to contact the target trunk with the lowest-numbered priority; |br| target trunk with the same priority will be tried in an order defined by the weight field. |br| The range is 0-65535. See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "weight","``integer``","A trunk selection mechanism. |br| The weight field specifies a relative weight for entries with the same priority. |br| Larger weights will be given a proportionately higher probability of being selected. |br| The range of this number is 0-65535. |br| In the presence of records containing weights greater than 0, records with weight 0 will have a very small chance of being selected. |br| See `RFC 2782 <https://tools.ietf.org/html/rfc2782>`_ for more details."
   "capacity_limit", "``integer``","Maximum number of simultaneous calls for the trunk."
   "ringing_timeout", "``integer``","After which it will be end transaction with internal disconnect code **Ringing timeout** if the call was not connected."
   "name", "``string``","Friendly name of the trunk."
   "external_reference_id", "``string``","Optional identifier for the inbound trunk in the customer's external system. Maximum length is 100 characters."
   "cli_format", "``string``","**raw** - Do not alter CLI (default). |br| **e164** - Attempt to convert CLI to E.164 format. |br| **local** - Attempt to convert CLI to Localized format. |br| **CLI format conversion may not work correctly for phone calls originating from outside the country of that specific DID**."
   "cli_prefix", "``string``","You may prefix the CLI with an optional ``+`` sign followed by up to 6 characters, including digits and ``#``."
   "description", "``string``","Optional description of the trunk."
   "configuration", "One of :ref:`sip_configurations <trunk_attributes_v34>`, |br| :ref:`pstn_configurations <trunk_attributes_v34>`","Trunk configuration complex object."
   "created_at","DateTime","Trunk created at DateTime"

Object Relationships
--------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_in_trunk_group", "to-one", ":ref:`Trunk Group Object <voice_in_trunk_group_object_v34>`"
   "pop", "to-one", ":ref:`POP Object <pop_object_v34>`"

.. _trunk_attrs_objc_v34:

Attributes Configuration
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``sip_configurations``", "No","Yes", "SIP configuration complex object. "
	   "attributes", ":ref:`sip_configuration_attributes <trunk_attributes_v34>`","No", "Yes", "SIP configuration attributes object."
    
   .. tab:: PSTN

	.. csv-table::
	   :header: "Name", "Type","Nullable", "Is Required?", "Description"

	   "type", "``pstn_configurations``", "No","Yes", "PSTN configuration complex object."
	   "attributes", ":ref:`pstn_configuration_attributes <trunk_attributes_v34>`","No", "Yes", "PSTN configuration attributes object."

Configuration Attributes
------------------------

.. tabs::

   .. tab:: SIP
   
    .. csv-table::
	   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

	   "username", "``string``", "No", "Yes", "User part of R-URI in INVITE request. |br| You also may use “{DID}” pattern which will be replaced by called DID number in E164 format. |br| For example, you can set Username to “+{DID}”; if you wish to have it in +E164 format"
	   "host", "``string``", "No", "Yes", "Host part of R-URI in INVITE request."
	   "port", "``integer``", "No", "No", "Port part of R-URI in INVITE request (is not mandatory). |br| If port is null, SRV record will be resolved (or A record if SRV is unavailable)."
	   "codec_ids", "``array``", "No", "No", ":ref:`Codecs <trunk_codecs_v34>`"
	   "rx_dtmf_format_id", "``integer``", "No", "No", "The method id for receiving DTMF signals from customers equipment. |br| Possible values: |br| 1 - RFC 2833 |br| 2 - SIP INFO application/dtmf-relay OR application/dtmf |br| 3 - RFC 2833 OR SIP INFO"
	   "tx_dtmf_format_id", "``integer``", "No", "No", "The method of sending DTMF signals to customers equipment. |br| Possible values: |br| 1 - Disable sending |br| 2 - RFC 2833 |br| 3 - SIP INFO application/dtmf-relay |br| 4 - SIP INFO application/dtmf"
	   "resolve_ruri", "``boolean``", "No", "No", "Replace host part of the R-URI by resolved IP address."
	   "auth_enabled", "``boolean``", "No", "No", "Enable authorization for the SIP server."
	   "auth_user", "``string``", "No", "No", "Optional authorization user for the SIP server."
	   "auth_password", "``string``", "No", "No", "Optional authorization password for the SIP server."
	   "auth_from_user", "``string``", "No", "No", "Specify user in a **from** field instead of CallerID (overrides CallerID). |br| Some equipment require **from**; to be equivalent to **Auth user**."
	   "auth_from_domain", "``string``", "No", "No", "Sets default **from** domain in SIP messages. Some equipment may require specific **From** Domain."
	   "sst_enabled", "``boolean``", "No", "No", "Enable SIP Session timers customization. |br| SIP session timers are used to make sure that a session (dialog) is still alive, |br| even though there may have been a long time since the last in-dialog message. |br| If the other end is not responding, the dialog will be hung up automatically. |br| SIP session timers need to be supported by all end points for it to work. |br| It’s a SIP extension, standardized by the IETF. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_min_timer", "``integer``", "No", "No", "Minimal SIP Session timer value (Default 600 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_max_timer", "``integer``", "No", "No", "Maximal SIP Session timer value (Default 900 seconds). |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_accept_501", "``boolean``", "No", "No", "Do not drop the call after receiving SIP 501 response for non-critical messages."
	   "sip_timer_b", "``integer``", "No", "No", "INVITE transaction timeout (Default 8000ms). |br| See `RFC 3261 Section 17.1.1.2 <https://tools.ietf.org/html/rfc3261#section-17.1.1.2>`_ for more details."
	   "dns_srv_failover_timer", "``integer``", "No", "No", "Invite transaction timeout for each of gateways with DNS SRV rerouting (Default 2000ms)."
	   "rtp_ping", "``boolean``", "No", "No", "Use RTP PING when connecting a call. |br| After establishing the call, DIDWW will send empty RTP packet **RTP PING**. |br| It is necessary if both parties operate in Symmetric RTP / Comedia mode and expect the other party to start sending RTP first."
	   "rtp_timeout", "``boolean``", "No", "No", "Disconnect the call if the RTP packets do not arrive within the specified time."
	   "force_symmetric_rtp", "``boolean``", "No", "No", "Forced to work in Symmetric RTP / COMEDIA mode."
	   "symmetric_rtp_ignore_rtcp", "``boolean``", "No", "No", "Avoid switching RTP session based on RTCP packet while working in Symmetric RTP / COMEDIA. |br| Only RTP packets will be considered."
	   "rerouting_disconnect_code_ids", "``array``", "No", "No", ":ref:`Rerouting disconnect codes <disconnect_codes_v34>`."
	   "sst_session_expires", "``integer``", "No", "No", "Session-Expires header value. Optional, should be in range with **sst_min_timer** and **sst_max_timer**. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details."
	   "sst_refresh_method_id", "``integer``", "No", "No", "SIP method which will be used for session update. |br| See `RFC 4028 <https://tools.ietf.org/html/rfc4028>`_ for more details. |br| Possible values: |br| 1 - Invite |br| 2 - Update |br| 3 - Update fallback Invite"
	   "transport_protocol_id", "``integer``", "No", "No", "Transport protocol ID. Possible values: |br| 1 - UDP |br| 2 - TCP |br| 3 - TLS"
	   "max_transfers", "``integer``", "No", "No", "Max count of the **REFER** requests."
	   "max_30x_redirects", "``integer``", "No", "No", "Max count of 301/302 redirects."
	   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. |br| See `RFC4568 about SRTP SDES <https://datatracker.ietf.org/doc/html/rfc4568>`_, `RFC5764 about SRTP DTLS <https://datatracker.ietf.org/doc/html/rfc5764>`_, and `RFC6189 about ZRTP <https://datatracker.ietf.org/doc/html/rfc6189>`_ for more details. |br| Possible values: |br| 'disabled' - Disabled |br| 'srtp_sdes' - SRTP SDES |br| 'srtp_dtls' - SRTP DTLS |br| 'zrtp' - ZRTP"
	   "stir_shaken_mode", "``string``", "No", "No", "Stir/Shaken mode. |br| See :ref:`STIR/SHAKEN <service_did_stir_shaken>`  for more details. |br| Possible Values: |br| 'disabled' - Do not send identity |br| 'original' - Transit Identity header as is |br| 'pai' - Add PAI, P-Attestation-Indicator, P-Origination-ID |br| 'original_pai' - Transit Identity Header as is + Add PAI, P-Attestation Indicator, P-Origination-ID |br| 'verstat' - Add P-Stir-Verstat, P-Attestation-Indicator, P-Origination-ID"
	   "allowed_rtp_ips", "Array of ``strings``", "No", "No", "The allowed RTP IPs. Array from 0 to 10 items: IPv4 or IPv6, single or subnet."
	   "network_protocol_priority", "``string``", "No", "No", "Network protocol priority for SIP routing. |br| Possible values: |br| ``force_ipv4`` - Use IPv4 exclusively. |br| ``force_ipv6`` - Use IPv6 exclusively. |br| ``any`` - Use either IPv4 or IPv6. |br| ``prefer_ipv4`` - Prefer IPv4 but fall back to IPv6. |br| ``prefer_ipv6`` - Prefer IPv6 but fall back to IPv4."
	   "enabled_sip_registration", "``boolean``", "No", "No", "Enables SIP registration for the trunk."
	   "use_did_in_ruri", "``boolean``", "No", "No", "Uses the called DID in the R-URI. This attribute works only when ``enabled_sip_registration`` is ``true``."
	   "diversion_relay_policy", "``string``", "No", "No", "Controls how Diversion information is relayed. |br| Possible values: |br| ``none`` - Do not relay the Diversion header. |br| ``as_is`` - Relay the Diversion header as received. |br| ``sip`` - Relay the Diversion header as a SIP URI. |br| ``tel`` - Relay the Diversion header as a TEL URI."
	   "diversion_inject_mode", "``string``", "No", "No", "Controls how Diversion information is injected. |br| Possible values: |br| ``none`` - Do not add a Diversion header. |br| ``did_number`` - Add a Diversion header using the DID number in E.164 format."
	   "cnam_lookup", "``boolean``", "No", "No", "Enables inbound CNAM lookup."
	   
   .. tab:: PSTN

	.. csv-table::
		:header: "Name", "Type","Nullable", "Is Required?", "Description"
		
		"dst", "``string``", "No","Yes", "Phone number's."


.. |br| raw:: html

   <br />

.. _voice_in_trunk_groups_v34:

===================
Inbound Trunk Group
===================

Returns the details of an inbound trunk group. Allows create, edit, or delete an inbound trunk group.

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
   :maxdepth: 1

   get-trunk-group.rst
   get-trunk-groups.rst
   create-trunk-group.rst
   update-trunk-group.rst
   delete-trunk-group.rst
   trunk-group-object.rst
  
  
  




=======================
Get Inbound Trunk Group
=======================

Returns a single inbound trunk group.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunk_groups/``

.. note:: For all returned data attributes, see :doc:`Trunk Group Object <trunk-group-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of the Trunk Group."
   "include","``string``","No",":ref:`Inclusion <api_includes>`. "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunks", ":ref:`List of Trunk Objects <voice_in_trunk_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
      
   
            GET /v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
               
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "418fe352-04b8-4e03-a7ce-cb57efd8c664",
                "type": "voice_in_trunk_groups",
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664"
                },
                "attributes": {
                  "created_at": "2017-06-25T14:56:31.513Z",
                  "external_reference_id": null,
                  "name": "Common Group",
                  "capacity_limit": 69
                },
                "relationships": {
                  "voice_in_trunks": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664/relationships/voice_in_trunks",
                      "related": "https://api.didww.com/v3/voice_in_trunk_groups/418fe352-04b8-4e03-a7ce-cb57efd8c664/voice_in_trunks"
                    }
                  }
                },
                "meta": {
                  "trunks_count": 1
                }
              }
            }
        
   .. tab:: Included Trunks
     
      .. http:example:: curl
   
            GET /v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae?include=voice_in_trunks HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "465b059a-b4a2-4c8e-ab3b-33dc60e096ae",
                "type": "voice_in_trunk_groups",
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae"
                },
                "attributes": {
                  "created_at": "2017-06-25T14:56:31.513Z",
                  "external_reference_id": null,
                  "name": "Common Group",
                  "capacity_limit": 69
                },
                "relationships": {
                  "voice_in_trunks": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae/relationships/voice_in_trunks",
                      "related": "https://api.didww.com/v3/voice_in_trunk_groups/465b059a-b4a2-4c8e-ab3b-33dc60e096ae/voice_in_trunks"
                    },
                    "data": [
                      {
                        "type": "voice_in_trunks",
                        "id": "87133f4d-4a88-436b-b74b-b63e79318426"
                      }
                    ]
                  }
                },
                "meta": {
                  "trunks_count": 1
                }
              },
              "included": [
                {
                  "id": "87133f4d-4a88-436b-b74b-b63e79318426",
                  "type": "voice_in_trunks",
                  "attributes": {
                    "priority": 1,
                    "capacity_limit": 5,
                    "weight": 65535,
                    "name": "Office Mobile",
                    "cli_format": "e164",
                    "cli_prefix": null,
                    "description": null,
                    "ringing_timeout": null,
                    "configuration": {
                      "type": "pstn_configurations",
                      "attributes": {
                        "dst": "1xxxxxxxxx"
                      }
                    }
                  },
                  "relationships": {
                    "voice_in_trunk_group": {
                      "links": {
                        "self": "https://api.didww.com/v3/voice_in_trunks/87133f4d-4a88-436b-b74b-b63e79318426/relationships/voice_in_trunk_group",
                        "related": "https://api.didww.com/v3/voice_in_trunks/87133f4d-4a88-436b-b74b-b63e79318426/voice_in_trunk_group"
                      }
                    }
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




==========================
Create Inbound Trunk Group
==========================

Creates a Trunk Group.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_in_trunk_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "include","``string``","No",":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
	:header: "Name", "Type","Nullable", "Is Required?", "Description"

	"name", "``string``", "No","Yes", "Unique name of the Trunk Group."
	"external_reference_id", "``string``", "Yes","No", "Optional identifier for the trunk group in the customer's external system. Maximum length is 100 characters."
	"capacity_limit", "``integer``", "No","No", "Maximum number of simultaneous calls for the Trunk Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_in_trunks", ":ref:`To many <api_relationships>`", "Linkage for included trunks."

Examples
========

.. tabs::

   .. tab:: Simple Create
   
     .. http:example:: curl
   
        POST /v3/voice_in_trunk_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        {
          "data": {
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Main group",
              "capacity_limit": 100
            }
          }
        }
        
        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "a6370df6-86db-4a1a-9a54-3742f1d8615c",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/a6370df6-86db-4a1a-9a54-3742f1d8615c"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "external_reference_id": null,
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/a6370df6-86db-4a1a-9a54-3742f1d8615c/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/a6370df6-86db-4a1a-9a54-3742f1d8615c/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 0
            }
          }
        }        
        
        
   .. tab:: Create and Assign Trunks
   
     .. http:example:: curl
   
        POST /v3/voice_in_trunk_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "data": [
                  {
                    "type": "voice_in_trunks",
                    "id": "b7a9d1ce-6a89-4071-bc0d-486ee223787d"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "7ca415f8-8342-427a-bbfc-171b995f75d6"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "46aa9cac-a8dd-4a06-82db-cb0731e53ba0"
                  }
                ]
              }
            }
          }
        }        
        
        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "faea735d-ba77-40ef-bf13-f4dfc0f43a68",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/faea735d-ba77-40ef-bf13-f4dfc0f43a68"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "external_reference_id": null,
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/faea735d-ba77-40ef-bf13-f4dfc0f43a68/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/faea735d-ba77-40ef-bf13-f4dfc0f43a68/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 3
            }
          }
        }
        
   .. tab:: Create and Assign Trunk + Include Trunks in Response
   
     .. http:example:: curl
   
        POST /v3/voice_in_trunk_groups?include=voice_in_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        {
          "data": {
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "data": [
                  {
                    "type": "voice_in_trunks",
                    "id": "1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "c606cd05-a19f-4d3c-9362-3857a79a6e1d"
                  }
                ]
              }
            }
          }
        }
        
        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "3b49216d-ccb0-4376-b9fa-a43ffcb48c35",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/3b49216d-ccb0-4376-b9fa-a43ffcb48c35"
            },
            "attributes": {
              "created_at": "2017-08-16T14:04:36.013Z",
              "external_reference_id": null,
              "name": "Main group",
              "capacity_limit": 100
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/3b49216d-ccb0-4376-b9fa-a43ffcb48c35/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/3b49216d-ccb0-4376-b9fa-a43ffcb48c35/voice_in_trunks"
                },
                "data": [
                  {
                    "type": "voice_in_trunks",
                    "id": "1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7"
                  },
                  {
                    "type": "voice_in_trunks",
                    "id": "c606cd05-a19f-4d3c-9362-3857a79a6e1d"
                  }
                ]
              }
            },
            "meta": {
              "trunks_count": 2
            }
          },
          "included": [
            {
              "data": {
                "id": "1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7",
                "type": "voice_in_trunks",
            "attributes": {
                "priority": 1,
                "capacity_limit": 2,
                "weight": 65535,
                "name": "Office PSTN",
                "cli_format": "e164",
                "cli_prefix": null,
                "description": null,
                "ringing_timeout": null,
                "configuration": {
                    "type": "pstn_configurations",
                    "attributes": {
                        "dst": "18337249999"
                      ]
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/1dcbcdae-4ad6-4c42-acc3-b4ec097dd2f7/voice_in_trunk_group"
                    }
                  }
                }
              }
            },
            {
              "data": {
                "id": "c606cd05-a19f-4d3c-9362-3857a79a6e1d",
                "type": "voice_in_trunks",
                "attributes": {
                  "priority": 1,
                  "capacity_limit": 18,
                  "weight": 65535,
                  "name": "Office sip",
                  "cli_format": "e164",
                  "cli_prefix": "+1",
                  "description": null,
                  "ringing_timeout": null,
                  "configuration": {
                    "type": "sip_configurations",
                    "attributes": {
                      "dst": "1xxxxxxxxx",
                      "host": "example.com",
                      "port": null,
                      "codec_ids": [
                        9,
                        6
                      ]
                    }
                  }
                },
                "relationships": {
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/voice_in_trunks/c606cd05-a19f-4d3c-9362-3857a79a6e1d/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/voice_in_trunks/c606cd05-a19f-4d3c-9362-3857a79a6e1d/voice_in_trunk_group"
                    }
                  }
                }
              }
            }
          ]
        } 

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>` "
   "401","No",":ref:`Unauthorized <api_key>`" 




==========================
Delete Inbound Trunk Group
==========================

Deletes a Trunk Group.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/voice_in_trunk_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk Group."

Example
=======

.. http:example:: curl

    DELETE https://api.didww.com/v3/voice_in_trunk_groups/1156df17-bcea-4c9a-9c1d-29320e288c03 HTTP/1.1
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 





========================
Get Inbound Trunk Groups
========================

Returns a collection of Trunk Groups.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_in_trunk_groups``

.. note:: For all returned data attributes, see :doc:`Trunk Group Object <trunk-group-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "include","``string``","No",":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]","``string``","No",":ref:`Filtering <api_filters>`"
   "fields[voice_in_trunk_groups]","``string``","No",":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort","``string``","No",":ref:`Sorting <api_sorting>` "

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "voice_in_trunks", ":ref:`Trunk Object <voice_in_trunk_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by: "

   "name", "The ``name`` field. "
   "created_at", "The ``created_at`` field. "
   "capacity_limit", "The ``capacity_limit`` field. "

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/voice_in_trunk_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "65b401cb-42f5-4911-877d-dc317a46b478",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/65b401cb-42f5-4911-877d-dc317a46b478"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "external_reference_id": null,
                "name": "Common Group",
                "capacity_limit": 69
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/65b401cb-42f5-4911-877d-dc317a46b478/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/65b401cb-42f5-4911-877d-dc317a46b478/voice_in_trunks"
                  }
                }
              },
              "meta": {
                "trunks_count": 1
              }
            },
            {
              "id": "72a60b4a-affb-46c7-8a8a-7e042c7611e8",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/72a60b4a-affb-46c7-8a8a-7e042c7611e8"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "external_reference_id": null,
                "name": "Custom Group",
                "capacity_limit": 50
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/72a60b4a-affb-46c7-8a8a-7e042c7611e8/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/72a60b4a-affb-46c7-8a8a-7e042c7611e8/voice_in_trunks"
                  }
                }
              },
              "meta": {
                "trunks_count": 0
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/voice_in_trunk_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/voice_in_trunk_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Included Trunks
   
    .. http:example:: curl
   
        GET /v3/voice_in_trunk_groups?include=voice_in_trunks HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "a8176983-61c4-4768-b699-10d5f3245d90",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/a8176983-61c4-4768-b699-10d5f3245d90"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "external_reference_id": null,
                "name": "Common Group",
                "capacity_limit": 69
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/a8176983-61c4-4768-b699-10d5f3245d90/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/a8176983-61c4-4768-b699-10d5f3245d90/voice_in_trunks"
                  },
                  "data": [
                    {
                      "type": "voice_in_trunks",
                      "id": "5aa0b0ea-2bda-4424-a93c-104829d72c06"
                    }
                  ]
                }
              },
              "meta": {
                "trunks_count": 1
              }
            },
            {
              "id": "def3b7b1-ce76-420d-9684-8dbdb69e17c1",
              "type": "voice_in_trunk_groups",
              "links": {
                "self": "https://api.didww.com/v3/voice_in_trunk_groups/def3b7b1-ce76-420d-9684-8dbdb69e17c1"
              },
              "attributes": {
                "created_at": "2017-06-25T14:56:31.513Z",
                "external_reference_id": null,
                "name": "Custom Group",
                "capacity_limit": 50
              },
              "relationships": {
                "voice_in_trunks": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunk_groups/def3b7b1-ce76-420d-9684-8dbdb69e17c1/relationships/voice_in_trunks",
                    "related": "https://api.didww.com/v3/voice_in_trunk_groups/def3b7b1-ce76-420d-9684-8dbdb69e17c1/voice_in_trunks"
                  },
                  "data": [
        
                  ]
                }
              },
              "meta": {
                "trunks_count": 0
              }
            }
          ],
          "included": [
            {
              "id": "5aa0b0ea-2bda-4424-a93c-104829d72c06",
              "type": "voice_in_trunks",
              "attributes": {
                "priority": 1,
                "capacity_limit": 5,
                "weight": 65535,
                "name": "Office Mobile",
                "cli_format": "e164",
                "cli_prefix": null,
                "description": null,
                "ringing_timeout": null,
                "configuration": {
                  "type": "pstn_configurations",
                  "attributes": {
                    "dst": "1xxxxxxxxx"
                  }
                }
              },
              "relationships": {
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/voice_in_trunks/5aa0b0ea-2bda-4424-a93c-104829d72c06/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/voice_in_trunks/5aa0b0ea-2bda-4424-a93c-104829d72c06/voice_in_trunk_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/voice_in_trunk_groups?include=voice_in_trunks&page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/voice_in_trunk_groups?include=voice_in_trunks&page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. _voice_in_trunk_group_object_v34:

==========================
Inbound Trunk Group Object
==========================

Trunk Group Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

	"name", "``string``", "Trunk Group name."
	"external_reference_id", "``string``", "Optional identifier for the trunk group in the customer's external system. Maximum length is 100 characters."
	"capacity_limit", "``integer``", "Maximum number of simultaneous calls for the Trunk Group."
   "created_at", "``DateTime``", "Trunk Group creation date and time."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_in_trunks", "to-many", ":ref:`Inbound Trunk Object <voice_in_trunk_object_v34>`. Returns the inbound trunks linked to the trunk group."




==========================
Update Inbound Trunk Group
==========================

Updates a Trunk Group.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/voice_in_trunk_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique ID identifier of Trunk Group."
   "include","``string``","No",":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
	:header: "Name", "Type","Nullable", "Is Required?", "Description"

	"name", "``string``", "No","Yes", "Unique name of the Trunk Group."
	"external_reference_id", "``string``", "Yes","No", "Optional identifier for the trunk group in the customer's external system. Maximum length is 100 characters."
	"capacity_limit", "``integer``", "No","No", "Maximum number of simultaneous calls for the Trunk Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_in_trunks", ":ref:`To many <api_relationships>`", "Linkage for included trunks."

Examples
========

.. tabs::

   .. tab:: Simple Update
   
     .. http:example:: curl
   
        PATCH /v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
           
        {
          "data": {
            "id": "43deb3aa-674a-465e-ac16-fb3084325ec7",
            "type": "voice_in_trunk_groups",
            "attributes": {
              "name": "Renamed group",
              "capacity_limit": 1
            }
          }
        }
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "43deb3aa-674a-465e-ac16-fb3084325ec7",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "external_reference_id": null,
              "name": "Renamed group",
              "capacity_limit": 1
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/43deb3aa-674a-465e-ac16-fb3084325ec7/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 1
            }
          }
        }
        
   .. tab:: Remove Inbound Trunks from the Group
   
     .. http:example:: curl
   
        PATCH /v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a",
            "type": "voice_in_trunk_groups",
            "relationships": {
              "voice_in_trunks": {
                "data": [
        
                ]
              }
            }
          }
        }        
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a",
            "type": "voice_in_trunk_groups",
            "links": {
              "self": "https://api.didww.com/v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a"
            },
            "attributes": {
              "created_at": "2017-06-25T14:56:31.513Z",
              "external_reference_id": null,
              "name": "Common Group",
              "capacity_limit": 69
            },
            "relationships": {
              "voice_in_trunks": {
                "links": {
                  "self": "https://api.didww.com/v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a/relationships/voice_in_trunks",
                  "related": "https://api.didww.com/v3/voice_in_trunk_groups/e74fcf6a-bb8d-4ee0-9980-bdc24a728b9a/voice_in_trunks"
                }
              }
            },
            "meta": {
              "trunks_count": 0
            }
          }
        }
        

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>` "
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _voice_out_trunks_v34:

===============
Outbound Trunks
===============

Returns a list of all outbound trunks configured for the account. Allows you to create, update, fetch, and delete an outbound trunk.

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. note:: Voice out trunk management via API is not enabled by default. For more information, please contact our sales team at sales@didww.com.

.. toctree::
  :maxdepth: 1
  
  get-voice-out-trunk.rst
  get-voice-out-trunks.rst
  create-voice-out-trunk.rst
  update-voice-out-trunk.rst
  delete-voice-out-trunk.rst
  voice-out-trunk-object.rst
  voice-out-trunk-regenerate-credentials.rst
  
  
  
  
  
  


==================
Get Outbound Trunk
==================

Returns a single outbound trunk owned by the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_out_trunks/{id}``

.. note:: For all returned data attributes, see :doc:`Outbound Trunk Object <voice-out-trunk-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique identifier of the outbound trunk."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`DID Object <did_object_v34>`"
   "emergency_dids", "Emergency DID relationship data."

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`DID Object <did_object_v34>`"
   "emergency_dids", "Emergency DID relationship data."

Examples
========

.. tabs::

   .. tab:: credentials_and_ip

      .. http:example:: curl

         GET /v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "03813615-da15-4e3b-8e0a-3ea64b2585de",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": "string",
                   "username": "554******",
                   "password": "fqe******"
                 }
               },
               "allow_any_did_as_cli": true,
               "status": "active",
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "media_encryption_mode": "disabled",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: ip_only

      .. http:example:: curl

         GET /v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "cf2e6377-fcaa-4416-8c8e-acd5f31a427f",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": [
                 "198.51.100.1/32"
               ],
               "authentication_method": {
                 "type": "ip_only",
                 "attributes": {
                   "allowed_sip_ips": [
                     "198.51.100.1/32"
                   ],
                   "tech_prefix": null
                 }
               },
               "allow_any_did_as_cli": true,
               "status": "active",
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "media_encryption_mode": "disabled",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": true,
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: twilio

      .. http:example:: curl

         GET /v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "14a0b7fb-845a-44d9-a7dc-ac1620f21e42",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": null,
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "allow_any_did_as_cli": true,
               "status": "active",
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "media_encryption_mode": "disabled",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: include emergency_dids

      .. http:example:: curl

         GET /v3/voice_out_trunks/91f7bcb4-3278-433b-9de1-5e6f4131fd4d?include=emergency_dids HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "91f7bcb4-3278-433b-9de1-5e6f4131fd4d",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk with emergency DID",
               "allowed_rtp_ips": [
                 "198.51.100.0/24"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "198.51.100.0/24"
                   ],
                   "tech_prefix": null,
                   "username": "9q2******",
                   "password": "6zm******"
                 }
               },
               "allow_any_did_as_cli": true,
               "status": "active",
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 75,
               "threshold_reached": false,
               "threshold_amount": "3000.0",
               "media_encryption_mode": "disabled",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/91f7bcb4-3278-433b-9de1-5e6f4131fd4d/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/91f7bcb4-3278-433b-9de1-5e6f4131fd4d/dids"
                 }
               },
               "emergency_dids": {
                 "data": [
                   {
                     "type": "dids",
                     "id": "0b5d4ca6-7002-4f19-a678-f5be95538e9b"
                   }
                 ]
               }
             }
           },
           "included": [
             {
               "id": "0b5d4ca6-7002-4f19-a678-f5be95538e9b",
               "type": "dids",
               "attributes": {
                 "number": "12125550124",
                 "emergency_enabled": true
               }
             }
           ],
           "meta": {
             "api_version": "2026-04-16"
           }
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

.. _voice_out_trunks_v34_create:

=====================
Create Outbound Trunk
=====================

Creates an outbound trunk.

In version ``2026-04-16``, customers can create outbound trunks through the API even if the Outbound feature is not enabled on the account.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_out_trunks``

Body Parameters
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "type", "``string``", "No", "Yes", "Must be ``voice_out_trunks``."
   "attributes", "``object``", "No", "Yes", "Outbound trunk attributes object."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "No", "Yes", "The outbound trunk name."
   "external_reference_id", "``string``", "Yes", "No", "Optional identifier for the outbound trunk in the customer's external system. Maximum length is 100 characters."
   "allowed_rtp_ips", "Array of ``strings``", "Yes", "No", "Allowed RTP IP addresses for media traffic. Required when ``authentication_method.type`` is ``credentials_and_ip``."
   "authentication_method", "``object``", "No", "Yes", "Authentication method object. Supported POST types: |br| ``credentials_and_ip`` - use SIP credentials together with allowed IP addresses. |br| ``twilio`` - use a Twilio Account SID for authentication. |br| ``ip_only`` is not supported in ``POST`` requests."
   "on_cli_mismatch_action", "``string``", "No", "Yes", "Possible values: |br| ``send_original_cli`` - pass the original ``From`` header value from your system to the destination without modification. |br| ``reject_call`` - reject the call if the ``From`` header value does not match any DID allowed on the trunk. |br| ``replace_cli`` - replace the CLI with one of the DIDs allowed on the trunk."
   "capacity_limit", "``integer``", "Yes", "No", "The capacity limit of the outbound trunk. Allowed values from 0 to 32767."
   "allow_any_did_as_cli", "``boolean``", "No", "No", "When set to ``true``, all eligible DIDs can be used as CLI and the ``dids`` relationship must not contain explicit DIDs."
   "status", "``string``", "No", "No", "Possible values: |br| ``active`` - the trunk can be used for outbound traffic. |br| ``blocked`` - outbound traffic on the trunk is blocked. |br| If set to ``null``, the default value is ``active``."
   "threshold_amount", "``string``", "Yes", "No", "The outbound trunk 24-hour threshold limit. Can be from 0.0 to 100000.0."
   "default_dst_action", "``string``", "No", "No", "Possible values: |br| ``allow_all`` - allow calls to all destinations except the prefixes listed in ``dst_prefixes``. |br| ``reject_all`` - s to all destinations except the prefixes listed in ``dst_prefixes``."
   "dst_prefixes", "Array of ``strings``", "Yes", "No", "The destination prefixes allowed or rejected based on ``default_dst_action``."
   "emergency_enable_all", "``boolean``", "No", "No", "Allows all eligible DIDs to be used for emergency calling on the trunk. Default value is ``false``."
   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. Possible values: |br| ``disabled`` - media encryption is turned off. |br| ``srtp_sdes`` - use SRTP encryption with SDES key exchange. |br| ``srtp_dtls`` - use SRTP encryption with DTLS key exchange. |br| ``zrtp`` - use SRTP encryption with ZRTP key exchange."
   "callback_url", "``string``", "Yes", "No", "Can be ``null`` or a valid HTTP(S) URL."
   "force_symmetric_rtp", "``boolean``", "No", "No", "Enables symmetric RTP / COMEDIA mode."
   "rtp_ping", "``boolean``", "No", "No", "Enables RTP ping after the call is connected."
   "rtp_timeout", "``integer``", "Yes", "No", "Disconnects the call if RTP packets do not arrive within the specified time. Supported values are from 30 to 600 seconds."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`DIDs <dids_v34>`", "The DID numbers explicitly allowed as CLI when ``allow_any_did_as_cli`` is ``false``. DIDs must support ``voice_out`` feature to be selected."
   "emergency_dids", ":ref:`DIDs <dids_v34>`", "The DID numbers explicitly enabled for emergency calling when ``emergency_enable_all`` is ``false``.  DIDs must support ``voice_out`` and ``emergency`` features and have ``emergency_enabled = true`` to be selected."

Authentication Method
---------------------

The outbound trunk authentication is configured through the ``authentication_method`` attribute.

Supported authentication method types:

- ``credentials_and_ip`` - uses SIP credentials together with allowed IP addresses.
- ``twilio`` - uses a Twilio Account SID for authentication.
- ``ip_only`` is returned by ``GET`` endpoints but is not supported in ``POST`` requests.

Authentication Method Attributes by Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. tabs::

   .. tab:: credentials_and_ip

      .. csv-table::
         :header: "Name", "Type", "Nullable", "Is Required?", "Description"

         "allowed_sip_ips", "Array of ``strings``", "No", "Yes", "The allowed originating SIP IPs."
         "tech_prefix", "``string``", "Yes", "No", "An optional technical prefix added before the destination number. The maximum length is 8 characters and only digits and ``#`` are supported."

   .. tab:: twilio

      .. csv-table::
         :header: "Name", "Type", "Nullable", "Is Required?", "Description"

         "twilio_account_sid", "``string``", "No", "Yes", "The Twilio Account SID. It is a 34-character identifier of the Twilio account."

.. _voice_out_trunks_v34_create_examples:

Examples
========

.. tabs::

   .. tab:: credentials_and_ip

      .. http:example:: curl

         POST /v3/voice_out_trunks HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "callback_url": null,
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "03813615-da15-4e3b-8e0a-3ea64b2585de",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "callback_url": null,
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null,
                   "username": "554******",
                   "password": "fqe******"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: twilio

      .. http:example:: curl

         POST /v3/voice_out_trunks HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "callback_url": null,
               "allowed_rtp_ips": null,
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "14a0b7fb-845a-44d9-a7dc-ac1620f21e42",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "callback_url": null,
               "allowed_rtp_ips": null,
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: Selected emergency DIDs

      .. http:example:: curl

         POST /v3/voice_out_trunks HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk for selected emergency DIDs",
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ]
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "emergency_enable_all": false
            },
            "relationships": {
               "emergency_dids": {
                 "data": [
                   {
                     "id": "7158ac26-392f-47d1-89ab-c8b3f5ec05d9",
                     "type": "dids"
                   },
                   {
                     "id": "67a90c09-1bff-4bc3-a35e-116fda2b0d22",
                     "type": "dids"
                   }
                 ]
               }
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "9c91f03e-8796-4e6a-8c12-00e4f334f9b2",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk for selected emergency DIDs",
               "callback_url": null,
               "allowed_rtp_ips": null,
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null,
                   "username": "554******",
                   "password": "fqe******"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": null,
               "allow_any_did_as_cli": false,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": null,
               "default_dst_action": "allow_calls",
               "dst_prefixes": null,
               "emergency_enable_all": false,
               "media_encryption_mode": "disable",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/dids"
                 },
                 "data": []
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/emergency_dids"
                 }
                 },
                 "data": [
                   {
                     "id": "7158ac26-392f-47d1-89ab-c8b3f5ec05d9",
                     "type": "dids"
                   },
                   {
                     "id": "67a90c09-1bff-4bc3-a35e-116fda2b0d22",
                     "type": "dids"
                   }
                 ]
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "422", "No", ":ref:`Validation Error Object <api_validation_error_object>`"
   "400", "No", ":ref:`Bad Request <api_bad_request>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"



=====================
Delete Outbound Trunk
=====================

Deletes the outbound trunk without the possibility to retrieve it.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/voice_out_trunks/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"
   
   "id","``string``","Yes","Unique identifier of the outbound trunk."

Example
=======

.. http:example:: curl

    DELETE /v3/voice_out_trunks/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    


===================
Get Outbound Trunks
===================

Returns the collection of outbound trunks.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/voice_out_trunks``

.. note:: For all returned data attributes, see :doc:`Outbound Trunk Object <voice-out-trunk-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
   "fields[voice_out_trunks]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"
   "pagination", "``string``", "No", ":ref:`Pagination <api_pagination>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "name", "``string``", "Yes", "Yes", "The trunk ``name`` field."
   "name_contains", "``string``", "Yes", "Yes", "The ``name_contains`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."
   "on_cli_mismatch_action", "``string``", "Yes", "Yes", "The ``on_cli_mismatch_action`` field. Possible values: ``reject_call``, ``replace_cli``, ``send_original_cli``."
   "allow_any_did_as_cli", "``boolean``", "No", "No", "The ``allow_any_did_as_cli`` field."
   "status", "``string``", "No", "No", "The ``status`` field. Possible values: ``active``, ``blocked``."
   "threshold_reached", "``boolean``", "No", "No", "The ``threshold_reached`` field."
   "default_dst_action", "``string``", "No", "No", "The ``default_dst_action`` field. Possible values: ``allow_all``, ``reject_all``."
   "media_encryption_mode", "``string``", "No", "No", "The ``media_encryption_mode`` field. Possible values: ``disabled``, ``srtp_sdes``, ``srtp_dtls``, ``zrtp``."
   "authentication_method.type", "``string``", "No", "No", "The ``authentication_method.type`` field. Possible values: ``credentials_and_ip``, ``ip_only``, ``twilio``."
   "emergency_enable_all", "``boolean``", "No", "No", "The ``emergency_enable_all`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "name", "The ``name`` field."
   "created_at", "The ``created_at`` field."
   "allow_any_did_as_cli", "The ``allow_any_did_as_cli`` field."
   "threshold_reached", "The ``threshold_reached`` field."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`DID Object <did_object_v34>`"
   "emergency_dids", "Emergency DID relationship data."

Object Relationships
--------------------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`DID Object <did_object_v34>`"
   "emergency_dids", "Emergency DID relationship data."

Example
=======

.. tabs::

   .. tab:: List outbound trunks

      .. http:example:: curl

         GET /v3/voice_out_trunks HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "03813615-da15-4e3b-8e0a-3ea64b2585de",
               "type": "voice_out_trunks",
               "attributes": {
                 "name": "Outbound trunk Name",
                 "allowed_rtp_ips": [
                   "0.0.0.0/0"
                 ],
                 "authentication_method": {
                   "type": "credentials_and_ip",
                   "attributes": {
                     "allowed_sip_ips": [
                       "0.0.0.0/0"
                     ],
                     "tech_prefix": null,
                     "username": "554******",
                     "password": "fqe******"
                   }
                 },
                 "allow_any_did_as_cli": true,
                 "status": "active",
                 "on_cli_mismatch_action": "send_original_cli",
                 "capacity_limit": 100,
                 "threshold_reached": false,
                 "threshold_amount": "10000.0",
                 "media_encryption_mode": "disabled",
                 "default_dst_action": "allow_all",
                 "dst_prefixes": [],
                 "emergency_enable_all": false,
                 "force_symmetric_rtp": false,
                 "rtp_ping": false,
                 "rtp_timeout": 30,
                 "callback_url": null,
                 "created_at": "2025-04-02T10:00:00.000Z",
                 "external_reference_id": null
               },
               "relationships": {
                 "dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/dids"
                   }
                 },
                 "emergency_dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/emergency_dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/emergency_dids"
                   }
                 }
               }
             },
             {
               "id": "cf2e6377-fcaa-4416-8c8e-acd5f31a427f",
               "type": "voice_out_trunks",
               "attributes": {
                 "name": "Outbound trunk Name",
                 "allowed_rtp_ips": [
                   "198.51.100.1/32"
                 ],
                 "authentication_method": {
                   "type": "ip_only",
                   "attributes": {
                     "allowed_sip_ips": [
                       "198.51.100.1/32"
                     ],
                     "tech_prefix": null
                   }
                 },
                 "allow_any_did_as_cli": true,
                 "status": "active",
                 "on_cli_mismatch_action": "send_original_cli",
                 "capacity_limit": 100,
                 "threshold_reached": false,
                 "threshold_amount": "10000.0",
                 "media_encryption_mode": "disabled",
                 "default_dst_action": "allow_all",
                 "dst_prefixes": [],
                 "emergency_enable_all": true,
                 "force_symmetric_rtp": false,
                 "rtp_ping": false,
                 "rtp_timeout": 30,
                 "callback_url": null,
                 "created_at": "2025-04-02T10:00:00.000Z",
                 "external_reference_id": null
               },
               "relationships": {
                 "dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/dids"
                   }
                 },
                 "emergency_dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/emergency_dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/emergency_dids"
                   }
                 }
               }
             },
             {
               "id": "14a0b7fb-845a-44d9-a7dc-ac1620f21e42",
               "type": "voice_out_trunks",
               "attributes": {
                 "name": "Outbound trunk Name",
                 "allowed_rtp_ips": null,
                 "authentication_method": {
                   "type": "twilio",
                   "attributes": {
                     "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                   }
                 },
                 "allow_any_did_as_cli": true,
                 "status": "active",
                 "on_cli_mismatch_action": "send_original_cli",
                 "capacity_limit": 100,
                 "threshold_reached": false,
                 "threshold_amount": "10000.0",
                 "media_encryption_mode": "disabled",
                 "default_dst_action": "allow_all",
                 "dst_prefixes": [],
                 "emergency_enable_all": false,
                 "force_symmetric_rtp": false,
                 "rtp_ping": false,
                 "rtp_timeout": 30,
                 "callback_url": null,
                 "created_at": "2025-04-02T10:00:00.000Z",
                 "external_reference_id": null
               },
               "relationships": {
                 "dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/dids"
                   }
                 },
                 "emergency_dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/emergency_dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/emergency_dids"
                   }
                 }
               }
             }
           ],
           "meta": {
             "total_records": 3,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/voice_out_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/voice_out_trunks?page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab:: Include emergency_dids

      .. http:example:: curl

         GET /v3/voice_out_trunks?include=emergency_dids HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "91f7bcb4-3278-433b-9de1-5e6f4131fd4d",
               "type": "voice_out_trunks",
               "attributes": {
                 "name": "Outbound trunk with emergency DID",
                 "allowed_rtp_ips": [
                   "198.51.100.0/24"
                 ],
                 "authentication_method": {
                   "type": "credentials_and_ip",
                   "attributes": {
                     "allowed_sip_ips": [
                       "198.51.100.0/24"
                     ],
                     "tech_prefix": null,
                     "username": "9q2******",
                     "password": "6zm******"
                   }
                 },
                 "allow_any_did_as_cli": true,
                 "status": "active",
                 "on_cli_mismatch_action": "send_original_cli",
                 "capacity_limit": 75,
                 "threshold_reached": false,
                 "threshold_amount": "3000.0",
                 "media_encryption_mode": "disabled",
                 "default_dst_action": "allow_all",
                 "dst_prefixes": [],
                 "emergency_enable_all": false,
                 "force_symmetric_rtp": false,
                 "rtp_ping": false,
                 "rtp_timeout": 30,
                 "callback_url": null,
                 "created_at": "2025-04-02T10:00:00.000Z",
                 "external_reference_id": null
               },
               "relationships": {
                 "dids": {
                   "links": {
                     "self": "https://api.didww.com/v3/voice_out_trunks/91f7bcb4-3278-433b-9de1-5e6f4131fd4d/relationships/dids",
                     "related": "https://api.didww.com/v3/voice_out_trunks/91f7bcb4-3278-433b-9de1-5e6f4131fd4d/dids"
                   }
                 },
                 "emergency_dids": {
                   "data": [
                     {
                       "type": "dids",
                       "id": "0b5d4ca6-7002-4f19-a678-f5be95538e9b"
                     }
                   ]
                 }
               }
             }
           ],
           "included": [
             {
               "id": "0b5d4ca6-7002-4f19-a678-f5be95538e9b",
               "type": "dids",
               "attributes": {
                 "number": "12125550123",
                 "emergency_enabled": true
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           }
         }


.. |br| raw:: html

   <br />

=====================
Update Outbound Trunk
=====================

Updates an outbound trunk.

In version ``2026-04-16``, customers can update outbound trunks through the API even if the Outbound feature is not enabled on the account.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/voice_out_trunks/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique identifier of the outbound trunk."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "No", "No", "The outbound trunk name."
   "external_reference_id", "``string``", "Yes", "No", "Optional identifier for the outbound trunk in the customer's external system. Maximum length is 100 characters."
   "allowed_rtp_ips", "Array of ``strings``", "Yes", "No", "Allowed RTP IP addresses for media traffic. Required when changing ``authentication_method.type`` to ``credentials_and_ip``."
   "authentication_method", "``object``", "No", "No", "Authentication method object. Supported PATCH target types are ``credentials_and_ip`` and ``twilio``. ``ip_only`` may be returned by ``GET`` endpoints but cannot be set through ``PATCH``."
   "on_cli_mismatch_action", "``string``", "No", "No", "Possible values: |br| ``send_original_cli`` - pass the original ``From`` header value from your system to the destination without modification. |br| ``reject_call`` - reject the call if the ``From`` header value does not match any DID allowed on the trunk. |br| ``replace_cli`` - replace the CLI with one of the DIDs allowed on the trunk."
   "capacity_limit", "``integer``", "Yes", "No", "The capacity limit of the outbound trunk. Allowed values from 0 to 32767."
   "allow_any_did_as_cli", "``boolean``", "No", "No", "When set to ``true``, all eligible DIDs can be used as CLI and the ``dids`` relationship must not contain explicit DIDs."
   "status", "``string``", "No", "No", "Possible values: |br| ``active`` - the trunk can be used for outbound traffic. |br| ``blocked`` - outbound traffic on the trunk is blocked."
   "threshold_amount", "``string``", "Yes", "No", "The outbound trunk 24-hour threshold limit. Can be from 0.0 to 100000.0."
   "default_dst_action", "``string``", "No", "No", "Possible values: |br| ``allow_all`` - allow calls to all destinations except the prefixes listed in ``dst_prefixes``. |br| ``reject_all`` - s to all destinations except the prefixes listed in ``dst_prefixes``."
   "dst_prefixes", "Array of ``strings``", "Yes", "No", "The destination prefixes allowed or rejected based on ``default_dst_action``."
   "emergency_enable_all", "``boolean``", "No", "No", "Allows all eligible DIDs to be used for emergency calling on the trunk."
   "media_encryption_mode", "``string``", "No", "No", "Media encryption mode. Possible values: |br| ``disabled`` - media encryption is turned off. |br| ``srtp_sdes`` - use SRTP encryption with SDES key exchange. |br| ``srtp_dtls`` - use SRTP encryption with DTLS key exchange. |br| ``zrtp`` - use SRTP encryption with ZRTP key exchange."
   "callback_url", "``string``", "Yes", "No", "Can be ``null`` or a valid HTTP(S) URL."
   "force_symmetric_rtp", "``boolean``", "No", "No", "Enables symmetric RTP / COMEDIA mode."
   "rtp_ping", "``boolean``", "No", "No", "Enables RTP ping after the call is connected."
   "rtp_timeout", "``integer``", "Yes", "No", "Disconnects the call if RTP packets do not arrive within the specified time. Supported values are from 30 to 600 seconds."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`DIDs <dids_v34>`", "The DID numbers explicitly allowed as CLI when ``allow_any_did_as_cli`` is ``false``."
   "emergency_dids", ":ref:`DIDs <dids_v34>`", "The DID numbers explicitly enabled for emergency calling when ``emergency_enable_all`` is ``false``."

Authentication Method
---------------------

Supported authentication method types:

- ``credentials_and_ip`` - uses SIP credentials together with allowed IP addresses.
- ``twilio`` - uses a Twilio Account SID for authentication.
- ``ip_only`` - may be returned by ``GET`` endpoints, but ``PATCH`` does not allow changing ``authentication_method.type`` to ``ip_only``.

.. note::
   After changing the authentication type, the previous authentication attributes are cleared.

Authentication Method Attributes by Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. tabs::

   .. tab:: credentials_and_ip

      .. csv-table::
         :header: "Name", "Type", "Nullable", "Is Required?", "Description"

         "allowed_sip_ips", "Array of ``strings``", "No", "Yes", "The allowed originating SIP IPs."
         "tech_prefix", "``string``", "Yes", "No", "An optional technical prefix added before the destination number. The maximum length is 8 characters and only digits and ``#`` are supported."

   .. tab:: twilio

      .. csv-table::
         :header: "Name", "Type", "Nullable", "Is Required?", "Description"

         "twilio_account_sid", "``string``", "No", "Yes", "The Twilio Account SID. It is a 34-character identifier of the Twilio account."

Examples
========

.. tabs::

   .. tab:: Switch ip_only to twilio

      .. http:example:: curl

         PATCH /v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "id": "cf2e6377-fcaa-4416-8c8e-acd5f31a427f",
             "type": "voice_out_trunks",
             "attributes": {
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "allowed_rtp_ips": null
             }
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "cf2e6377-fcaa-4416-8c8e-acd5f31a427f",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": null,
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 300,
               "allow_any_did_as_cli": false,
               "status": "blocked",
               "threshold_reached": false,
               "threshold_amount": "1000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": ["23", "45"],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": true,
               "rtp_ping": true,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: Switch twilio to credentials_and_ip

      .. http:example:: curl

         PATCH /v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "id": "14a0b7fb-845a-44d9-a7dc-ac1620f21e42",
             "type": "voice_out_trunks",
             "attributes": {
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null
                 }
               }
             }
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "14a0b7fb-845a-44d9-a7dc-ac1620f21e42",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null,
                   "username": "554******",
                   "password": "fqe******"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: Switch credentials_and_ip to twilio

      .. http:example:: curl

         PATCH /v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "id": "03813615-da15-4e3b-8e0a-3ea64b2585de",
             "type": "voice_out_trunks",
             "attributes": {
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "allowed_rtp_ips": null
             }
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "03813615-da15-4e3b-8e0a-3ea64b2585de",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": null,
               "authentication_method": {
                 "type": "twilio",
                 "attributes": {
                   "twilio_account_sid": "AC39347AF064AF97E1682C3B7332DAAEE6"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/03813615-da15-4e3b-8e0a-3ea64b2585de/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: Switch ip_only to credentials_and_ip

      .. http:example:: curl

         PATCH /v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "id": "cf2e6377-fcaa-4416-8c8e-acd5f31a427f",
             "type": "voice_out_trunks",
             "attributes": {
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null
                 }
               }
             }
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "cf2e6377-fcaa-4416-8c8e-acd5f31a427f",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk Name",
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null,
                   "username": "554******",
                   "password": "fqe******"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_all",
               "dst_prefixes": [],
               "emergency_enable_all": true,
               "media_encryption_mode": "disabled",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/cf2e6377-fcaa-4416-8c8e-acd5f31a427f/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: Update selected emergency DIDs

      .. http:example:: curl

         PATCH /v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "id": "9c91f03e-8796-4e6a-8c12-00e4f334f9b2",
             "type": "voice_out_trunks",
             "attributes": {
               "emergency_enable_all": false
             },
             "relationships": {
               "emergency_dids": {
                 "data": [
                   {
                     "id": "7158ac26-392f-47d1-89ab-c8b3f5ec05d9",
                     "type": "dids"
                   },
                   {
                     "id": "67a90c09-1bff-4bc3-a35e-116fda2b0d22",
                     "type": "dids"
                   }
                 ]
               }
             }
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "9c91f03e-8796-4e6a-8c12-00e4f334f9b2",
             "type": "voice_out_trunks",
             "attributes": {
               "name": "Outbound trunk for emergency DIDs",
               "allowed_rtp_ips": [
                 "0.0.0.0/0"
               ],
               "authentication_method": {
                 "type": "credentials_and_ip",
                 "attributes": {
                   "allowed_sip_ips": [
                     "0.0.0.0/0"
                   ],
                   "tech_prefix": null,
                   "username": "554******",
                   "password": "fqe******"
                 }
               },
               "on_cli_mismatch_action": "send_original_cli",
               "capacity_limit": 100,
               "allow_any_did_as_cli": true,
               "status": "active",
               "threshold_reached": false,
               "threshold_amount": "10000.0",
               "default_dst_action": "allow_calls",
               "dst_prefixes": [],
               "emergency_enable_all": false,
               "media_encryption_mode": "disable",
               "force_symmetric_rtp": false,
               "rtp_ping": false,
               "rtp_timeout": 30,
               "callback_url": null,
               "created_at": "2025-04-02T10:00:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/relationships/dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/dids"
                 }
               },
               "emergency_dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/relationships/emergency_dids",
                   "related": "https://api.didww.com/v3/voice_out_trunks/9c91f03e-8796-4e6a-8c12-00e4f334f9b2/emergency_dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab:: Invalid change to ip_only

      .. http:example:: curl

         PATCH /v3/voice_out_trunks/14a0b7fb-845a-44d9-a7dc-ac1620f21e42 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         {
           "data": {
             "id": "14a0b7fb-845a-44d9-a7dc-ac1620f21e42",
             "type": "voice_out_trunks",
             "attributes": {
               "authentication_method": {
                 "type": "ip_only",
                 "attributes": {
                   "allowed_sip_ips": [
                     "198.51.100.1/32"
                   ],
                   "tech_prefix": null
                 }
               },
               "allowed_rtp_ips": [
                 "198.51.100.1/32"
               ]
             }
           }
         }

         HTTP/1.1 422 Unprocessable Content
         Content-Type: application/vnd.api+json

         {
           "errors": [
             {
               "title": "is not allowed for update",
               "detail": "type - is not allowed for update",
               "code": "100",
               "source": {
                 "pointer": "/data/attributes/authentication_method/type"
               },
               "status": "422"
             }
           ]
         }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "422", "No", ":ref:`Validation Error Object <api_validation_error_object>`"
   "400", "No", ":ref:`Bad Request <api_bad_request>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

.. _voice_out_trunk_object_v34:

======================
Outbound Trunk Object
======================

JSON:API object with type ``voice_out_trunks``.

Authentication data is returned only inside ``data.attributes.authentication_method``.

Request
=======

URI Parameters
--------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique identifier of the outbound trunk."

Data Attributes
---------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "The outbound trunk name."
   "external_reference_id", "``string``", "Optional identifier for the outbound trunk in the customer's external system. Maximum length is 100 characters."
   "allowed_rtp_ips", "Array of ``strings``", "Allowed RTP IP addresses for media traffic."
   "on_cli_mismatch_action", "``string``", "The action applied when the CLI does not match the allowed DID list. Possible values: |br| ``send_original_cli`` - pass the original ``From`` header value from your system to the destination without modification. |br| ``reject_call`` - reject the call if the ``From`` header value does not match any DID allowed on the trunk. |br| ``replace_cli`` - replace the CLI with one of the DIDs allowed on the trunk."
   "capacity_limit", "``integer``", "The capacity limit of the outbound trunk."
   "allow_any_did_as_cli", "``boolean``", "When set to ``true``, any eligible DID can be used as CLI for the trunk."
   "status", "``string``", "The status of the outbound trunk. Possible values: |br| ``active`` - the trunk can be used for outbound traffic. |br| ``blocked`` - outbound traffic on the trunk is blocked."
   "threshold_reached", "``boolean``", "Indicates whether the 24-hour threshold amount has been reached."
   "threshold_amount", "``string``", "The 24-hour threshold limit."
   "default_dst_action", "``string``", "The default destination action. Possible values: |br| ``allow_all`` - allow calls to all destinations except the prefixes listed in ``dst_prefixes``. |br| ``reject_all`` - reject calls to all destinations except the prefixes listed in ``dst_prefixes``."
   "dst_prefixes", "Array of ``strings``", "The destination prefixes allowed or rejected based on ``default_dst_action``."
   "emergency_enable_all", "``boolean``", "When set to ``true``, all eligible DIDs of the account can be used for emergency calling on this trunk."
   "media_encryption_mode", "``string``", "Media encryption mode. Possible values: |br| ``disabled`` - media encryption is turned off. |br| ``srtp_sdes`` - use SRTP encryption with SDES key exchange. |br| ``srtp_dtls`` - use SRTP encryption with DTLS key exchange. |br| ``zrtp`` - use SRTP encryption with ZRTP key exchange."
   "callback_url", "``string``", "The callback URI. Can be ``null`` or a valid HTTP(S) URL."
   "force_symmetric_rtp", "``boolean``", "Enables symmetric RTP / COMEDIA mode."
   "rtp_ping", "``boolean``", "When enabled, DIDWW sends an empty RTP packet after call establishment."
   "rtp_timeout", "``integer``", "Disconnects the call if RTP packets do not arrive within the specified time. Supported values are from 30 to 600 seconds."
   "created_at", "``date&time``", "The date and time when the outbound trunk was created."
   "authentication_method", "``object``", "Authentication method object. See :ref:`outbound_trunk_authentication_method_v34`."

.. _outbound_trunk_authentication_method_v34:

Authentication Method
---------------------

The outbound trunk authentication is returned in the ``authentication_method`` attribute.

Supported authentication method types:

- ``credentials_and_ip`` - uses SIP credentials together with allowed IP addresses.
- ``ip_only`` - uses allowed IP addresses only.
- ``twilio`` - uses a Twilio Account SID for authentication.

Authentication Method Attributes by Type
----------------------------------------

The following attributes are part of the ``authentication_method`` object:

.. tabs::

   .. tab:: credentials_and_ip

      .. csv-table::
         :header: "Name", "Type", "Description"

         "allowed_sip_ips", "Array of ``strings``", "The allowed originating SIP IPs."
         "tech_prefix", "``string``", "An optional technical prefix added before the destination number. The maximum length is 8 characters and only digits and ``#`` are supported."
         "username", "``string``", "The digest authentication username."
         "password", "``string``", "The digest authentication password."

   .. tab:: ip_only

      .. csv-table::
         :header: "Name", "Type", "Description"

         "allowed_sip_ips", "Array of ``strings``", "The allowed originating SIP IPs."
         "tech_prefix", "``string``", "An optional technical prefix added before the destination number. The maximum length is 8 characters and only digits and ``#`` are supported."

   .. tab:: twilio

      .. csv-table::
         :header: "Name", "Type", "Description"

         "twilio_account_sid", "``string``", "The Twilio Account SID. It is a 34-character identifier of the Twilio account."

Object Relationships
--------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "dids", "to-many", ":ref:`DID Object <did_object_v34>`"
   "emergency_dids", "to-many", "DIDs assigned for emergency calling on the outbound trunk."


.. |br| raw:: html

   <br />

.. _voice_out_regenerate_credentials_v34:

======================================
Outbound Trunk Regenerate Credentials
======================================

Regenerates the username and password for an outbound trunk that uses the ``credentials_and_ip`` authentication method.

.. note::
    - The endpoint is relevant only for trunks that use ``credentials_and_ip`` authentication.
    - ``POST /v3/voice_out_trunk_regenerate_credentials`` is available in version ``2026-04-16`` even when the customer does not have the Outbound feature enabled.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/voice_out_trunk_regenerate_credentials``

Request Body Relationships
--------------------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "voice_out_trunk", ":ref:`Outbound Trunk Object <voice_out_trunk_object_v34>`", "The outbound trunk whose credentials should be regenerated."

Example
=======

.. tabs::

   .. tab:: Regenerate Credentials

    .. http:example:: curl

        POST /v3/voice_out_trunk_regenerate_credentials HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "type": "voice_out_trunk_regenerate_credentials",
            "relationships": {
              "voice_out_trunk": {
                "data": {
                  "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
                  "type": "voice_out_trunks"
                }
              }
            }
          }
        }

        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "457bf47d-446d-41cd-91c3-dfbda7bf0753",
            "type": "voice_out_trunk_regenerate_credentials"
          },
          "meta": {
            "api_version": "2026-04-16"
          }
        }



.. |br| raw:: html

   <br />

.. _shared_capacity_groups_v34:

=====================
Shared Capacity Group
=====================

.. note::

    To get familiar with Capacity and its options, please read this article: :ref:`Flexible Capacity <flexible_capacity>`

Returns a list of the Capacity Groups assigned to a Capacity Pool. Allows to create, edit or delete a shared capacity group. 

Supported methods: ``GET``,  ``POST``, ``PATCH``, ``DELETE``. 

.. toctree::
  :maxdepth: 1
  
  get-shared-capacity-group.rst
  get-shared-capacity-groups.rst
  create-shared-capacity-group.rst
  update-shared-capacity-group.rst
  delete-shared-capacity-group.rst
  shared-capacity-group-object.rst
  
  
  



=========================
Get Shared Capacity Group
=========================

Returns a single Channels Group.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/shared_capacity_groups/``

.. note:: For all returned data attributes, see :doc:`Shared Capacity Group Object <shared-capacity-group-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number allocated to this Shared Capacity Group."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`A list of Shared Capacity Group objects <did_object_v34>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample group",
              "shared_channels_count": 3,
              "created_at": "2018-06-19T11:41:21.644Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }
        
   .. tab:: Include DIDs
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e?include=dids HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample group",
              "shared_channels_count": 3,
              "created_at": "2018-06-19T11:41:21.644Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                },
                "data": [
                  {
                    "type": "dids",
                    "id": "44957076-778a-4802-b60c-d22db0cda284"
                  }
                ]
              }
            },
            "included": [
              {
                "id": "44957076-778a-4802-b60c-d22db0cda284",
                "type": "dids",
                "attributes": {
                  "blocked": false,
                  "capacity_limit": 1,
                  "description": "string",
                  "terminated": false,
                  "awaiting_registration": false,
                  "number": "437xxxxxxxxx",
                  "expires_at": "2017-06-25T08:21:41.795Z",
                  "channels_included_count": 2,
                  "created_at": "2017-06-25T08:21:41.795Z",
                  "pending_removal": false,
                  "dedicated_channels_count": 0
                },
                "relationships": {
                  "did_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/did_group",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/did_group"
                    }
                  },
                  "order": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/order",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/order"
                    }
                  },
                  "voice_in_trunk": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk"
                    }
                  },
                  "voice_in_trunk_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk_group",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk_group"
                    }
                  },
                  "capacity_pool": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/capacity_pool",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/capacity_pool"
                    }
                  },
                  "shared_capacity_group": {
                    "links": {
                      "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/shared_capacity_group",
                      "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/shared_capacity_group"
                    }
                  }
                }
              }
            ]
          }
        }
        
   .. tab:: Include Capacity Pool
   
     .. http:example:: curl
     
        GET /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e?include=capacity_pool HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]    
  
  
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample group",
              "shared_channels_count": 3,
              "created_at": "2018-06-19T11:41:21.644Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                },
                "data": {
                  "type": "capacity_pools",
                  "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            },
            "included": [
              {
                "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
                "type": "capacity_pools",
                "attributes": {
                  "name": "Extended",
                  "renew_date": "2018-07-21",
                  "total_channels_count": 10,
                  "unassigned_channels_count": 4,
                  "assigned_channels_count": 6,
                  "minimum_limit": 5,
                  "minimum_qty_per_order": 1,
                  "nrc": "0.0",
                  "mrc": "25.0",
                  "metered_rate": "0.02"
                },
                "relationships": {
                  "countries": {
                    "links": {
                      "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                      "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                    }
                  },
                  "shared_capacity_groups": {
                    "links": {
                      "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                      "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                    }
                  },
                  "qty_based_pricings": {
                    "links": {
                      "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                      "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                    }
                  }
                }
              }
            ]
          }
        }      
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



=============================
Create Shared Capacity Groups
=============================

Creates a Shared Capacity Group.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/shared_capacity_groups``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "False", "Yes", "Unique name of Shared Capacity Group."
   "external_reference_id", "``string``", "True", "No", "Optional identifier for the shared capacity group in the customer's external system. Maximum length is 100 characters."
   "shared_channels_count", "``integer``", "False", "No", "Unassigned channels quantity to assign to the Shared Capacity Group from the Capacity Pool."
   "metered_channels_count", "``integer``", "False", "No", "Metered channels quantity to assign to the Shared Capacity Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`To Many <api_relationships>`", "Linkage for included dids."
   "capacity_pool", ":ref:`To one <api_relationships>`", "Linkage for included capacity_pool."

Examples
========

.. tabs::

   .. tab:: Simple Create
   
     .. http:example:: curl
   
        POST /v3/shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "metered_channels_count": 5,
              "shared_channels_count": 3
            },
            "relationships": {
              "capacity_pool": {
                "data": {
                  "type": "capacity_pools",
                  "id": "1e9e4362-bc5c-47f3-a2bb-c17afa66f3fa"
                }
              }
            }
          }
        }

     
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }
        
   .. tab:: Create and Assign DIDs
   
     .. http:example:: curl
   
        POST /v3/shared_capacity_groups?include=dids HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "metered_channels_count": 5,
              "shared_channels_count": 3
            },
            "relationships": {
              "capacity_pool": {
                "data": {
                  "type": "capacity_pools",
                  "id": "1e9e4362-bc5c-47f3-a2bb-c17afa66f3fa"
                }
              },
              "dids": {
                "data": [
                  {
                    "type": "dids",
                    "id": "091b6984-07f7-4eca-a42c-f1856248d646"
                  },
                  {
                    "type": "dids",
                    "id": "88b0e9a1-5d8e-4737-8f31-43f0b2aa2861"
                  }
                ]
              }
            }
          }
        }

        
        HTTP/1.1 201 Created
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Sample Capacity Group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        } 
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



============================
Delete Shared Capacity Group
============================

Deletes a Shared Capacity Group.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/shared_capacity_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number allocated to this Shared Capacity Group."

Example
=======

.. http:example:: curl

    DELETE /v3/shared_capacity_groups/1156df17-bcea-4c9a-9c1d-29320e288c03 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
        
        
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json

                

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 



==========================
Get Shared Capacity Groups
==========================

Returns a collection of Shared Capacity Groups.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/shared_capacity_groups``

.. note:: For all returned data attributes, see :doc:`Shared Capacity Group Object <shared-capacity-group-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[shared_capacity_groups]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "dids", ":ref:`A list of Shared Capacity Group objects <did_object_v34>`"
   "capacity_pool", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "name", "``string``", "Yes", "Yes", "Shared Capacity Group ``name`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."
   "capacity_pool.id", "``string``", "Yes", "Yes", "The ``capacity_pool.id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "8a581244-de83-4c46-ac0a-32659279169e",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Mixed group",
                "shared_channels_count": 3,
                "created_at": "2018-06-20T08:48:47.811Z",
                "external_reference_id": null,
                "metered_channels_count": 5
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/dids"
                  }
                }
              }
            },
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Metered group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "external_reference_id": null,
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
   .. tab:: Include DIDs
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups?include=dids HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "8a581244-de83-4c46-ac0a-32659279169e",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Mixed group",
                "shared_channels_count": 3,
                "created_at": "2018-06-20T08:48:47.811Z",
                "external_reference_id": null,
                "metered_channels_count": 5
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/dids"
                  },
                  "data": [
                    {
                      "type": "dids",
                      "id": "44957076-778a-4802-b60c-d22db0cda284"
                    }
                  ]
                }
              }
            },
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Metered group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "external_reference_id": null,
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "44957076-778a-4802-b60c-d22db0cda284",
              "type": "dids",
              "attributes": {
                "blocked": false,
                "capacity_limit": 1,
                "description": "string",
                "terminated": false,
                "awaiting_registration": false,
                "number": "437xxxxxxxxx",
                "expires_at": "2017-06-25T08:21:41.795Z",
                "channels_included_count": 2,
                "created_at": "2017-06-25T08:21:41.795Z",
                "pending_removal": false,
                "dedicated_channels_count": 0
              },
              "relationships": {
                "did_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/did_group",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/did_group"
                  }
                },
                "order": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/order",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/order"
                  }
                },
                "voice_in_trunk": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk"
                  }
                },
                "voice_in_trunk_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/voice_in_trunk_group",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/voice_in_trunk_group"
                  }
                },
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/capacity_pool"
                  }
                },
                "shared_capacity_group": {
                  "links": {
                    "self": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/relationships/shared_capacity_group",
                    "related": "https://api.didww.com/v3/dids/44957076-778a-4802-b60c-d22db0cda284/shared_capacity_group"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }        
        
   .. tab:: Include Capacity Pool
   
     .. http:example:: curl
   
        GET /v3/shared_capacity_groups?include=capacity_pool HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": [
            {
              "id": "8a581244-de83-4c46-ac0a-32659279169e",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Mixed group",
                "shared_channels_count": 3,
                "created_at": "2018-06-20T08:48:47.811Z",
                "external_reference_id": null,
                "metered_channels_count": 5
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/capacity_pool"
                  },
                  "data": {
                    "type": "capacity_pools",
                    "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/8a581244-de83-4c46-ac0a-32659279169e/dids"
                  }
                }
              }
            },
            {
              "id": "dd2e8844-6a79-4673-ba1c-c8a4913884cc",
              "type": "shared_capacity_groups",
              "attributes": {
                "name": "Metered group",
                "shared_channels_count": 0,
                "created_at": "2018-06-19T11:41:21.644Z",
                "external_reference_id": null,
                "metered_channels_count": 30
              },
              "relationships": {
                "capacity_pool": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/capacity_pool",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/capacity_pool"
                  }
                },
                "dids": {
                  "links": {
                    "self": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/relationships/dids",
                    "related": "https://api.didww.com/v3/shared_capacity_groups/dd2e8844-6a79-4673-ba1c-c8a4913884cc/dids"
                  }
                }
              }
            }
          ],
          "included": [
            {
              "id": "b8db1d7c-f415-4530-a340-c774bcc1c55f",
              "type": "capacity_pools",
              "attributes": {
                "name": "Extended",
                "renew_date": "2018-07-21",
                "total_channels_count": 10,
                "unassigned_channels_count": 4,
                "assigned_channels_count": 6,
                "minimum_limit": 5,
                "minimum_qty_per_order": 1,
                "nrc": "0.0",
                "mrc": "25.0",
                "metered_rate": "0.02"
              },
              "relationships": {
                "countries": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/countries",
                    "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/countries"
                  }
                },
                "shared_capacity_groups": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/shared_capacity_groups",
                    "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/shared_capacity_groups"
                  }
                },
                "qty_based_pricings": {
                  "links": {
                    "self": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/relationships/qty_based_pricings",
                    "related": "https://api.didww.com/v3/capacity_pools/b8db1d7c-f415-4530-a340-c774bcc1c55f/qty_based_pricings"
                  }
                }
              }
            }
          ],
          "meta": {
            "total_records": 2
          },
          "links": {
            "first": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
            "last": "https://api.didww.com/v3/shared_capacity_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50"
          }
        }
        
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`"


.. _shared_capacity_group_object_v34:

============================
Shared Capacity Group Object
============================

Shared Capacity Group Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Shared Capacity Group name."
   "external_reference_id", "``string``", "Optional identifier for the shared capacity group in the customer's external system. Maximum length is 100 characters."
   "metered_channels_count", "``integer``", "Metered channels quantity in Shared Capacity Group."
   "shared_channels_count", "``integer``", "Shared channels quantity in Shared Capacity Group."
   "created_at", "``DateTime``", "Shared Capacity Group creation date and time."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "capacity_pool", "to-one", ":ref:`Capacity Pool Object <capacity_pool_object_v34>`. Returns the capacity pool linked to the shared capacity group."
   "dids", "to-many", ":ref:`DID Object <did_object_v34>`. Returns the DIDs linked to the shared capacity group."



=============================
Update Shared Capacity Groups
=============================

Updates a Shared Capacity Group.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/shared_capacity_groups/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"
   
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Nullable", "Is Required?", "Description"

   "name", "``string``", "False", "Yes", "Unique name of Shared Capacity Group."
   "external_reference_id", "``string``", "True", "No", "Optional identifier for the shared capacity group in the customer's external system. Maximum length is 100 characters."
   "shared_channels_count", "``integer``", "False", "No", "Unassigned channels quantity to assign to the Shared Capacity Group from the Capacity Pool."
   "metered_channels_count", "``integer``", "False", "No", "Metered channels quantity to assign to the Shared Capacity Group."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`To Many <api_relationships>`", "Linkage for included dids."
   "capacity_pool", ":ref:`To one <api_relationships>`", "Linkage for included capacity_pool."

Examples
========

.. tabs::

   .. tab:: Simple Update
   
     .. http:example:: curl
   
        PATCH /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group"
            }
          }
        }

     
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }

   .. tab:: Update and Assign DIDs

     .. http:example:: curl

        PATCH /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "relationships": {
              "dids": {
                "data": [
                  {
                    "type": "dids",
                    "id": "a2dcccdb-4c81-4d93-a174-26001ccfc13a"
                  },
                  {
                    "type": "dids",
                    "id": "fd345680-4a4e-40db-b2f2-f81651e3e2df"
                  }
                ]
              }
            }
          }
        }

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group",
              "shared_channels_count": 3,
              "created_at": "2023-03-28T18:25:38.415Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/62fa8ad9-21cc-48e1-933e-f2fe33740891/dids"
                }
              }
            }
          }
        }

   .. tab:: Update and Remove DIDs
   
     .. http:example:: curl
   
        PATCH /v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "relationships": {
              "dids": {
                "data": [
        
                ]
              }
            }
          }
        }

        
        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json
        
        {
          "data": {
            "id": "71afa2e2-8d46-4ea3-988d-aa112ed98b5e",
            "type": "shared_capacity_groups",
            "attributes": {
              "name": "Renamed group",
              "shared_channels_count": 3,
              "created_at": "2018-07-06T16:11:32.981Z",
              "external_reference_id": null,
              "metered_channels_count": 5
            },
            "relationships": {
              "capacity_pool": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/capacity_pool",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/capacity_pool"
                }
              },
              "dids": {
                "links": {
                  "self": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/relationships/dids",
                  "related": "https://api.didww.com/v3/shared_capacity_groups/71afa2e2-8d46-4ea3-988d-aa112ed98b5e/dids"
                }
              }
            }
          }
        }        

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "422","No",":ref:`Unprocessable Entity <api_validation_error_object>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _resources_summary_v34:

.. _didww_api_20260606:

=================================
API Resources Summary v2026-04-16
=================================

.. raw:: html

    <div class="postman-run-button"
    data-postman-action="collection/fork"
    data-postman-var-1="23329000-94fb7eaa-e6d9-48cb-913f-2d03976de8cc"
    data-postman-collection-url="entityId=23329000-94fb7eaa-e6d9-48cb-913f-2d03976de8cc&entityType=collection&workspaceId=c7e9c67d-ac71-4c91-a5ef-b12f6619f415"
    data-postman-param="env%5BDIDWW%20Sandbox%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoieW91ckRpZHd3QXBpS2V5IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoieW91ckRpZHd3QXBpS2V5Iiwic2Vzc2lvbkluZGV4IjoxfV0=">
    </div>
    <p></p>
    <script type="text/javascript">
    (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
    (n = o.createElement("script")),
    (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
    }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
    </script>

The DIDWW API allows you to perform an extensive set of actions such as querying the DID coverage and inventory, ordering and configuring phone numbers and services, setting capacity and creating SIP trunks by using the following methods:

 * **GET** - Fetch data, where the data can be a collection or resources or an individual resource
 * **POST** - Create a new resource
 * **PATCH** - Update an existing resource
 * **DELETE** - Remove an existing resource

.. csv-table::
   :header: "API Call", "Method/s", "Details"

   ":ref:`balance <balance_v34>`","GET", "Returns the prepaid balance as well as the available credit on the account."
   ":ref:`cities <cities_v34>`", "GET", "Returns a list of cities included in the current DIDWW inventory, or returns the details of a specific city."
   ":ref:`countries <countries_v34>`","GET","Returns a list of countries included in the current DIDWW inventory, or return the details of a specific country."
   ":ref:`dids <dids_v34>`","GET, PATCH","Returns a list of all of the DIDs owned by an account or the details for a single DID, or modify the settings for a single DID owned by an account."
   ":ref:`did_history <did_history_v34>`","GET","Returns a list of DID history records or a single DID history record."
   ":ref:`did_groups <did_groups_v34>`","GET","Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code."
   ":ref:`did_group_types <did_group_types_v34>`", "GET","Returns a list of the various types of DIDs supported by DIDWW (for example, mobile, toll-free, SMS)."
   ":ref:`capacity_pools <capacity_pools_v34>`","GET, PATCH","Returns a list of the Capacity Pools which include information about channels quantity, supported Countries, Shared Capacity Groups."
   ":ref:`shared_capacity_groups <shared_capacity_groups_v34>`","GET, POST, PATCH, DELETE","Returns a list of the Capacity Groups assigned to Capacity Pool."
   ":ref:`export <export_v34>`","GET, POST, PATCH","Returns call detail record (CDR) exports, creates a new export, or updates an existing export."
   ":ref:`orders <orders_v34>`","GET, POST, PATCH, DELETE","Returns a list of the orders previously placed in this account, creates a new order, updates an existing order, or deletes an order."
   ":ref:`regions <regions_v34>`","GET","Returns a list of regions (for example, states within the USA) included in the current DIDWW inventory."
   ":ref:`voice_in_trunks <voice_in_trunks_v34>`","GET, POST, PATCH, DELETE","Returns a list of all of the voice in trunks configured by this account, create a new trunk, modify the settings of an existing trunk, or delete a trunk."
   ":ref:`voice_out_trunks <voice_out_trunks_v34>`","GET, POST, PATCH, DELETE","Returns a list of all voice out trunks configured by this account, create a new trunk, modify the existing trunk, or delete a trunk."
   ":ref:`emergency_calling_services <emergency_calling_services_v34>`","GET, DELETE","Returns a list of Emergency Calling Services configured by the account, returns the details of a single service, or cancels an existing service."
   ":ref:`voice_in_trunk_groups <voice_in_trunk_groups_v34>`","GET, POST, PATCH, DELETE","Returns the details of a voice in trunk group, create a new trunk group, modify trunk group settings, or delete a trunk group."
   ":ref:`available_dids <available_dids_v34>`","GET","Returns a list of available DID numbers in the current DIDWW coverage."
   ":ref:`did_reservation <did_reservation_v34>`","GET, POST, DELETE","Returns a list or a single DID reservations for the account."
   ":ref:`address_verifications <address_verifications_v34>`","GET, POST, PATCH","Returns a list of address verifications, the details of a single address verification, creates a new address verification, or updates an existing address verification."
   ":ref:`addresses <addresses_v34>`","GET, POST, PATCH, DELETE","Returns the details of a address, create a new address, modify address settings, or delete an address."
   ":ref:`encrypted_files <encrypted_files_v34>`","GET, POST, DELETE","Returns the details of a encrypted file, create a new encrypted file, or delete an encrypted file."
   ":ref:`identities <identities_v34>`","GET, POST, PATCH, DELETE","Returns the details of a identity, create a new identity, modify identity settings, or delete an identity."
   ":ref:`permanent_supporting_documents <permanent_documents_v34>`","GET, POST, DELETE","Returns a list of permanent supporting documents or the details of a single permanent supporting document, creates a new permanent supporting document, or deletes a permanent supporting document."
   ":ref:`proof_types <proof_types_v34>`","GET","Returns a list or a single proof_types for the account."
   ":ref:`proofs <proofs_v34>`","GET, POST, DELETE","Returns a list of proofs or the details of a single proof, creates a new proof, or deletes a proof."
   ":ref:`address_requirements <address_requirements_v34>`","GET","Returns a list or a single address requirement for the account."
   ":ref:`emergency_requirements <emergency_requirements_v34>`","GET","Returns a list of emergency requirements for the account."
   ":ref:`emergency_requirement_validations <emergency_requirement_validations_v34>`","POST","Checks whether an address and / or identity is valid against an emergency requirement."
   ":ref:`emergency_verifications <emergency_verifications_v34>`","GET, POST, PATCH","Returns a list of Emergency Verifications, the details of a single Emergency Verification, creates a new Emergency Verification task, or updates an existing Emergency Verification."
   ":ref:`supporting_document_templates <supporting_document_template_v34>`","GET","Returns a list or a single supporting document templates for the account."
   ":ref:`areas <areas_v34>`","GET","Returns a list or a single regulatory area."
   ":ref:`nanpa_prefixes <nanpa_prefixes_v34>`","GET","Returns a list NANPA prefixes or a single NANPA prefix."


.. _address_verifications_object_v34:

============================
Address Verifications Object
============================

Address Verifications Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "service_description", "``string``", "The description of the verification task."
   "external_reference_id", "``string``", "Optional identifier for the verification task in the customer's external system. Maximum length is 100 characters."
   "callback_url", "``string``", "The HTTP or HTTPS endpoint to which events related to the verification task will be delivered."
   "callback_method", "``string``", "The HTTP method used for verification task events. Supported methods: ``post``, ``get``."
   "status", "``string``", "The current status of the verification task. Possible values: ``pending``, ``approved``, ``rejected``."
   "reference", "``string``", "The unique reference number for the verification task."
   "reject_reasons", "``array[string]``", "The reason(s) for verification rejection."
   "reject_comment", "``string``", "A detailed compliance comment for a rejected verification. Returns ``null`` when there is no rejection comment."
   "created_at", "``Date&Time``", "The date and time the verification task was created."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "address", "to-one", ":ref:`Addresses Object <addresses_object_v34>`. Returns the address linked to the verification task."
   "dids", "to-many", ":ref:`DID Object <did_object_v34>`. Returns the DIDs linked to the verification task."


.. |br| raw:: html

   <br />

===========================
Create Address Verification
===========================

Creates an Address Verification task and configures a callback to receive status updates. |br|
Supports linking DIDs, addresses, and optional supporting files.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/address_verifications``

URI Query Parameters
--------------------

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "service_description", "``string``", "No", "The description of verification task."
   "external_reference_id", "``string``", "No", "Optional identifier for the verification task in the customer's external system. Maximum length is 100 characters."
   "callback_url", "``string``", "No", "The HTTP or HTTPS endpoint to where events related to verification task will be delivered."
   "callback_method", "``string``", "No", "The HTTP Method used for verification task events. ``post`` and ``get`` are supported methods."

See :ref:`Callback details <callbacks_details_v34>` for information about **callback_url** and **callback_method**.

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "dids", ":ref:`DID <did_object_v34>`", "Specifies the ID of DID for verification task."
   "addresses", ":ref:`Addresses <addresses_object_v34>`", "Specifies the ID of Address for verification task."
   "onetime_files", ":ref:`Encrypted Files Object <encrypted_files_object_v34>`", "Specifies Onetime files for verification task."

Testing
=======

Confirm the correct functioning of your integration by simulating approvals and rejections in the **sandbox** environment.
This can be achieved by assigning specific testing values to the **id_number** attribute of the :ref:`Identity <identity_object_v34>`, which will be utilized when creating the Address Verification.
Refer to the table below for the available options.

.. csv-table::
   :header: "Action", "id_number value"

   "approve", "11111111-1111-1111-1111-111111111111"
   "reject", "22222222-2222-2222-2222-222222222222"

Examples
========

.. tabs::

   .. tab:: Create Address Verification

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "get"
                },
                "relationships": {
                  "dids": {
                    "data": [
                      {
                        "id": "b0c54164-03b9-42fa-b052-68a95bdab67b",
                        "type": "dids"
                      },
                      {
                        "id": "95e9d153-4881-4a6a-85a0-9b9e68f817eb",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "a1f03dae-ea44-4348-993f-ce1c68ca1c21",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6",
                    "type": "address_verifications",
                    "attributes": {
                        "service_description": null,
                        "callback_url": "http://example.com",
                        "callback_method": "get",
                        "status": "pending",
                        "reject_reasons": [],
                        "reject_comment": null,
                        "reference": "TTC-388920",
                        "created_at": "2023-02-27T09:01:04.275Z",
                        "external_reference_id": null
                    },
                    "relationships": {
                        "dids": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/dids",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/dids"
                            }
                        },
                        "address": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/address",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/address"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Create Address Verification with Service Description

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                "callback_url": "http://example.com",
                "callback_method": "get",
                "service_description": "string"
                },
                "relationships": {
                  "onetime_files": {
                    "data": [
                      {
                        "id": "96fb69e0-d5bb-4637-b740-28349f1a4274",
                        "type": "encrypted_files"
                      }
                    ]
                  },
                  "dids": {
                    "data": [
                      {
                        "id": "723ba6a6-ec10-45f5-b2ba-84be6a4e0eb2",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "f13240d5-d3cc-4c05-a529-fb63a0027118",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
                "type": "address_verifications",
                "attributes": {
                  "service_description": "string",
                  "callback_url": "http://example.com",
                  "callback_method": "get",
                  "status": "pending",
                  "reject_reasons": [],
                  "reject_comment": null,
                  "created_at": "2021-03-23T12:20:04.584Z",
                  "reference": "SHB-485120",
                  "external_reference_id": null
                },
                "relationships": {
                  "dids": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids",
                      "related": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids"
                    }
                  },
                  "address": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address",
                      "related": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

   .. tab:: Verification Error

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                    "type": "address_verifications",
                    "attributes": {
                    "callback_url": "http://example.com",
                    "callback_method": "get",
                    "service_description": "string"
                    },
                    "relationships": {
                      "onetime_files": {
                            "data": [
                              {
                                    "id": "606911e3-ae91-4717-8d16-39d85de906fc",
                                    "type": "encrypted_files"
                              }
                            ]
                      },
                      "dids": {
                            "data": [
                              {
                                    "id": "e750ea2f-b1a0-4cf7-887d-0cab23ee4138",
                                    "type": "dids"
                              }
                            ]
                      },
                      "address": {
                            "data": {
                              "id": "ef8bedc8-4e2a-4064-b2b2-e08270eabe1b",
                              "type": "addresses"
                            }
                      }
                    }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {"errors": [
                  {
                  "title": "one-time document is not needed",
                  "detail": "one-time document is not needed",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               },
                  {
                  "title": "service description is not needed",
                  "detail": "service description is not needed",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               }
            ]}

   .. tab:: Verification Error: Missing proofs

     .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "get"
                },
                "relationships": {
                  "dids": {
                    "data": [
                      {
                        "id": "dd769be0-d5ef-4c6f-b000-89cd2a780d7f",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "4f97a28d-d8be-4c00-bf72-df175e4d44c3",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {"errors": [
                  {
                  "title": "1 Identity Proof(s) (National ID, Passport) required",
                  "detail": "1 Identity Proof(s) (National ID, Passport) required",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               },
                  {
                  "title": "Following Supporting Document(s) required (Germany Registration Form)",
                  "detail": "Following Supporting Document(s) required (Germany Registration Form)",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               },
                  {
                  "title": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required",
                  "detail": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required",
                  "code": "100",
                  "source": {"pointer": "/data"},
                  "status": "422"
               }
            ]}

   .. tab:: Verification Error: Missing mandatory fields

    .. http:example:: curl

            POST /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "address_verifications",
                "attributes": {
                  "callback_url": "http://example.com",
                  "callback_method": "get"
                },
                "relationships": {
                  "dids": {
                    "data": [
                      {
                        "id": "a2eca370-0873-4b2e-b58b-3216ad3db98c",
                        "type": "dids"
                      }
                    ]
                  },
                  "address": {
                    "data": {
                      "id": "1703ec4d-2fc8-4965-b7d3-3645a2e90fac",
                      "type": "addresses"
                    }
                  }
                }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {
                "errors": [
                    {
                        "title": "Following mandatory fields are not filled in (Contact Email)",
                        "detail": "Following mandatory fields are not filled in (Contact Email)",
                        "code": "100",
                        "source": {
                            "pointer": "/data"
                        },
                        "status": "422"
                    }
                ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

========================
Get Address Verification
========================

Returns a single address verification status and reason if the verification was rejected.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/address_verifications/``

.. note:: For all returned data attributes, see :doc:`Address Verifications Object <address-verifications-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Address Verification."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "address", ":ref:`Addresses Object <addresses_object_v34>`"
   "dids", ":ref:`DID Object <did_object_v34>`"
   "dids.did_group", ":ref:`DID Group Object <did_group_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Approved Verification

     .. http:example:: curl

            GET /v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
                    "type": "address_verifications",
                    "attributes": {
                        "external_reference_id": null,
                        "service_description": null,
                        "callback_url": null,
                        "callback_method": null,
                        "status": "approved",
                        "reject_reasons": [],
                        "reject_comment": null,
                        "created_at": "2020-09-15T06:38:12.650Z",
                        "reference": "SHB-485120"
                    },
                    "relationships": {
                        "dids": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/dids",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/dids"
                            }
                        },
                        "address": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/address",
                                "related": "https://sandbox-api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/address"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Rejected Verification

     .. http:example:: curl

            GET /v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": {
                  "id": "48e72d60-1884-4997-8755-fd2ba9f307bd",
                  "type": "address_verifications",
                  "attributes": {
                     "external_reference_id": null,
                     "service_description": "string",
                     "callback_url": "http://192.0.2.10/test.php",
                     "callback_method": "get",
                     "status": "rejected",
                     "reject_reasons": [
                        "The proof of personal address is required",
                        "The DID cannot be used for the indicated service"
                     ],
                     "reject_comment": "Additional info from operator",
                     "reference": "VFG-606536",
                     "created_at": "2021-08-12T06:47:58.477Z"
                  },
                  "relationships": {
                     "dids": {
                        "links": {
                           "self": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/relationships/dids",
                           "related": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/dids"
                        }
                     },
                     "address": {
                        "links": {
                           "self": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/relationships/address",
                           "related": "https://sandbox-api.didww.com/v3/address_verifications/48e72d60-1884-4997-8755-fd2ba9f307bd/address"
                        }
                     }
                  }
               },
               "meta": {
                  "api_version": "2026-04-16"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 



.. |br| raw:: html

   <br />

=========================
Get Address Verifications
=========================

Returns the address verifications status and reasons if the verification was rejected.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/address_verifications``

.. note:: For all returned data attributes, see :doc:`Address Verifications Object <address-verifications-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[address_verifications]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "address", ":ref:`Addresses Object <addresses_object_v34>`"
   "dids", ":ref:`DID Object <did_object_v34>`"
   "dids.did_group", ":ref:`DID Group Object <did_group_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "address.id", "``string``", "Yes", "Yes", "The ``address.id`` field."
   "address.identity.id", "``string``", "Yes", "Yes", "The ``address.identity.id`` field."
   "status", "``string``", "No", "No", "The ``status`` field. Possible values: ``pending``, ``approved``, ``rejected``."
   "reference", "``string``", "No", "Yes", "The ``reference`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "created_at", "The ``created_at`` field."
   "external_reference_id", "The ``external_reference_id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

     .. http:example:: curl

            GET /v3/address_verifications HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": [
                  {
                        "id": "40c315d2-255c-410f-9af7-6b288c3f8ba4",
                        "type": "address_verifications",
                        "attributes": {
                           "external_reference_id": null,
                           "service_description": "testing",
                           "callback_url": null,
                           "callback_method": null,
                           "status": "rejected",
                           "reject_reasons": [
                              "The proof of personal address is required",
                              "The DID cannot be used for the indicated service"
                           ],
                           "reject_comment": "Additional info from operator",
                           "reference": "EGE-764403",
                           "created_at": "2021-03-22T06:24:58.295Z"
                        },
                        "relationships": {
                           "dids": {
                              "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/dids",
                                    "related": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/dids"
                              }
                           },
                           "address": {
                              "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/address",
                                    "related": "https://sandbox-api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/address"
                              }
                           }
                        }
                  }
               ],
               "meta": {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links": {
                  "first": "https://sandbox-api.didww.com/v3/address_verifications?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://sandbox-api.didww.com/v3/address_verifications?page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

   .. tab:: Filter by status

     .. http:example:: curl

            GET /v3/address_verifications?filter[status]=rejected HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "40c315d2-255c-410f-9af7-6b288c3f8ba4",
                  "type": "address_verifications",
                  "attributes":       {
                     "external_reference_id": null,
                     "service_description": "testing",
                     "callback_url": null,
                     "callback_method": null,
                     "status": "rejected",
                     "reject_reasons": [
                        "The proof of personal address is required",
                        "The DID cannot be used for the indicated service"
                     ],
                     "reject_comment": "Additional info from operator",
                     "reference": "EGE-764403",
                     "created_at": "2021-03-22T06:24:58.295Z"
                  },
                  "relationships":       {
                     "dids": {"links":          {
                        "self": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/dids",
                        "related": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/dids"
                     }},
                     "address": {"links":          {
                        "self": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/relationships/address",
                        "related": "https://api.didww.com/v3/address_verifications/40c315d2-255c-410f-9af7-6b288c3f8ba4/address"
                     }}
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_verifications?filter%5Bstatus%5D=rejected&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_verifications?filter%5Bstatus%5D=rejected&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

   .. tab:: Include dids

     .. http:example:: curl

            GET /v3/address_verifications?include=dids HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "9814cf4f-b472-4ea7-9275-565eb90be397",
                  "type": "address_verifications",
                  "attributes":       {
                     "service_description": null,
                     "callback_url": "http://192.0.2.10/test.php",
                     "callback_method": "get",
                     "status": "rejected",
                     "reject_reasons": [
                        "The proof of personal address is required",
                        "The DID cannot be used for the indicated service"
                     ],
                     "reject_comment": "Additional info from operator",
                     "reference": "XNH-144620",
                     "created_at": "2021-08-11T15:43:23.263Z"
                  },
                  "relationships":       {
                     "dids":          {
                        "links":             {
                           "self": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/relationships/dids",
                           "related": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/dids"
                        },
                        "data": [            {
                           "type": "dids",
                           "id": "9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc"
                        }]
                     },
                     "address": {"links":          {
                        "self": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/relationships/address",
                        "related": "https://api.didww.com/v3/address_verifications/9814cf4f-b472-4ea7-9275-565eb90be397/address"
                     }}
                  }
               }],
               "included": [   {
                  "id": "9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc",
                  "type": "dids",
                  "attributes":       {
                     "blocked": true,
                     "capacity_limit": 55,
                     "description": null,
                     "terminated": false,
                     "awaiting_registration": true,
                     "created_at": "2018-11-28T09:40:31.684Z",
                     "billing_cycles_count": null,
                     "number": "4921111111111",
                     "expires_at": "2021-08-19T17:32:21.390Z",
                     "channels_included_count": 2,
                     "dedicated_channels_count": 0
                  },
                  "relationships":       {
                     "did_group": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/did_group",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/did_group"
                     }},
                     "order": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/order",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/order"
                     }},
                     "voice_in_trunk": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/voice_in_trunk",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/voice_in_trunk"
                     }},
                     "voice_in_trunk_group": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/voice_in_trunk_group",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/voice_in_trunk_group"
                     }},
                     "capacity_pool": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/capacity_pool",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/capacity_pool"
                     }},
                     "shared_capacity_group": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/shared_capacity_group",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/shared_capacity_group"
                     }},
                     "address_verification": {"links":          {
                        "self": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/relationships/address_verification",
                        "related": "https://api.didww.com/v3/dids/9e7e20b9-6142-4d5c-a001-cafa0ff9d7cc/address_verification"
                     }}
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_verifications?include=dids&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_verifications?include=dids&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _address_verifications_v34:

=====================
Address Verifications
=====================

Returns a single or a list of Address Verifications in the account. Allows create a callback/webhook method to receive notifications associated with Verification Statuses.

Supported methods: ``GET``, ``POST``, ``PATCH``

.. toctree::
  :maxdepth: 1
  
  get-address-verification.rst
  get-address-verifications.rst
  create-address-verification.rst
  update-address-verification.rst
  address-verifications-object.rst
  
  
  


.. |br| raw:: html

   <br />

===========================
Update Address Verification
===========================

Update the settings of a single Address Verification owned by your account.

Only ``external_reference_id`` can be updated.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/address_verifications/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Address Verification."

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "external_reference_id", "``string``", "No", "Optional identifier for the verification task in the customer's external system. Maximum length is 100 characters."

Examples
========

.. tabs::

   .. tab:: Update external_reference_id

     .. http:example:: curl

            PATCH /v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
                "type": "address_verifications",
                "attributes": {
                  "external_reference_id": "test"
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
                "type": "address_verifications",
                "attributes": {
                  "external_reference_id": "test",
                  "service_description": null,
                  "callback_url": null,
                  "callback_method": null,
                  "status": "approved",
                  "reject_reasons": [],
                  "reject_comment": null,
                  "reference": "SHB-485120",
                  "created_at": "2020-09-15T06:38:12.650Z"
                },
                "relationships": {
                  "dids": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/dids",
                      "related": "https://api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/dids"
                    }
                  },
                  "address": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/relationships/address",
                      "related": "https://api.didww.com/v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e/address"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _addresses_object_v34:

================
Addresses Object
================

Addresses Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "city_name", "``string``", "City name of the address."
   "postal_code", "``string``", "Postal code of the address."
   "address", "``string``", "Full address."
   "description", "``string``", "Description of the address."
   "external_reference_id", "``string``", "Optional identifier for the address in the customer's external system. Maximum length is 100 characters."
   "verified", "``boolean``", "Displays if Address is verified."
   "created_at", "``Date&Time``", "Creation date and time of the address."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "identity", "to-one", ":ref:`Identity Object <identity_object_v34>`. Returns the identity assigned to the address."
   "country", "to-one", ":ref:`Country Object <country_object_v34>`. Returns the country assigned to the address."
   "proofs", "to-many", ":ref:`Proofs Object <proofs_object_v34>`. Returns the proofs assigned to the address."
   "area", "to-one", ":ref:`Area Object <area_object_v34>`. Returns the area assigned to the address."
   "city", "to-one", ":ref:`City Object <city_object_v34>`. Returns the city assigned to the address."


.. |br| raw:: html

   <br />

================
Create Addresses
================

Creates an Address that can be assigned to an Identity.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/addresses``

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Required", "Description"

   "city_name", "``string``", "Yes", "City name of the address."
   "postal_code", "``string``", "Yes", "Postal code of the address."
   "address", "``string``", "Yes", "Full address."
   "description", "``string``", "No", "The description of the address."
   "external_reference_id", "``string``", "No", "Optional identifier for the address in the customer's external system. Maximum length is 100 characters."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "countries", ":ref:`Countries <country_object_v34>`", "Specifies the country for the address."
   "identities", ":ref:`Identities <identity_object_v34>`", "Specifies the identity for the address."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch

     .. http:example:: curl

            POST /v3/addresses HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "addresses",
                "attributes": {
                  "city_name": "string",
                  "postal_code": "string",
                  "address": "string",
                  "description": "string"
                },
                "relationships": {
                  "identity": {
                    "data": {
                      "id": "6c832a1d-b19d-471b-b416-9b5bf2b6ef9d",
                      "type": "identities"
                    }
                  },
                  "country": {
                    "data": {
                      "id": "38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                    "type": "addresses",
                    "attributes": {
                        "city_name": "string",
                        "postal_code": "string",
                        "address": "string",
                        "description": "string",
                        "created_at": "2020-09-16T10:23:07.846Z",
                        "verified": false,
                        "external_reference_id": null
                    },
                    "relationships": {
                        "identity": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/identity",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/identity"
                            }
                        },
                        "country": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/country",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/country"
                            }
                        },
                        "proofs": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/proofs",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/proofs"
                            }
                        },
                        "area": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/area",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/area"
                            }
                        },
                        "city": {
                            "links": {
                                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/city",
                                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/city"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Invalid country.id Input

     .. http:example:: curl

            POST /v3/addresses HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "addresses",
                "attributes": {
                  "city_name": "Vilnius",
                  "postal_code": "LT80001",
                  "address": "Street 1",
                  "description": "yellow house"
                },
                "relationships": {
                  "identity": {
                    "data": {
                      "id": "6c832a1d-b19d-471b-b416-9b5bf2b6ef9d",
                      "type": "identities"
                    }
                  },
                  "country": {
                    "data": {
                      "id": "country_id_string",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {"errors": [{
               "title": "is invalid",
               "detail": "country - is invalid",
               "code": "100",
               "source": {"pointer": "/data/relationships/country"},
               "status": "422"
            }]}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



==============
Delete Address
==============

Deletes the address without restoration.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/addresses/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Addresses. "

Example
=======

.. http:example:: curl

    DELETE /v3/addresses/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "409","No",":ref:`Conflict <conflict_v1>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




===========
Get Address
===========

Returns a single Address in the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/addresses/``

.. note:: For all returned data attributes, see :doc:`Address Object <address-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Addresses."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "identity", ":ref:`Identities Object <identity_object_v34>`"
   "identity.country", ":ref:`Country Object <country_object_v34>`"
   "identity.proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "identity.proofs.proof_type", ":ref:`Proofs Object <proofs_object_v34>`"
   "identity.permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v34>`"
   "identity.permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "area", ":ref:`Area Object <area_object_v34>`"
   "city", ":ref:`City Object <city_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/addresses/0083c7f2-b030-491f-91b3-54597967ca38 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "54c92d8e-f135-4b55-ac48-748d44437509",
                "type": "addresses",
                "attributes": {
                    "city_name": "Dublin",
                    "postal_code": "Dublin 8",
                    "address": "10/13 Thomas Street",
                    "description": "My Business Address",
                    "created_at": "2020-09-14T07:29:41.413Z",
                    "verified": false,
                    "external_reference_id": null
                },
                "relationships": {
                    "identity": {
                        "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/identity",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/identity"
                        }
                    },
                    "country": {
                        "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/country",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/country"
                        }
                    },
                    "proofs": {
                        "links": {
                            "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/proofs",
                            "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/proofs"
                        }
                    },
                    "area": {
                      "links": {
                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/area",
                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/area"
                      }
                    },
                    "city": {
                      "links": {
                        "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/city",
                        "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/city"
                      }
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




=============
Get Addresses
=============

Returns a list of Addresses on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/addresses``

.. note:: For all returned data attributes, see :doc:`Address Object <address-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[addresses]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "identity", ":ref:`Identities Object <identity_object_v34>`"
   "identity.country", ":ref:`Country Object <country_object_v34>`"
   "identity.proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "identity.proofs.proof_type", ":ref:`Proofs Object <proofs_object_v34>`"
   "identity.permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v34>`"
   "identity.permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "area", ":ref:`Area Object <area_object_v34>`"
   "city", ":ref:`City Object <city_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "city_name", "``string``", "Yes", "No", "The ``city_name`` field."
   "city_name_contains", "``string``", "Yes", "No", "The ``city_name_contains`` field."
   "postal_code", "``string``", "Yes", "No", "The ``postal_code`` field."
   "postal_code_contains", "``string``", "Yes", "No", "The ``postal_code_contains`` field."
   "address", "``string``", "Yes", "No", "The ``address`` field."
   "address_contains", "``string``", "Yes", "No", "The ``address_contains`` field."
   "description", "``string``", "Yes", "No", "The ``description`` field."
   "description_contains", "``string``", "Yes", "No", "The ``description_contains`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."
   "identity.id", "``string``", "Yes", "Yes", "The ``identity.id`` field."
   "country.id", "``string``", "Yes", "Yes", "The ``country.id`` field."
   "area.id", "``string``", "Yes", "Yes", "The ``area.id`` field."
   "city.id", "``string``", "Yes", "Yes", "The ``city.id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "city_name", "The ``first_name`` field."
   "postal_code", "The ``last_name`` field."
   "address", "The ``address`` field."
   "description", "The ``id_number`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

      .. http:example:: curl

         GET /v3/addresses HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json
         Api-Key: [API token]

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
               "type": "addresses",
               "attributes": {
                 "city_name": "Antwerp",
                 "postal_code": "4641PA",
                 "address": "49th Ave",
                 "description": "Address of Rise Industries",
                 "created_at": "2020-09-16T10:23:07.846Z",
                 "verified": false,
                 "external_reference_id": null
               },
               "relationships": {
                 "identity": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/identity",
                     "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/identity"
                   }
                 },
                 "country": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/country",
                     "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/proofs",
                     "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/proofs"
                   }
                 },
                 "area": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/area",
                     "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/area"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/city",
                     "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/city"
                   }
                 }
               }
             },
             {
               "id": "f3f18701-356b-43dc-8a96-82d07af415cf",
               "type": "addresses",
               "attributes": {
                 "city_name": "Galway",
                 "postal_code": "Galway 17",
                 "address": "Street 15",
                 "description": "Headquarters",
                 "created_at": "2020-09-22T11:57:05.524Z",
                 "verified": false,
                 "external_reference_id": null
               },
               "relationships": {
                 "identity": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/identity",
                     "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/identity"
                   }
                 },
                 "country": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/country",
                     "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/proofs",
                     "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/proofs"
                   }
                 },
                 "area": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/area",
                     "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/area"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/relationships/city",
                     "related": "https://sandbox-api.didww.com/v3/addresses/f3f18701-356b-43dc-8a96-82d07af415cf/city"
                   }
                 }
               }
             },
             {
               "id": "54c92d8e-f135-4b55-ac48-748d44437509",
               "type": "addresses",
               "attributes": {
                 "city_name": "Dublin",
                 "postal_code": "Dublin 8",
                 "address": "10/13 Thomas Street",
                 "description": "My Business Address",
                 "created_at": "2020-09-14T07:29:41.413Z",
                 "verified": false,
                 "external_reference_id": null
               },
               "relationships": {
                 "identity": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/identity",
                     "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/identity"
                   }
                 },
                 "country": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/country",
                     "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/proofs",
                     "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/proofs"
                   }
                 },
                 "area": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/area",
                     "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/area"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/relationships/city",
                     "related": "https://sandbox-api.didww.com/v3/addresses/54c92d8e-f135-4b55-ac48-748d44437509/city"
                   }
                 }
               }
             }
           ],
           "meta": {
             "total_records": 3,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://sandbox-api.didww.com/v3/addresses?page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://sandbox-api.didww.com/v3/addresses?page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab:: Filter by country.id (i.e. Germany)

    .. http:example:: curl

        GET /v3/addresses?filter[country.id]=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "6f73fecd-6a7b-4440-93d7-41e0000baee0",
                  "type": "addresses",
                  "attributes":       {
                     "city_name": "Berlin",
                     "postal_code": "13089",
                     "address": "Leopoldstraße 38, Berlin Heinersdorf,Berlin",
                     "description": "none",
                     "created_at": "2021-06-08T08:38:25.433Z",
                     "verified": false,
                     "external_reference_id": null
                  },
                  "relationships":       {
                     "identity": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/identity",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/identity"
                     }},
                     "country": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/country",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/country"
                     }},
                     "proofs": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/proofs",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/proofs"
                     }},
                     "area": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/area",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/area"
                     }},
                     "city": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/city",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/city"
                     }}
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/addresses?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/addresses?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

   .. tab:: Include country

    .. http:example:: curl

        GET /v3/addresses?include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "6f73fecd-6a7b-4440-93d7-41e0000baee0",
                  "type": "addresses",
                  "attributes":       {
                     "city_name": "Berlin",
                     "postal_code": "13089",
                     "address": "Leopoldstraße 38, Berlin Heinersdorf,Berlin",
                     "description": "none",
                     "created_at": "2021-06-08T08:38:25.433Z",
                     "verified": false,
                     "external_reference_id": null
                  },
                  "relationships":       {
                     "identity": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/identity",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/identity"
                     }},
                     "country":          {
                        "links":             {
                           "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/country",
                           "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/country"
                        },
                        "data":             {
                           "type": "countries",
                           "id": "38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f"
                        }
                     },
                     "proofs": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/proofs",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/proofs"
                     }},
                     "area": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/area",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/area"
                     }},
                     "city": {"links":          {
                        "self": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/relationships/city",
                        "related": "https://api.didww.com/v3/addresses/6f73fecd-6a7b-4440-93d7-41e0000baee0/city"
                     }}
                  }
               }],
               "included": [   {
                  "id": "38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f",
                  "type": "countries",
                  "attributes":       {
                     "name": "Germany",
                     "prefix": "49",
                     "iso": "DE"
                  },
                  "relationships": {"regions": {"links":       {
                     "self": "https://api.didww.com/v3/countries/38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f/relationships/regions",
                     "related": "https://api.didww.com/v3/countries/38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f/regions"
                  }}}
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/addresses?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/addresses?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _addresses_v34:

=========
Addresses
=========

Returns a single or a list of Addresses in the account. Allows creating modifying or deleting an address.  

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  get-address.rst
  get-addresses.rst
  create-address.rst
  update-address.rst
  delete-address.rst
  address-object.rst


.. |br| raw:: html

   <br />

================
Update Addresses
================

Update the settings of a single Address owned by your account.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/addresses/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number allocated to this Address."

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "city_name", "``string``", "No", "City name of the address."
   "postal_code", "``string``", "No", "Postal code of the address."
   "address", "``string``", "No", "Full address."
   "description", "``string``", "No", "The description of the address."
   "external_reference_id", "``string``", "No", "Optional identifier for the address in the customer's external system. Maximum length is 100 characters."

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch

     .. http:example:: curl

      PATCH /v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
      Host: api.didww.com
      Content-Type: application/vnd.api+json
      Accept: application/vnd.api+json
      Api-Key: [API token]

      {
        "data": {
          "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
          "type": "addresses",
          "attributes": {
            "city_name": "string",
            "postal_code": "string",
            "address": "string",
            "description": "string"
          }
        }
      }

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json

      {
        "data": {
          "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
          "type": "addresses",
          "attributes": {
            "city_name": "string",
            "postal_code": "string",
            "address": "string",
            "description": "string",
            "created_at": "2020-09-16T10:23:07.846Z",
            "verified": false,
            "external_reference_id": null
          },
          "relationships": {
            "identity": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/identity",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/identity"
              }
            },
            "country": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/country",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/country"
              }
            },
            "proofs": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/proofs",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/proofs"
              }
            },
            "area": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/area",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/area"
              }
            },
            "city": {
              "links": {
                "self": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/relationships/city",
                "related": "https://sandbox-api.didww.com/v3/addresses/49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0/city"
              }
            }
          }
        },
        "meta": {
          "api_version": "2026-04-16"
        }
      }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _area_object_v34:

===========
Area Object
===========

Area Object definition.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Area name"

Relationships
-------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`"


.. _get_area_v34:

========
Get Area
========

Returns an area for a given area ID. Note that a unique identification number is allocated to each area.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/areas/``

.. note:: For all returned data attributes, see :doc:`Area Object <area-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID number for the area."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request
   
      .. http:example:: curl
         
            GET /v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                "type": "areas",
                "attributes": {
                  "name": "Tuscany"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                      "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                    }
                  }
                }
              }
            }

   .. tab:: Include Country 
      
   
      .. http:example:: curl
         
            GET /v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": {
                "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                "type": "areas",
                "attributes": {
                  "name": "Tuscany"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                      "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "51d3fe2a-6588-496b-870c-398e627de5c4"
                    }
                  }
                }
              },
              "included": [
                {
                  "id": "51d3fe2a-6588-496b-870c-398e627de5c4",
                  "type": "countries",
                  "attributes": {
                    "name": "Italy",
                    "prefix": "39",
                    "iso": "IT"
                  }
                }
              ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _get_areas_v34:

=========
Get Areas
=========

Returns a list of areas. Maximum :ref:`page size <api_pagination>` is 1000. Default page size is 1000.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/areas``

.. note:: For all returned data attributes, see :doc:`Area Object <area-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[areas]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Area ``id`` field."
   "name", "``string``", "Yes", "Yes", "Area ``name`` field. Case insensitive."
   "country.id", "``string``", "Yes", "Yes", "A ``country.id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by: "

   "name", "Area ``name`` field."

Examples
========

.. tabs::

   .. tab:: Simple request
   
        .. http:example:: curl 
        
           GET /v3/areas HTTP/1.1
           Host: api.didww.com
           Content-Type: application/vnd.api+json
           Accept: application/vnd.api+json
           Api-Key: [API Token]
           
           
           HTTP/2 200 OK
           Content-Type: application/vnd.api+json
           
           {
             "data": [
               {
                 "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                 "type": "areas",
                 "attributes": {
                   "name": "Tuscany"
                 },
                 "relationships": {
                   "country": {
                     "links": {
                       "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                       "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                     }
                   }
                 }
               }
             ],
              "meta": {
                  "total_records": 1,
                  "api_version": "2026-04-16"
              },
              "links": {
                  "first": "https://api.didww.com/v3/areas?page%5Bnumber%5D=1&page%5Bsize%5D=1000",
                  "last": "https://api.didww.com/v3/areas?page%5Bnumber%5D=1&page%5Bsize%5D=1000"
              }
           }

   .. tab:: Filter by name or country.id
   
      .. http:example:: curl
         
            GET /v3/areas?filter[name]=Tuscany&filter[country.id]=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                  "type": "areas",
                  "attributes": {
                    "name": "Tuscany"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                        "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                      }
                    }
                  }
                }
              ],
              "meta": {
                  "total_records": 1,
                  "api_version": "2026-04-16"
              },
              "links": {
                  "first": "https://api.didww.com/v3/areas?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Tuscany&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
                  "last": "https://api.didww.com/v3/areas?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Tuscany&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
              }
            }
            

   .. tab:: Include Country Resource
      
   
      .. http:example:: curl
         
            GET /v3/areas?include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API Token]
            
            
            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json
            
            {
              "data": [
                {
                  "id": "9fcc7390-84a2-47f1-a900-0558cdcb6ce3",
                  "type": "areas",
                  "attributes": {
                    "name": "Tuscany"
                  },
                  "relationships": {
                    "country": {
                      "links": {
                        "self": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/relationships/country",
                        "related": "https://api.didww.com/v3/areas/9fcc7390-84a2-47f1-a900-0558cdcb6ce3/country"
                      },
                      "data": {
                          "type": "countries",
                          "id": "51d3fe2a-6588-496b-870c-398e627de5c4"
                      }
                    }
                  }
                }
              ],
              "included": [
                {
                  "id": "51d3fe2a-6588-496b-870c-398e627de5c4",
                  "type": "countries",
                  "attributes": {
                    "name": "Italy",
                    "prefix": "39",
                    "iso": "IT"
                  }
                }
              ],
              "meta": {
                  "total_records": 1,
                  "api_version": "2026-04-16"
              },
              "links": {
                  "first": "https://api.didww.com/v3/areas?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
                  "last": "https://api.didww.com/v3/areas?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _areas_v34:

=====
Areas
=====
 
Returns a single or a list of regulatory areas.
If address includes information about the regulatory area, it means that address created must be within locality or region covered by the phone number's prefix.

Supported methods: ``GET``
 
.. toctree:: 
  :titlesonly:
  	
  get-area.rst
  get-areas.rst
  area-object.rst



.. |br| raw:: html

   <br />

.. _create_encrypted_files_v34:

=====================
Create Encrypted File
=====================

Creates an encrypted file on your account.

Encryption details is available :ref:`here <encryption_details_v34>`.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/encrypted_files``

Header: ``Content-Type: multipart/form-data``

.. note::

   In version ``2026-04-16``, ``POST /v3/encrypted_files`` accepts a **single file** per request and returns JSON:API-formatted success and error responses.

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Parameter Type", "Type", "Is Required?", "Description"

   "encrypted_files[encryption_fingerprint]", "``formData``", "``string``", "Yes", "The encryption fingerprint."
   "encrypted_files[description]", "``formData``", "``string``", "No", "The encrypted file description."
   "encrypted_files[file]", "``formData``", "``file``", "Yes", "The encrypted file."

.. note::

    - Accepted file formats:

        - `.pdf`
        - `.jpg`
        - `.png`

    - You may upload **1 file per request**.
    - Each file **must not exceed 20 MB** in size.
    - Uploaded encrypted files will **expire after 24 hours**.
    - Legacy batch parameters such as ``encrypted_files[items][][file]`` are not supported in version ``2026-04-16`` and return ``400 Bad Request``.

Examples
========

.. tabs::

   .. tab:: 201 Created

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "377dc5cf-55b3-45b8-9fed-156600a7f151",
                    "type": "encrypted_files",
                    "attributes": {
                        "description": "my file",
                        "expires_at": "2026-04-07T20:53:11.747Z"
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: 201 Created Without Description

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "377dc5cf-55b3-45b8-9fed-156600a7f151",
                    "type": "encrypted_files",
                    "attributes": {
                        "description": null,
                        "expires_at": "2026-04-07T20:53:11.747Z"
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: 422 Unprocessable Entity (Outdated Fingerprint)

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {
                "errors": [
                    {
                        "title": "outdated fingerprint",
                        "detail": "outdated fingerprint",
                        "code": "100",
                        "source": {
                            "pointer": "/data"
                        },
                        "status": "422"
                    }
                ]
            }

   .. tab:: 422 Unprocessable Entity (Missing File)

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 422 Unprocessable Entity
            Content-Type: application/vnd.api+json

            {
                "errors": [
                    {
                        "title": "can't be blank",
                        "detail": "file - can't be blank",
                        "code": "100",
                        "source": {
                            "pointer": "/data/attributes/file"
                        },
                        "status": "422"
                    }
                ]
            }

   .. tab:: 400 Bad Request (Invalid Params)

     .. http:example:: curl

            POST /v3/encrypted_files HTTP/1.1
            Host: api.didww.com
            Content-Type: multipart/form-data
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 400 Bad Request
            Content-Type: application/vnd.api+json

            {
                "errors": [
                    {
                        "title": "invalid params",
                        "detail": "invalid params",
                        "code": "400",
                        "status": "400"
                    }
                ]
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 
   "400","No",":ref:`Bad Request Error Object <api_bad_request>`"
   "422","No",":ref:`Validation Error Object <api_validation_error_object>`"


.. |br| raw:: html

   <br />

=====================
Delete Encrypted File
=====================

Deletes an encrypted file from your account. 

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/encrypted_files``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Encrypted File."

Examples
========

.. tabs::

   .. tab:: Example
   
     .. http:example:: curl

			DELETE /v3/encrypted_files/dfd8ee70-3806-446e-aa49-7b7f30a4e7d0 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
		
		    HTTP/1.1 204 Deleted
		    Content-Type: application/vnd.api+json

   

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. _encrypted_files_object_v34:

.. |br| raw:: html

   <br />

======================
Encrypted Files Object
======================

Encrypted files object attributes. 

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "description", "``string``", "The description of encrypted file."
   "expires_at", "``Date&Time``", "The expiration date for the encrypted file."

Create Request Attributes
=========================

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "encrypted_files[encryption_fingerprint]", "``string``", "Yes", "The encryption fingerprint."
   "encrypted_files[description]", "``string``", "No", "The encrypted file description."
   "encrypted_files[file]", "``file``", "Yes", "The encrypted file."


.. |br| raw:: html

   <br />

.. _encryption_details_v34:

==================
Encryption details
==================

Files passed to :ref:`Create Encrypted File <create_encrypted_files_v34>` should be encrypted with :ref:`DIDWW Public Keys <public_keys_v34>`.

Using SDK for encryption
========================

Recommended way of using encryption is to encrypt files in browser.
it can be achieved via `@didww/encrypt <https://github.com/didww/didww-encrypt>`_  JS library.

If you want to encrypt files on server side it can be done via following:

.. grid:: 1 1 1 3
   :gutter: 4

   .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Gem**
      :link: https://github.com/didww/didww-v3-ruby/blob/master/lib/didww/encrypt.rb
      :link-type: url

      Use the APIv3 Ruby gem to perform file encryption on the server side.

   .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
      :link: https://github.com/didww/didww-api-3-php-sdk/blob/master/src/Encrypt.php
      :link-type: url

      Use the official PHP SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
      :link: https://github.com/didww/didww-api-3-java-sdk/blob/main/src/main/java/com/didww/sdk/Encrypt.java
      :link-type: url

      Use the official Java SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
      :link: https://github.com/didww/didww-api-3-python-sdk/blob/main/src/didww/encrypt.py
      :link-type: url

      Use the official Python SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
      :link: https://github.com/didww/didww-api-3-typescript-sdk/blob/main/src/encrypt.ts
      :link-type: url

      Use the official TypeScript SDK to implement server-side encryption.

   .. grid-item-card:: :iconify:`logos:go` **Go Encryption Sample**
      :link: https://github.com/didww/go-encrypt-sample
      :link-type: url

       Use the Go sample project to implement server-side file encryption compatible with DIDWW API v3.

To implement encryption manually see figure:

|br|

.. figure:: https://doc.didww.com/_images/enc.png
    :figclass: align-center

    **Fig. 1.** File encryption schematic.

For additional check you need to pass fingerprint of public keys along with encrypted files.
You can use our JS library or ruby SDK for that.

To implement fingerprint calculation manually see figure:

.. figure:: https://doc.didww.com/_images/fingerprint.png
    :figclass: align-center

    **Fig. 1.** Fingerprint calculation schematic.


.. |br| raw:: html

   <br />

==================
Get Encrypted File
==================

Returns a single encrypted file. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/encrypted_files/``

.. note:: For all returned data attributes, see :doc:`Encrypted Files Object <encrypted-files-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Encrypted File."

Examples
========

.. tabs::

   .. tab:: Encrypted File 
   
     .. http:example:: curl

			GET /v3/encrypted_files/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			    "data": [
			        {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files",
			            "attributes": {
			                "description": "Description",
			                "expires_at": "2021-03-29T14:18:19.569Z"
			            }
			        }
			    ],
			    "meta": {
			        "total_records": 1,
			        "api_version": "2026-04-16"
			    },
			    "links": {
			        "first": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50",
			        "last": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

===================
Get Encrypted Files
===================

Returns a list of encrypted files in the account. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/encrypted_files``

.. note:: For all returned data attributes, see :doc:`Encrypted Files Object <encrypted-files-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "fields[encrypted_files]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by"

   "description", "The encrypted file description."
   "expires_at", "The expiration date of encrypted file."

Examples
========

.. tabs::

   .. tab:: Encrypted File 
   
     .. http:example:: curl

			GET /v3/encrypted_files HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			    "data": [
			        {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files",
			            "attributes": {
			                "description": "Description",
			                "expires_at": "2021-03-29T14:18:19.569Z"
			            }
			        }
			    ],
			    "meta": {
			        "total_records": 1,
			        "api_version": "2026-04-16"
			    },
			    "links": {
			        "first": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50",
			        "last": "https://sandbox-api.didww.com/v3/encrypted_files?page%5Bnumber%5D=1&page%5Bsize%5D=50"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. _encrypted_files_v34:

===============
Encrypted Files
===============

Returns a single or a list of Encrypted Files on the account. Allows uploading the encrypted files to DIDWW server. 

.. attention::

 File format for the uploaded documents should be one of the following: JPG, PNG, PDF
 Other formats will be rejected during the verification process.
 
Encryption details is available :ref:`here <encryption_details_v34>`.

Supported methods: ``GET``, ``POST``, ``DELETE``.

.. toctree::
  :maxdepth: 1

  encryption-details.rst
  get-encrypted-file.rst
  get-encrypted-files.rst
  create-encrypted-files.rst
  delete-encrypted-files.rst
  encrypted-files-object.rst
  public-keys.rst


.. _public_keys_v34:

===============
Get Public Keys
===============

Returns a list of RSA public keys which should be used for files encryption.

Encryption details is available :ref:`here <encryption_details_v34>`.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/public_keys``

Examples
========

.. tabs::

   .. tab:: Encrypted File

     .. http:example:: curl

			GET /v3/public_keys HTTP/1.1
			Host: api.didww.com
			Accept: application/vnd.api+json

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			    "data": [
			        {
			            "id": "dcf2bfcb-a1d0-3b58-bbf0-3ec22a510ba8",
			            "type": "public_keys",
			            "attributes": {
			                "key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----\n"
			            }
			        },
			        {
			            "id": "f40e1176-a4ff-36e6-b2ed-c2c2d18097a3",
			            "type": "public_keys",
			            "attributes": {
			                "key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----\n"
			            }
			        }
			    ],
			    "meta": {
			        "api_version": "2026-04-16"
			    }
			}


.. |br| raw:: html

   <br />

===============
Create Identity
===============

Create single Identity owned by your account.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/identities/``

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "birth_country", ":ref:`Country Object <country_object_v34>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "addresses", ":ref:`Addresses Object <addresses_object_v34>`"
   "addresses.country", ":ref:`Country Object <country_object_v34>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v34>`"
   "permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"

Request Body Object Attributes
------------------------------

.. tabs::

   .. tab:: Personal

     .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "first_name", "``string``", "Yes", "First name of the personal identity."
	   "last_name", "``string``", "Yes", "Last name of the personal identity."
	   "phone_number", "``string``", "Yes", "Phone number of the personal identity."
	   "personal_tax_id", "``string``", "No", "Personal tax ID of the personal identity."
	   "birth_date", "``string``", "No", "Birth date of the personal identity in ISO 8601 format."
	   "id_number", "``string``", "No", "ID number of the personal identity."
	   "description", "``string``", "No", "Description of the personal identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system"
	   "identity_type", "``string``", "Yes", "Type of identity. Write ``personal`` to create a personal identity."
	   "contact_email", "``string``", "No", "Contact email address of identity."

   .. tab:: Business

	 .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "company_name", "``string``", "Yes", "Company name of the business identity."
	   "company_reg_number", "``string``", "No", "Company registration number of the business identity."
	   "vat_id", "``string``", "No", "Company VAT ID of the business identity."
	   "first_name", "``string``", "Yes", "Company's representative First name of the business identity."
	   "last_name", "``string``", "Yes", "Company's representative Last name of the business identity."
	   "phone_number", "``string``", "Yes", "Company's representative Phone number of the business identity."
	   "personal_tax_id", "``string``", "No", "Company's representative Tax ID of the business identity."
	   "birth_date", "``string``", "No", "Company's representative Birth date of the business identity in ISO 8601 format."
	   "id_number", "``string``", "No", "Company's representative ID number of the business identity."
	   "description", "``string``", "No", "Company's representative description of the business identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system."
	   "identity_type", "``string``", "Yes", "Identity type. Write ``business`` to create a business identity."
	   "contact_email", "``string``", "No", "Contact email address of identity."

Request Body Object Relationships
---------------------------------

.. csv-table::
  :header: "Title", "Type", "Description"

  "country", ":ref:`Country Object <country_object_v34>`", "Specifies the country for identity."
  "birth_country", ":ref:`Country Object <country_object_v34>`", "Specifies the birth country for identity. In version ``2026-04-16``, it is handled separately from ``country`` and is not auto-assigned."

.. note::

   Assigning ``country`` does not automatically assign ``birth_country``. Set ``birth_country`` explicitly when needed.

Examples
========

.. tabs::

   .. tab:: Create Personal Identity

     .. http:example:: curl

            POST /v3/identities HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "birth_date": null,
                  "id_number": "string",
                  "description": "string",
                  "personal_tax_id": "string",
                  "external_reference_id": "string",
                  "identity_type": "personal",
                  "contact_email": "string"
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "39623bf9-381f-4da6-ab29-2d3eb8783d81",
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "id_number": "string",
                  "birth_date": null,
                  "company_name": null,
                  "company_reg_number": null,
                  "vat_id": null,
                  "description": "string",
                  "personal_tax_id": "string",
                  "identity_type": "personal",
                  "created_at": "2021-03-22T11:53:32.240Z",
                  "external_reference_id": null,
                  "verified": false,
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/country",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/country"
                    }
                  },
                  "proofs": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/proofs",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/proofs"
                    }
                  },
                  "addresses": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/addresses",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/addresses"
                    }
                  },
                  "permanent_documents": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/permanent_documents",
                      "related": "https://sandbox-api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/permanent_documents"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

   .. tab:: Create Personal Identity with Country and Birth Country

     .. http:example:: curl

            POST /v3/identities HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "birth_date": null,
                  "id_number": "string",
                  "description": "string",
                  "personal_tax_id": "string",
                  "external_reference_id": "string",
                  "identity_type": "personal",
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "data": {
                      "id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
                      "type": "countries"
                    }
                  },
                  "birth_country": {
                    "data": {
                      "id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
                "data": {
                    "id": "874390d1-ea6f-47c0-8d30-c9baaaeebdd9",
                    "type": "identities",
                    "attributes": {
                        "first_name": "string",
                        "last_name": "string",
                        "phone_number": "string",
                        "id_number": "string",
                        "birth_date": null,
                        "company_name": null,
                        "company_reg_number": null,
                        "vat_id": null,
                        "description": "string",
                        "personal_tax_id": "string",
                        "identity_type": "personal",
                        "created_at": "2023-01-31T09:23:10.406Z",
                        "external_reference_id": "string",
                        "verified": false,
                        "contact_email": "string"
                    },
                    "relationships": {
                        "country": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/country",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/country"
                            }
                        },
                        "birth_country": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/birth_country",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/birth_country"
                            }
                        },
                        "proofs": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/proofs",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/proofs"
                            }
                        },
                        "addresses": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/addresses",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/addresses"
                            }
                        },
                        "permanent_documents": {
                            "links": {
                                "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/permanent_documents",
                                "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/permanent_documents"
                            }
                        }
                    }
                },
                "meta": {
                    "api_version": "2026-04-16"
                }
            }

   .. tab:: Create Business Identity

        .. http:example:: curl

            POST /v3/identities HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "id_number": "string",
                  "birth_date": "string",
                  "company_name": "string",
                  "company_reg_number": "string",
                  "vat_id": "string",
                  "description": "string",
                  "personal_tax_id": "string",
                  "external_reference_id": "string",
                  "identity_type": "business",
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "data": {
                      "id": "6d0effab-3fe3-4e07-acc6-1d3ddc717ebc",
                      "type": "countries"
                    }
                  },
                  "birth_country": {
                    "data": {
                      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 201 Created
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "fb7f3f67-014c-496b-b918-f874f2689a40",
                "type": "identities",
                "attributes": {
                  "first_name": "string",
                  "last_name": "string",
                  "phone_number": "string",
                  "id_number": "string",
                  "birth_date": null,
                  "company_name": "string",
                  "company_reg_number": null,
                  "vat_id": null,
                  "description": "string",
                  "personal_tax_id": "string",
                  "identity_type": "business",
                  "created_at": "2021-03-22T12:08:29.987Z",
                  "external_reference_id": null,
                  "verified": false,
                  "contact_email": "string"
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/country",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/country"
                    }
                  },
                  "birth_country": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/birth_country",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/birth_country"
                    }
                  },
                  "proofs": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/proofs",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/proofs"
                    }
                  },
                  "addresses": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/addresses",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/addresses"
                    }
                  },
                  "permanent_documents": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/permanent_documents",
                      "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/permanent_documents"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 



===============
Delete Identity
===============

Deletes the Identity without restoration.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/identities/``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "id", "``string``","Yes","Unique ID identifier of the Identities."

Example
=======

.. http:example:: curl

    DELETE /v3/identities/c3947e93-4a3b-4080-b9d3-cbcc633ab808 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]
    
    
    HTTP/1.1 204 No Content
    Content-Type: application/vnd.api+json
    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "409","No",":ref:`Conflict <conflict_v1>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




==============
Get Identities
==============

Returns a list of Identities on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/identities``

.. note:: For all returned data attributes, see :doc:`Identity Object <identity-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``, ``DateTime``", "No", ":ref:`Filtering <api_filters>`"
   "fields[identities]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"
   
   "country", ":ref:`Country Object <country_object_v34>`"
   "birth_country", ":ref:`Country Object <country_object_v34>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "addresses", ":ref:`Addresses Object <addresses_object_v34>`"
   "addresses.country", ":ref:`Country Object <country_object_v34>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v34>`"
   "permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"
   
   "first_name", "``string``", "Yes", "Yes", "The ``first_name`` field."
   "first_name_contains", "``string``", "Yes", "Yes", "The ``firs_name_contains`` field."
   "last_name", "``string``", "Yes", "Yes", "The ``last_name`` field."
   "last_name_contains", "``string``", "Yes", "Yes", "The ``last_name_contains`` field."
   "phone_number", "``string``", "Yes", "Yes", "The ``phone_number`` field."
   "phone_number_contains", "``string``", "Yes", "No", "The ``phone_number_contains`` field."
   "id_number", "``string``", "Yes", "Yes", "The ``id_number`` field."
   "id_number_contains", "``string``", "Yes", "Yes", "The ``id_number_contains`` field."
   "birth_date", "``DateTime``", "No", "Yes", "The ``birth_date`` field."
   "company_name", "``string``", "Yes", "Yes", "The ``company_name`` field."
   "company_name_contains", "``string``", "Yes", "Yes", "The ``company_name_contains`` field."
   "company_reg_number", "``string``", "Yes", "Yes", "The ``company_reg_number`` field."
   "company_reg_number_contains", "``string``", "Yes", "Yes", "The ``company_reg_number_contains`` field."
   "vat_id", "``string``", "Yes", "Yes", "The ``vat_id`` field."
   "vat_id_contains", "``string``", "Yes", "Yes", "The ``vat_id_contains`` field."
   "description", "``string``", "Yes", "Yes", "The ``description`` field."
   "description_contains", "``string``", "Yes", "Yes", "The ``description_contains`` field"
   "personal_tax_id", "``string``", "Yes", "Yes", "The ``personal_tax_id`` field."
   "personal_tax_id_contains", "``string``", "Yes", "Yes", "The ``personal_tax_id`` field."
   "identity_type", "``string``", "No", "No", "The ``identity_type`` field. Possible values: ``any, personal``, ``business``."
   "country.id", "``string``", "No", "No", "The ``country.id`` field."
   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"
   
   "first_name", "The ``first_name`` field."
   "last_name", "The ``last_name`` field."
   "phone_number", "The ``phone_number`` field."
   "id_number", "The ``id_number`` field."
   "birth_date", "The ``birth_date`` field."
   "company_name", "The ``company_name`` field."
   "company_reg_number", "The ``company_reg_number`` field."
   "vat_id", "The ``vat_id`` field."
   "description", "The ``description`` field."
   "personal_tax_id", "The ``personal_tax_id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/identities HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
		            "type": "identities",
		            "attributes": {
		                "first_name": "Jane",
		                "last_name": "Smith",
		                "phone_number": "353-1-9015266",
		                "id_number": "0000000000",
		                "birth_date": "2000-01-01",
		                "company_name": null,
		                "company_reg_number": null,
		                "vat_id": null,
		                "description": "Personal details",
		                "personal_tax_id": null,
		                "identity_type": "personal",
		                "created_at": "2020-09-14T07:29:41.393Z",
                                "external_reference_id": null,
                                "verified": false,
                                "contact_email": "contact@email.com"
		            },
		            "relationships": {
		                "country": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
		                    }
		                },
		                "birth_country": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
		                    }
		                },
		                "addresses": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
		                    }
		                },
		                "permanent_documents": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
		                    }
		                }
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 4,
		        "api_version": "2026-04-16"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/identities?page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/identities?page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Filter first_name_contains

    .. http:example:: curl

        GET /v3/identities/v3/identities?filter[first_name_contains]=Jane HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
		            "type": "identities",
		            "attributes": {
		                "first_name": "Jane",
		                "last_name": "Smith",
		                "phone_number": "353-1-9015266",
		                "id_number": "0000000000",
		                "birth_date": "2000-01-01",
		                "company_name": null,
		                "company_reg_number": null,
		                "vat_id": null,
		                "description": "Personal details",
		                "personal_tax_id": null,
		                "identity_type": "personal",
		                "created_at": "2020-09-14T07:29:41.393Z",
                                "external_reference_id": null,
                                "verified": false,
                                "contact_email": "contact@email.com"
		            },
		            "relationships": {
		                "country": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
		                    }
		                },
		                "birth_country": {
		                    "links": {
		                        "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country",
		                        "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country"
		                    }
		                },
		                "proofs": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
		                    }
		                },
		                "addresses": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
		                    }
		                },
		                "permanent_documents": {
		                    "links": {
		                        "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
		                        "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
		                    }
		                }
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 4,
		        "api_version": "2026-04-16"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane&page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane&page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Include country

    .. http:example:: curl

        GET /v3/identities/v3/identities?include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
		            "type": "identities",
		            "attributes": {
		                "first_name": "Jane",
		                "last_name": "Smith",
		                "phone_number": "353-1-9015266",
		                "id_number": "0000000000",
		                "birth_date": "2000-01-01",
		                "company_name": null,
		                "company_reg_number": null,
		                "vat_id": null,
		                "description": "Personal details",
		                "personal_tax_id": null,
		                "identity_type": "personal",
		                "created_at": "2020-09-14T07:29:41.393Z",
                                "external_reference_id": null,
                                "verified": false,
                                "contact_email": "contact@email.com"
		            },
                  },
                  "relationships":{
                     "country":{
                        "links":{
                           "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/country",
                           "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/country"
                        },
                        "data":{
                           "type": "countries",
                           "id": "683c77a5-fcb0-48a0-8501-4de6284a2889"
                        }
                     },
                     "birth_country":{
                        "links":{
                           "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/birth_country",
                           "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/birth_country"
                        }
                     },
                     "proofs": {"links":{
                        "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/proofs",
                        "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/proofs"
                     }},
                     "addresses": {"links":{
                        "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/addresses",
                        "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/addresses"
                     }},
                     "permanent_documents": {"links":{
                        "self": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/relationships/permanent_documents",
                        "related": "https://api.didww.com/v3/identities/6c832a1d-b19d-471b-b416-9b5bf2b6ef9d/permanent_documents"
                     }}
                  }
               }],
               "included": [{
                  "id": "683c77a5-fcb0-48a0-8501-4de6284a2889",
                  "type": "countries",
                  "attributes":{
                     "name": "Lithuania",
                     "prefix": "370",
                     "iso": "LT"
                  },
                  "relationships": {"regions": {"links":{
                     "self": "https://api.didww.com/v3/countries/683c77a5-fcb0-48a0-8501-4de6284a2889/relationships/regions",
                     "related": "https://api.didww.com/v3/countries/683c77a5-fcb0-48a0-8501-4de6284a2889/regions"
                  }}}
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/identities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/identities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "401","No",":ref:`Unauthorized <api_key>`" 




============
Get Identity
============

Returns a single Identity in the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/identities/{id}``

.. note:: For all returned data attributes, see :doc:`Identity Object <identity-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "id", "``string``","Yes","Unique ID identifier of the Identity."
   "include", "``string``", "No", "Related resources to include in the response. See :ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "birth_country", ":ref:`Country Object <country_object_v34>`"
   "proofs", ":ref:`Proofs Object <proofs_object_v34>`"
   "addresses", ":ref:`Addresses Object <addresses_object_v34>`"
   "addresses.country", ":ref:`Country Object <country_object_v34>`"
   "proofs.proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "permanent_documents", ":ref:`Permanent Documents Object <permanent_documents_object_v34>`"
   "permanent_documents.template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/identities/0083c7f2-b030-491f-91b3-54597967ca38 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "0083c7f2-b030-491f-91b3-54597967ca38",
                "type": "identities",
                "attributes": {
                    "first_name": "Jane",
                    "last_name": "Smith",
                    "phone_number": "1276813663",
                    "id_number": "",
                    "birth_date": null,
                    "company_name": null,
                    "company_reg_number": null,
                    "vat_id": null,
                    "description": null,
                    "personal_tax_id": null,
                    "identity_type": "personal",
                    "created_at": "2025-04-11T13:03:17.029Z",
                    "external_reference_id": null,
                    "verified": false,
                    "contact_email": "contact@email.com"
                },
                "relationships": {
                    "country": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/country",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/country"
                        }
                    },
                    "birth_country": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/birth_country",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/birth_country"
                        }
                    },
                    "proofs": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/proofs",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/proofs"
                        }
                    },
                    "addresses": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/addresses",
                            "related": "https://sandbox-api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/addresses"
                        }
                    },
                    "permanent_documents": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/permanent_documents",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/permanent_documents"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

   .. tab:: Include country

    .. http:example:: curl

        GET /v3/identities/0083c7f2-b030-491f-91b3-54597967ca38?include=country HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "0083c7f2-b030-491f-91b3-54597967ca38",
                "type": "identities",
                "attributes": {
                    "first_name": "Jane",
                    "last_name": "Smith",
                    "phone_number": "1276813663",
                    "id_number": "",
                    "birth_date": null,
                    "company_name": null,
                    "company_reg_number": null,
                    "vat_id": null,
                    "description": null,
                    "personal_tax_id": null,
                    "identity_type": "personal",
                    "created_at": "2021-04-20T13:37:21.594Z",
                    "external_reference_id": null,
                    "verified": false
                },
                "relationships": {
                    "country": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/country",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/country"
                        },
                        "data": {
                            "type": "countries",
                            "id": "b9dce495-1085-4452-8224-6761dd3cc15a"
                        }
                    },
                    "birth_country": {
                        "links": {
                            "self": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/birth_country",
                            "related": "https://api.didww.com/v3/identities/0083c7f2-b030-491f-91b3-54597967ca38/relationships/birth_country"
                        }
                    }
                }
            },
            "included": [
                {
                    "id": "b9dce495-1085-4452-8224-6761dd3cc15a",
                    "type": "countries",
                    "attributes": {
                        "name": "Andorra",
                        "prefix": "376",
                        "iso": "AD"
                    }
                }
            ],
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 


.. _identity_object_v34:

===============
Identity Object
===============

Identity Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "first_name", "``string``", "First name of identity."
   "last_name", "``string``", "Last name of identity."
   "phone_number", "``string``", "Phone number of identity."
   "id_number", "``string``", "The ID number of identity."
   "birth_date", "``DateTime``", "The birth date of identity."
   "company_name", "``string``", "Company name of identity."
   "company_reg_number", "``string``", "Company Registration number of identity."
   "vat_id", "``string``", "The VAT ID of identity."
   "description", "``string``", "The friendly description of identity."
   "personal_tax_id", "``string``", "The personal tax number of identity."
   "external_reference_id", "``string``", "Identifier in external customer's system."
   "verified", "``boolean``", "Displays if Identity is verified."
   "contact_email", "``string``", "Contact email address of identity."
   "identity_type", "``string``", "One of the following: ``any, personal`` or ``business``."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`. Specifies the country for the identity."
   "birth_country", "to-one", ":ref:`Country Object <country_object_v34>`. Specifies the birth country for the identity. In version ``2026-04-16``, it is managed separately from ``country``."
   "proofs", "to-many", ":ref:`Proofs Object <proofs_object_v34>`. Returns the proofs assigned to the identity."
   "addresses", "to-many", ":ref:`Addresses Object <addresses_object_v34>`. Returns the addresses assigned to the identity."
   "permanent_documents", "to-many", ":ref:`Permanent Documents Object <permanent_documents_object_v34>`. Returns the permanent documents assigned to the identity."


.. |br| raw:: html

   <br />

.. _identities_v34:

==========
Identities
==========

Returns a single or a list of Identities in the account. Allows creating modifying or deleting an identity.  

Supported methods: ``GET``, ``POST``, ``PATCH``, ``DELETE``.

.. toctree::
  :maxdepth: 1
  
  get-identity.rst
  get-identities.rst
  create-identity.rst
  update-identity.rst
  delete-identity.rst
  identity-object.rst
  
  
  


.. |br| raw:: html

   <br />

===============
Update Identity
===============

Update the settings of a single Identity owned by your account.

Request
=======

HTTP Method: ``PATCH``

URI Path: ``/v3/identities/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?","Description"

   "id", "``string``","Yes","Unique ID identifier of the Identity."

Attributes
==========

.. tabs::

   .. tab:: Personal

     .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "first_name", "``string``", "Yes", "First name of the personal identity."
	   "last_name", "``string``", "Yes", "Last name of the personal identity."
	   "phone_number", "``string``", "Yes", "Phone number of the personal identity. Only digits allowed."
	   "personal_tax_id", "``string``", "No", "Personal tax ID of the personal identity."
	   "birth_date", "``string``", "No", "Birth date of the personal identity in ISO 8601 format."
	   "id_number", "``string``", "No", "ID number of the personal identity."
	   "description", "``string``", "No", "Description of the personal identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system."
	   "contact_email", "``string``", "No", "Contact email address of identity."

   .. tab:: Business

	 .. csv-table::
	   :header: "Name", "Type", "Is Required?", "Description"

	   "company_name", "``string``", "Yes", "Company name of the business identity."
	   "company_reg_number", "``string``", "No", "Company registration number of the business identity."
	   "vat_id", "``string``", "No", "Company VAT ID of the business identity."
	   "first_name", "``string``", "Yes", "Company's representative first name of the business identity."
	   "last_name", "``string``", "Yes", "Company's representative last name of the business identity."
	   "phone_number", "``string``", "Yes", "Company's representative phone number of the business identity. Only digits allowed."
	   "personal_tax_id", "``string``", "No", "Company's representative Tax ID of the business identity."
	   "birth_date", "``string``", "No", "Company's representative Birth date of the business identity in ISO 8601 format."
	   "id_number", "``string``", "No", "Company's representative ID number of the business identity."
	   "description", "``string``", "No", "Description of the business identity."
	   "external_reference_id", "``string``", "No", "Identifier for identity in external system."
	   "contact_email", "``string``", "No", "Contact email address of identity."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "country", ":ref:`Country Object <country_object_v34>`", "Specifies the country for identity. Required for business identity updates in the Postman schema."
   "birth_country", ":ref:`Country Object <country_object_v34>`", "Specifies the birth country for identity. Send an empty string to remove the current ``birth_country`` value."

.. note::

   Assigning ``country`` does not automatically assign ``birth_country``. Set ``birth_country`` explicitly when needed.

Examples
========

.. tabs::

   .. tab:: Simple Resource Patch

     .. http:example:: curl

            PATCH /v3/identities/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
                "type": "identities",
                "attributes": {
                  "birth_date": "2000-01-01",
                  "phone_number": "35319015266",
                  "last_name": "Smith",
                  "contact_email": "support@didww.com",
                  "vat_id": null,
                  "id_number": "0000000000",
                  "description": "string",
                  "personal_tax_id": "string"
                },
                "relationships": {
                  "birth_country": {
                    "data": {
                      "id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
                      "type": "countries"
                    }
                  }
                }
              }
            }

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
              "data": {
                "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
                "type": "identities",
                "attributes": {
                  "first_name": "Jane",
                  "last_name": "Smith",
                  "phone_number": "35319015266",
                  "id_number": "0000000000",
                  "birth_date": "2000-01-01",
                  "company_name": "string",
                  "company_reg_number": null,
                  "vat_id": null,
                  "description": "string",
                  "personal_tax_id": "string",
                  "identity_type": "personal",
                  "created_at": "2020-09-14T07:29:41.393Z",
                  "contact_email": "support@didww.com",
                  "external_reference_id": null
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
                    }
                  },
                  "birth_country": {
                    "links": {
                      "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country",
                      "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country"
                    }
                  },
                  "proofs": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
                    }
                  },
                  "addresses": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
                    }
                  },
                  "permanent_documents": {
                    "links": {
                      "self": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
                      "related": "https://sandbox-api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
                    }
                  }
                }
              },
              "meta": {
                "api_version": "2026-04-16"
              }
            }

   .. tab:: Remove birth_country

     .. http:example:: curl

            PATCH /v3/identities/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            {
              "data": {
                "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
                "type": "identities",
                "relationships": {
                  "birth_country": {
                    "data": ""
                  }
                }
              }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"
   
   "404","No",":ref:`Not Found <api_not_found>`"
   "401","No",":ref:`Unauthorized <api_key>`" 




====================
Regulation Resources
====================

Regulation Resources allows customers to comply with the individual country DID registration requirements via API.

The regulation requirements are unique to each country and type of DID number. DIDWW **customers** and their **end users** have a collective obligation to comply with these regulations. 

To review the regulation requirements for each individual country and number type you can use :ref:`Address Requirements <address_requirements_v34>` resource.

The :ref:`Identity <identities_v34>` and :ref:`Addresses <addresses_v34>` may require additional :ref:`proofs <proofs_v34>` of existence.

The quantity of proofs required is indicated in the returned values of Get Requirements request. For more information review :ref:`Requirements Object <requirements_object_v34>`.

.. attention::

  All verifications will be reviewed by DIDWW Compliance Team and once **approved** the same identity and address can be used again for the DID types that fall under the same level of restrictions. 

To create a registration requirement verification task for existing DIDs or newly purchased DIDs, the following steps are required:

 1. Check the :ref:`Address requirements <address_requirements_v34>`  for the DID that you are required to register.
 2. Create an :ref:`Identity <identities_v34>`. Two types of identities are supported:
     
  * Personal Identity 
  * Business Identity
  
 3. Create an :ref:`Address <addresses_v34>`.

 4. The **identity** and **address** may require additional :ref:`proof of existence <proofs_v34>` based on individual regulation requirements.

 5. The :ref:`proof types <proof_types_v34>` depend on the type of **Identity**.
 
.. note::
  
  Certain regulations do not require additional proofs, therefore steps **4** and **5** are completely optional. 
  
\

 6. Upload the documents using  :ref:`encrypted files <encrypted_files_v34>` endpoint.
 
.. attention::

 File format for the uploaded documents should be one of the following: **JPG**, **PNG**, **PDF**
 Other formats will be rejected during the verification process.
   
\

 
 7. Create a :ref:`proof <proofs_v34>` for identity or address.
 
 8. Additional :ref:`supporting document templates <supporting_document_template_v34>` may be required depending on the regulation.
 
.. note::

  Supporting document templates may be required by regulatory in certain countries. 

\

 9. :ref:`Validate <address_requirement_validations_v34>` the identity and address against the regulation requirements.
 
 10. Create a :ref:`verification task <address_verifications_v34>` for your DID Number.
 
 
.. note::
  You can receive :ref:`callback <callbacks_details_v34>` notifications about the verification task status. Status can be **Approved** or **Rejected**.

.. raw:: html

   <h2 id="proofs">Proofs<a class="headerlink" href="#proofs" title="Link to this heading"></a></h2>

.. tabs::

   .. tab:: Address

	.. csv-table::
		:header: "Name"

		"Copy of Phone Bill"
		"Utility Bill"
		"Rental Receipt"
		"Other"

   .. tab:: Personal Identity

	.. csv-table::
		:header: "Name"

		"Drivers License"
		"National ID "
		"Passport"
		"Residence Permit"
		"Visa"
		"Other"

   .. tab:: Business Identity

	.. csv-table::
		:header: "Name"

		"Business Registration Certificate / Incorporation Certificate"
		"Trade License  "
		"Excerpt from the commercial register "
		"Residence Permit"
		"Other"

The :ref:`Address requirements <address_requirements_v34>` may require optional fields to be filled in.
If requirement have **personal_mandatory_fields** and/or **business_mandatory_fields**,the corresponding attributes/relationships of :ref:`Identity <identity_object_v34>` should be filled in.

Following mandatory values can be included in **personal_mandatory_fields** and/or **business_mandatory_fields**:

.. csv-table::
   :header: "Attribute", "Description"

   "birth_date", "Birth Date of a Person"
   "personal_tax_id", "Personal / Representative Tax Number"
   "id_number", "Proof of ID"
   "vat_id", "VAT / TAX Number"
   "company_reg_number", "Company Registration Number"

.. csv-table::
   :header: "Relationships", "Description"

   "country", "Place of Birth / Country of Incorporation"

The :ref:`Address requirements <address_requirements_v34>` may require additional documents.
:ref:`Supporting Document Template Object <supporting_document_templates_object_v34>` lists all the additional documents that may be required by  :ref:`Address requirements <address_requirements_v34>`.

There are 2 types of :ref:`Supporting Document Templates <supporting_document_template_v34>`: **permanent document** and **onetime document**.

.. raw:: html

   <h2 id="permanent-document">Permanent document<a class="headerlink" href="#permanent-document" title="Link to this heading"></a></h2>

If the requirement contains **personal_permanent_document** and/or **business_permanent_document**, corresponding template form needs to be downloaded from the link provided under URL attribute.
The template form needs to be filled in and uploaded using :ref:`Encrypted File Resource<create_encrypted_files_v34>`.
The encrypted file(s) needs to be linked with the required Identity only once using :ref:`Permanent Supporting Document Resource<create_permanent_supporting_document_v34>`.
Consequently, this Identity can be reused again for the requirements with **Permanent Supporting Document** already linked.

.. raw:: html

   <h2 id="onetime-document">Onetime document<a class="headerlink" href="#onetime-document" title="Link to this heading"></a></h2>

If the requirement contains personal_onetime_document and/or business_onetime_document, corresponding template form needs to be downloaded from the link provided under URL attribute.
The template form needs to be filled in and uploaded using :ref:`Encrypted File Resource<create_encrypted_files_v34>`.
Such file(s) after encryption should be linked to the new address verification with this onetime document requirement.

.. raw:: html

   <h2 id="requirement-address-area-level">Requirement Address Area Level<a class="headerlink" href="#requirement-address-area-level" title="Link to this heading"></a></h2>

:ref:`Address requirement <address_requirements_v34>` may enforce the :ref:`Address <addresses_object_v34>` to be from specific country/area.

The **address_area_level** attribute may be one of the following:

.. csv-table::
   :header: "Value", "Description"

   "Worldwide", "Address from any country can be used"
   "country", "Address must be within the requirement country"
   "area", "Address must be within the locality or region covered by the phone number's prefix"
   "city", "Address must be from the same city as DIDs"

.. raw:: html

   <h2 id="requirement-identity-area-level">Requirement Identity Area Level<a class="headerlink" href="#requirement-identity-area-level" title="Link to this heading"></a></h2>

:ref:`Address requirement <address_requirements_v34>` may enforce the :ref:`Identity <identity_object_v34>` to be from specific country/area.

The **personal_area_level** and/or **business_area_level** attributes may be one of the following:

.. csv-table::
   :header: "Value", "Description"

   "Worldwide", "Address from any country can be used"
   "country", "Address must be within the requirement country"

The following requests allows you to retrieve resources and services related to regulation of your DIDWW account.

 .. toctree::
    :maxdepth: 2

    identities/index
    addresses/index
    requirements/index
    address-verifications/index
    supporting-document-templates/index
    encrypted-files/index
    proofs/index
    permanent-documents/index
    proof-types/index
    areas/index


.. |br| raw:: html

   <br />

.. _address_requirements_v34:

.. _requirements_v34:

====================
Address Requirements
====================

Returns the list of address requirements per country.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-address-requirement.rst
  get-address-requirements.rst
  address-requirement-object.rst
  address-requirement-validations.rst




=======================
Get Address Requirement
=======================

Returns a single address requirement.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/address_requirements/{id}``

.. note:: For all returned data attributes, see :doc:`Address Requirement Object <address-requirement-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Address Requirement."
   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "personal_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "business_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "personal_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "business_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "personal_proof_types", ":ref:`Proof Type Object <proof_types_object_v34>`"
   "business_proof_types", ":ref:`Proof Type Object <proof_types_object_v34>`"
   "address_proof_types", ":ref:`Proof Type Object <proof_types_object_v34>`"

Example
=======

.. http:example:: curl

    GET /v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171 HTTP/1.1
    Host: api.didww.com
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    Api-Key: [API token]

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
            "type": "address_requirements",
            "attributes": {
                "identity_type": "business",
                "personal_area_level": null,
                "business_area_level": "world_wide",
                "address_area_level": "area",
                "personal_proof_qty": 0,
                "business_proof_qty": 1,
                "address_proof_qty": 1,
                "personal_mandatory_fields": null,
                "business_mandatory_fields": null,
                "service_description_required": true,
                "restriction_message": "Ireland Local DID registration requirements:\r\n\r\n1. Name, business name and contact phone number.\r\n2. Current address in Ireland, must be from the same area in Ireland as DID ordered (street, building number, postal code, city).\r\n\r\nDID number will not be activated until full registration details are provided and approved."
            },
            "relationships": {
                "country": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                    }
                },
                "did_group_type": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                    }
                },
                "personal_permanent_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_permanent_document",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_permanent_document"
                    }
                },
                "business_permanent_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_permanent_document",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_permanent_document"
                    }
                },
                "personal_onetime_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_onetime_document",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_onetime_document"
                    }
                },
                "business_onetime_document": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_onetime_document",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_onetime_document"
                    }
                },
                "personal_proof_types": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_proof_types",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_proof_types"
                    }
                },
                "business_proof_types": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_proof_types",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_proof_types"
                    }
                },
                "address_proof_types": {
                    "links": {
                        "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/address_proof_types",
                        "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/address_proof_types"
                    }
                }
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 




.. _address_requirement_object_v34:

.. _requirements_object_v34:

==========================
Address Requirement Object
==========================

Address requirement object attributes. The JSON:API resource type is ``address_requirements``.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "identity_type", "``string``", "Identity type, possible values: ``any, business`` or ``personal``."
   "personal_area_level", "``string``", "Required location proof for Personal Identity. Possible values: ``world_wide``, ``country``."
   "business_area_level", "``string``", "Required location proof for Business Identity. Possible values: ``world_wide``, ``country``."
   "address_area_level", "``string``", "Required location proof for Address. Possible values: ``world_wide``, ``country``, ``area``, ``city``."
   "restriction_message", "``string``", "The message with requirements for specific Country/Area."
   "personal_proof_qty", "``integer``", "The quantity of proof documents required for Personal Identity."
   "business_proof_qty", "``integer``", "The quantity of proof documents required for Business Identity."
   "address_proof_qty", "``integer``", "The quantity of proof documents required for Address."
   "personal_mandatory_fields", "``array[string]``", "Mandatory fields for Personal Identity."
   "business_mandatory_fields", "``array[string]``", "Mandatory fields for Business Identity."
   "service_description_required", "``boolean``", "If Service description is required. Possible values: True/False."

Relationships
-------------

.. csv-table::
   :header: "Name", "Type", "Description"

   "country", "to-one", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", "to-one", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "personal_permanent_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "business_permanent_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "personal_onetime_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "business_onetime_document", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "personal_proof_types", "to-many", ":ref:`Proof Type Object <proof_types_object_v34>`"
   "business_proof_types", "to-many", ":ref:`Proof Type Object <proof_types_object_v34>`"
   "address_proof_types", "to-many", ":ref:`Proof Type Object <proof_types_object_v34>`"


.. |br| raw:: html

   <br />

.. _address_requirement_validations_v34:

.. _requirement_validations_v34:

===============================
Address Requirement Validations
===============================

Checks if the :ref:`Address <addresses_object_v34>` and/or :ref:`Identity <identity_object_v34>` created is valid against the :ref:`Address Requirement <address_requirements_v34>`. The JSON:API resource type is ``address_requirement_validations``.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/address_requirement_validations``

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Title", "Type", "Description"

   "address_requirement", ":ref:`Address Requirement <address_requirement_object_v34>`", "Specifies the address requirement ID."
   "identity", ":ref:`Identity <identity_object_v34>`", "Specifies the identity ID."
   "address", ":ref:`Address <addresses_object_v34>`", "Specifies the address ID."

Examples
========

.. tabs::

   .. tab:: Validation Request Error

     .. http:example:: curl

			POST /v3/address_requirement_validations HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "address_requirement_validations",
			    "relationships": {
			      "address_requirement": {
			        "data": {
			          "id": "ID_of_address_requirement",
			          "type": "address_requirements"
			        }
			      },
			      "address": {
			        "data": {
			          "id": "ID_of_Address",
			          "type": "addresses"
			        }
			      },
			      "identity": {
			        "data": {
			          "id": "ID_of_Identity",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 422 Unprocessable Entity
			Content-Type: application/vnd.api+json

			{
			    "errors": [
			        {
			            "title": "Identity Place of Birth must be Germany",
			            "detail": "Identity Place of Birth must be Germany",
			            "code": "100",
			            "source": {
			                "pointer": "/data"
			            },
			            "status": "422"
			        },
			        {
			            "title": "2 Identity Proof(s) (Drivers License, National ID, Passport, Residence Permit, Visa, Other) required",
			            "detail": "2 Identity Proof(s) (Drivers License, National ID, Passport, Residence Permit, Visa, Other) required",
			            "code": "100",
			            "source": {
			                "pointer": "/data"
			            },
			            "status": "422"
			        },
			        {
			            "title": "Address in Germany required",
			            "detail": "Address in Germany required",
			            "code": "100",
			            "source": {
			                "pointer": "/data"
			            },
			            "status": "422"
			        }
			    ]
			}

   .. tab:: Validation Request Success

     .. http:example:: curl

			POST /v3/address_requirement_validations HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "address_requirement_validations",
			    "relationships": {
			      "address_requirement": {
			        "data": {
			          "id": "ID_of_address_requirement",
			          "type": "address_requirements"
			        }
			      },
			      "address": {
			        "data": {
			          "id": "ID_of_Address",
			          "type": "addresses"
			        }
			      },
			      "identity": {
			        "data": {
			          "id": "ID_of_Identity",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 201 Created
			Content-Type: application/vnd.api+json

			{
			    "data":
			        {
			            "id": "3553253a-99eb-4303-a16a-6b1042d3f147",
			            "type": "address_requirement_validations"
			            },
			        "meta": {"api_version": "2026-04-16"}
			}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 




========================
Get Address Requirements
========================

Returns the list of address requirements.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/address_requirements``

.. note:: For all returned data attributes, see :doc:`Address Requirement Object <address-requirement-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[address_requirements]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "country", ":ref:`Country Object <country_object_v34>`"
   "did_group_type", ":ref:`DID Group Type Object <did_group_type_object_v34>`"
   "personal_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "business_permanent_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "personal_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "business_onetime_document", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "personal_proof_types", ":ref:`Proof Type Object <proof_types_object_v34>`"
   "business_proof_types", ":ref:`Proof Type Object <proof_types_object_v34>`"
   "address_proof_types", ":ref:`Proof Type Object <proof_types_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "id", "``string``", "No", "Yes", "Address requirement ``id`` field."
   "country.id", "``string``", "Yes", "Yes", "The ``country.id`` field."
   "did_group_type.id", "``string``", "Yes", "Yes", "The ``did_group_type.id`` field."

Available Mandatory Fields
--------------------------

.. important:: The ``personal_mandatory_fields`` and ``business_mandatory_fields`` arrays in the response may contain a selection of the fields listed below, depending on the specific requirement.

.. tabs::

    .. tab:: Personal

          .. csv-table::
             :header: "Value", "Description"

             "birth_date", "The user's date of birth."
             "country", "The user's country of tax residence."
             "birth_country", "The user's country of birth."
             "id_number", "The user's national identification number."
             "personal_tax_id", "The user's personal tax identification number."
             "contact_email", "The user's contact email address."

    .. tab:: Business

          .. csv-table::
             :header: "Value", "Description"

             "id_number", "The national ID number of the company's legal representative."
             "vat_id", "The company's Value Added Tax (VAT) identification number."
             "country", "The country where the company is registered."
             "company_reg_number", "The company's official registration number."
             "personal_tax_id", "The personal tax ID of the company's legal representative."
             "contact_email", "The contact email of the company's representative."

Example
=======

.. tabs::

    .. tab:: Simple Request

        .. http:example:: curl

            GET /v3/address_requirements HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "3f3be6a6-a513-4509-bd9b-945e599e16f5",
                        "type": "address_requirements",
                        "attributes": {
                            "identity_type": "any",
                            "personal_area_level": "world_wide",
                            "business_area_level": "world_wide",
                            "address_area_level": "area",
                            "personal_proof_qty": 0,
                            "business_proof_qty": 0,
                            "address_proof_qty": 0,
                            "personal_mandatory_fields": null,
                            "business_mandatory_fields": null,
                            "service_description_required": true,
                            "restriction_message": "Restriction message"
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/country",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/country"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/did_group_type",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/did_group_type"
                                }
                            },
                            "personal_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/personal_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/personal_permanent_document"
                                }
                            },
                            "business_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/business_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/business_permanent_document"
                                }
                            },
                            "personal_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/personal_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/personal_onetime_document"
                                }
                            },
                            "business_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/business_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/business_onetime_document"
                                }
                            },
                            "personal_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/personal_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/personal_proof_types"
                                }
                            },
                            "business_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/business_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/business_proof_types"
                                }
                            },
                            "address_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/relationships/address_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/3f3be6a6-a513-4509-bd9b-945e599e16f5/address_proof_types"
                                }
                            }
                        }
                    },
                    {
                        "id": "d210e6e4-1716-4342-b04c-7a6ef6feb171",
                        "type": "address_requirements",
                        "attributes": {
                            "identity_type": "business",
                            "personal_area_level": null,
                            "business_area_level": "world_wide",
                            "address_area_level": "area",
                            "personal_proof_qty": 0,
                            "business_proof_qty": 1,
                            "address_proof_qty": 1,
                            "personal_mandatory_fields": null,
                            "business_mandatory_fields": null,
                            "service_description_required": true,
                            "restriction_message": "Ireland Local DID registration requirements:\r\n\r\n1. Name, business name and contact phone number.\r\n2. Current address in Ireland, must be from the same area in Ireland as DID ordered (street, building number, postal code, city).\r\n\r\nDID number will not be activated until full registration details are provided and approved."
                        },
                        "relationships": {
                            "country": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/country",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/country"
                                }
                            },
                            "did_group_type": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/did_group_type",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/did_group_type"
                                }
                            },
                            "personal_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_permanent_document"
                                }
                            },
                            "business_permanent_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_permanent_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_permanent_document"
                                }
                            },
                            "personal_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_onetime_document"
                                }
                            },
                            "business_onetime_document": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_onetime_document",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_onetime_document"
                                }
                            },
                            "personal_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/personal_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/personal_proof_types"
                                }
                            },
                            "business_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/business_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/business_proof_types"
                                }
                            },
                            "address_proof_types": {
                                "links": {
                                    "self": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/relationships/address_proof_types",
                                    "related": "https://sandbox-api.didww.com/v3/address_requirements/d210e6e4-1716-4342-b04c-7a6ef6feb171/address_proof_types"
                                }
                            }
                        }
                    }
                ],
                "meta": {
                    "total_records": 2,
                    "api_version": "2026-04-16"
                },
                "links": {
                    "first": "https://sandbox-api.didww.com/v3/address_requirements?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                    "last": "https://sandbox-api.didww.com/v3/address_requirements?page%5Bnumber%5D=1&page%5Bsize%5D=50"
                }
            }

    .. tab:: Filter by country.id (i.e. Germany)

        .. http:example:: curl

            GET /v3/address_requirements?filter[country.id]=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data":    [
                        {
                     "id": "3553253a-99eb-4303-a16a-6b1042d3f147",
                     "type": "address_requirements",
                     "attributes":          {
                        "identity_type": "any",
                        "personal_area_level": "world_wide",
                        "business_area_level": "country",
                        "address_area_level": "country",
                        "personal_proof_qty": 1,
                        "business_proof_qty": 1,
                        "address_proof_qty": 1,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["country"],
                        "service_description_required": false,
                        "restriction_message": "German National DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n* Germany registration form<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n* Germany registration form<br>\r\nFor <b>address<\/b> verification:\r\n* Address in Germany (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)<br>\r\nThe number provided online is a <b>demo<\/b>. An active number will be provided when the registration process is complete.<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/country",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/3553253a-99eb-4303-a16a-6b1042d3f147/address_proof_types"
                        }}
                     }
                  },
                        {
                     "id": "229310cf-21c1-41f0-9cfb-c4ea133304d5",
                     "type": "address_requirements",
                     "attributes":          {
                        "identity_type": "any",
                        "personal_area_level": "world_wide",
                        "business_area_level": "country",
                        "address_area_level": "city",
                        "personal_proof_qty": 1,
                        "business_proof_qty": 1,
                        "address_proof_qty": 1,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["country"],
                        "service_description_required": false,
                        "restriction_message": "German Local DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n* Germany registration form<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n* Germany registration form<br>\r\nFor <b>address<\/b> verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)<br>\r\nThe number provided online is a <b>demo<\/b>. An active number will be provided when the registration process is complete.<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/country",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/229310cf-21c1-41f0-9cfb-c4ea133304d5/address_proof_types"
                        }}
                     }
                  }
               ],
               "meta":    {
                  "total_records": 2,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_requirements?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_requirements?filter%5Bcountry.id%5D=38003e8b-cccc-41d4-b1a6-d1e6fddf2c0f&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

    .. tab:: Filter by did_group_type.id (i.e. Shared-Cost)

        .. http:example:: curl

            GET /v3/address_requirements?filter[did_group_type.id]=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data":    [
                        {
                     "id": "5558cecd-cf91-4189-ad77-0f21518eb0d9",
                     "type": "address_requirements",
                     "attributes":          {
                        "identity_type": "any",
                        "personal_area_level": "world_wide",
                        "business_area_level": "world_wide",
                        "address_area_level": "world_wide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 0,
                        "address_proof_qty": 0,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": null,
                        "service_description_required": false,
                        "restriction_message": "Australian Shared Cost DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/country",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/address_proof_types"
                        }}
                     }
                  },
                        {
                     "id": "469d5cb4-baf6-4639-a500-f3bd04e89861",
                     "type": "address_requirements",
                     "attributes":          {
                        "identity_type": "business",
                        "personal_area_level": null,
                        "business_area_level": "world_wide",
                        "address_area_level": "world_wide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 2,
                        "address_proof_qty": 2,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["id_number"],
                        "service_description_required": true,
                        "restriction_message": "Chinese Shared Cost DID End User registration requirements:<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport\r\n* Company name\r\n* Company incorporation certificate copy<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)\r\n* 2 copies of utility bills (less than 6 months old)<br>\r\nAdditional information:\r\n* Service usage description<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/country",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/country"
                        }},
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/address_proof_types"
                        }}
                     }
                  }
               ],
               "meta":    {
                  "total_records": 2,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

    .. tab:: Include country while filtered by did_group_type.id

        .. http:example:: curl

            GET /v3/address_requirements?filter[did_group_type.id]=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&include=country HTTP/1.1
            Host: api.didww.com
            Content-Type: application/vnd.api+json
            Accept: application/vnd.api+json
            Api-Key: [API token]

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
               "data":    [
                        {
                     "id": "5558cecd-cf91-4189-ad77-0f21518eb0d9",
                     "type": "address_requirements",
                     "attributes":          {
                        "identity_type": "any",
                        "personal_area_level": "world_wide",
                        "business_area_level": "world_wide",
                        "address_area_level": "world_wide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 0,
                        "address_proof_qty": 0,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": null,
                        "service_description_required": false,
                        "restriction_message": "Australian Shared Cost DID End User registration requirements:<br>\r\nFor <b>personal identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country":             {
                           "links":                {
                              "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/country",
                              "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/country"
                           },
                           "data":                {
                              "type": "countries",
                              "id": "afeb1a21-abb4-4983-8712-7ab44950fc16"
                           }
                        },
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/5558cecd-cf91-4189-ad77-0f21518eb0d9/address_proof_types"
                        }}
                     }
                  },
                        {
                     "id": "469d5cb4-baf6-4639-a500-f3bd04e89861",
                     "type": "address_requirements",
                     "attributes":          {
                        "identity_type": "business",
                        "personal_area_level": null,
                        "business_area_level": "world_wide",
                        "address_area_level": "world_wide",
                        "personal_proof_qty": 0,
                        "business_proof_qty": 2,
                        "address_proof_qty": 2,
                        "personal_mandatory_fields": null,
                        "business_mandatory_fields": ["id_number"],
                        "service_description_required": true,
                        "restriction_message": "Chinese Shared Cost DID End User registration requirements:<br>\r\nFor <b>business identity<\/b> verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport\r\n* Company name\r\n* Company incorporation certificate copy<br>\r\nFor <b>address<\/b> verification:\r\n* Address worldwide (street, building number, postal code, city and country)\r\n* 2 copies of utility bills (less than 6 months old)<br>\r\nAdditional information:\r\n* Service usage description<br>\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.<br>\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process.<br>\r\n"
                     },
                     "relationships":          {
                        "country":             {
                           "links":                {
                              "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/country",
                              "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/country"
                           },
                           "data":                {
                              "type": "countries",
                              "id": "7006e60d-d2c7-4479-94ad-b954038e6dde"
                           }
                        },
                        "did_group_type": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/did_group_type",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/did_group_type"
                        }},
                        "personal_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_permanent_document"
                        }},
                        "business_permanent_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_permanent_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_permanent_document"
                        }},
                        "personal_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_onetime_document"
                        }},
                        "business_onetime_document": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_onetime_document",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_onetime_document"
                        }},
                        "personal_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/personal_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/personal_proof_types"
                        }},
                        "business_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/business_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/business_proof_types"
                        }},
                        "address_proof_types": {"links":             {
                           "self": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/relationships/address_proof_types",
                           "related": "https://api.didww.com/v3/address_requirements/469d5cb4-baf6-4639-a500-f3bd04e89861/address_proof_types"
                        }}
                     }
                  }
               ],
               "included":    [
                        {
                     "id": "afeb1a21-abb4-4983-8712-7ab44950fc16",
                     "type": "countries",
                     "attributes":          {
                        "name": "Australia",
                        "prefix": "61",
                        "iso": "AU"
                     },
                     "relationships": {"regions": {"links":          {
                        "self": "https://api.didww.com/v3/countries/afeb1a21-abb4-4983-8712-7ab44950fc16/relationships/regions",
                        "related": "https://api.didww.com/v3/countries/afeb1a21-abb4-4983-8712-7ab44950fc16/regions"
                     }}}
                  },
                        {
                     "id": "7006e60d-d2c7-4479-94ad-b954038e6dde",
                     "type": "countries",
                     "attributes":          {
                        "name": "China",
                        "prefix": "86",
                        "iso": "CN"
                     },
                     "relationships": {"regions": {"links":          {
                        "self": "https://api.didww.com/v3/countries/7006e60d-d2c7-4479-94ad-b954038e6dde/relationships/regions",
                        "related": "https://api.didww.com/v3/countries/7006e60d-d2c7-4479-94ad-b954038e6dde/regions"
                     }}}
                  }
               ],
               "meta":    {
                  "total_records": 2,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/address_requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/address_requirements?filter%5Bdid_group_type.id%5D=f2ff69ed-0d6b-4d66-b4bb-9ae2aa1d6b1e&include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

.. _supporting_document_template_v34:

=============================
Supporting Document Templates
=============================

Retrieves a list of supporting document templates that may be required in certain countries by regulation.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-supporting-document-template.rst
  get-supporting-document-templates.rst
  supporting-document-templates-object.rst
  
  
  




=================================
Get Supporting Document Templates
=================================

Returns a single supporting document template. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/supporting_document_templates/``

.. note:: For all returned data attributes, see :doc:`Supporting Document Templates Object <supporting-document-templates-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Template."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
    .. http:example:: curl

		GET /v3/supporting_document_templates/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
		Host: api.didww.com
		Content-Type: application/vnd.api+json
		Accept: application/vnd.api+json
		Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": {
		        "id": "206ccec2-1166-461f-9f58-3a56823db548",
		        "type": "supporting_document_templates",
		        "attributes": {
		            "name": "Generic LOI",
		            "permanent": false,
		            "url": "https://sandbox-api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn"
		        }
		    },
		    "meta": {
		        "api_version": "2026-04-16"
		    }
		}
      





=================================
Get Supporting Document Templates
=================================

Lists all supporting document templates. 

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/supporting_document_templates``

.. note:: For all returned data attributes, see :doc:`Supporting Document Templates Object <supporting-document-templates-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``, ``boolean``", "No", ":ref:`Filtering <api_filters>`"
   "fields[supporting_document_templates]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
  
Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "permanent", "``boolean``", "No", "No", "The ``permanent`` field."
   "name", "``string``", "No", "No", "The ``name`` field exact match."
   "name_contains", "``string``", "No", "No", "The ``name`` field contains."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
    .. http:example:: curl

		GET /v3/supporting_document_templates HTTP/1.1
		Host: api.didww.com
		Content-Type: application/vnd.api+json
		Accept: application/vnd.api+json
		Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

		{
		    "data": [
		        {
		            "id": "206ccec2-1166-461f-9f58-3a56823db548",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Generic LOI",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn"
		            }
		        },
		        {
		            "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Belgium Registration Form",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra"
		            }
		        },
		        {
		            "id": "4199435f-646e-4e9d-a143-8f3b972b10c5",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Germany Special Registration Form",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/4rghqnqtba0fa7mbdgig086xej1e"
		            }
		        },
		        {
		            "id": "94be4d74-c968-4d81-91c5-2d11b4e45328",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "LOI Example",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/xptvgb8derrz0ru95wr9oi68g9tg"
		            }
		        },
		        {
		            "id": "eb810289-8620-44e1-982d-13e6cee70404",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "TestPermanDoc",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/owwqi77007ks4qx198b7su3eukg6"
		            }
		        },
		        {
		            "id": "f65149c1-b551-4444-97d7-22939445c42a",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "TestDoc4",
		                "permanent": true,
		                "url": "https://sandbox-api.didww.com/storage/public/txm3ftmuhyhypm6553b2874iuljg"
		            }
		        },
		        {
		            "id": "8aacfda9-f78a-4d17-8d05-82e344bf822d",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "test",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/of8dctya2w8fqf3hxu71a3hcmsa4"
		            }
		        },
		        {
		            "id": "83f83c27-af8d-43f4-a9ca-a84c363e3e25",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Brazilian DIDWW LOA",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/gvbw9l9jcegb5re30afhpu4eisvu"
		            }
		        },
		        {
		            "id": "6da59922-6c98-4cfa-bd0e-ec15f71eb1ff",
		            "type": "supporting_document_templates",
		            "attributes": {
		                "name": "Test34",
		                "permanent": false,
		                "url": "https://sandbox-api.didww.com/storage/public/o9rz29nhi4eoip5obmtuv7w23cvf"
		            }
		        }
		    ],
		    "meta": {
		        "total_records": 30,
		        "api_version": "2026-04-16"
		    },
		    "links": {
		        "first": "https://sandbox-api.didww.com/v3/supporting_document_templates?page%5Bnumber%5D=1&page%5Bsize%5D=50",
		        "last": "https://sandbox-api.didww.com/v3/supporting_document_templates?page%5Bnumber%5D=1&page%5Bsize%5D=50"
		    }
		}

   .. tab:: Filter name_contains

    .. http:example:: curl

		GET /v3/supporting_document_templates?filter[name_contains]=Germany HTTP/1.1
		Host: api.didww.com
		Content-Type: application/vnd.api+json
		Accept: application/vnd.api+json
		Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

            {
               "data": [   {
                  "id": "a6f8fa4f-302b-447a-880f-f68407c67e78",
                  "type": "supporting_document_templates",
                  "attributes":       {
                     "name": "Germany Registration Form",
                     "permanent": true,
                     "url": "https://api.didww.com/storage/public/kb5ovqxc43xhompzcrhh6e3fz7mo"
                  }
               }],
               "meta":    {
                  "total_records": 1,
                  "api_version": "2026-04-16"
               },
               "links":    {
                  "first": "https://api.didww.com/v3/supporting_document_templates?filter%5Bname_contains%5D=Germany&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                  "last": "https://api.didww.com/v3/supporting_document_templates?filter%5Bname_contains%5D=Germany&page%5Bnumber%5D=1&page%5Bsize%5D=50"
               }
            }


.. _supporting_document_templates_object_v34:

===================================
Supporting Document Template Object
===================================

Supporting Document Template Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "Name of the template"
   "url", "``string``", "URL of the template."
   "permanent", "``boolean``", "Defines if the template is permanent. Possible values: True/False."

.. |br| raw:: html

   <br />

.. _proofs_v34:

======
Proofs
======

Allows creating, retrieving, or deleting identity proofs.

Supported methods: ``GET``, ``POST``, ``DELETE``.

.. toctree::
  :maxdepth: 1

  get-proof.rst
  get-proofs.rst
  create-proof.rst
  delete-proof.rst
  proofs-object.rst


=========
Get Proof
=========

Returns a single proof in the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/proofs/{id}``

.. note:: For all returned data attributes, see :doc:`Proofs Object <proofs-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the proof."
   "include", "``string``", "No", "Related resources to include in the response. See :ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "entity", ":ref:`Identity Object <identity_object_v34>` or :ref:`Address Object <addresses_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/proofs/84155378-88d5-456e-844d-103596e3fb2c HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "84155378-88d5-456e-844d-103596e3fb2c",
                "type": "proofs",
                "attributes": {
                    "created_at": "2021-03-28T18:01:50.387Z",
                    "expires_at": null,
                    "external_reference_id": null
                },
                "relationships": {
                    "proof_type": {
                        "links": {
                            "self": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
                            "related": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
                        }
                    },
                    "entity": {
                        "links": {
                            "self": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
                            "related": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

============
Create Proof
============

Creates an identity proof. 

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/proofs``

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "external_reference_id", "``string``", "No", "Optional identifier for the proof in the customer's external system. Maximum length is 100 characters."

Request Body Object Relationships
---------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "files", "``string``", "Yes", "The ID of :ref:`encrypted files <encrypted_files_object_v34>` associated to this proof."
   "proof_types", "``string``", "Yes", "The ID of :ref:`proof type <proof_types_object_v34>` associated to this proof."
   "entity", "``string``", "Yes", "Allowed entity types: ``identities`` or ``addresses``"

Examples
========

.. tabs::

   .. tab:: Resource Creation Example: Identities
   
     .. http:example:: curl

			POST /v3/proofs HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
			{
			  "data": {
			    "type": "proofs",
			    "relationships": {
			      "files": {
			        "data": [
			          {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files"
			          }
			        ]
			      },
			      "proof_type": {
			        "data": {
			          "id": "d2c1b3fb-29f7-46ca-ba82-b617f4630b78",
			          "type": "proof_types"
			        }
			      },
			      "entity": {
			        "data": {
			          "id": "54c92d8e-f135-4b55-ac48-748d44437509",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}	
			
			
			HTTP/1.1 201 Created
			Content-Type: application/vnd.api+json
		
			{
			    "data": {
			        "id": "84155378-88d5-456e-844d-103596e3fb2c",
			        "type": "proofs",
			        "attributes": {
			            "created_at": "2021-03-28T18:01:50.387Z",
			            "expires_at": null,
			            "external_reference_id": null
			        },
			        "relationships": {
			            "proof_type": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
			                }
			            },
			            "entity": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
			                }
			            }
			        }
			    },
			    "meta": {
			        "api_version": "2026-04-16"
			    }
			}

   .. tab:: Resource Creation Example: Addresses

     .. http:example:: curl

			POST /v3/proofs HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "proofs",
			    "relationships": {
			      "files": {
			        "data": [
			          {
			            "id": "cc52b6b3-0627-47d3-a1c9-b54d3de42813",
			            "type": "encrypted_files"
			          }
			        ]
			      },
			      "proof_type": {
			        "data": {
			          "id": "d2c1b3fb-29f7-46ca-ba82-b617f4630b78",
			          "type": "proof_types"
			        }
			      },
			      "entity": {
			        "data": {
			          "id": "54c92d8e-f135-4b55-ac48-748d44437509",
			          "type": "addresses"
			        }
			      }
			    }
			  }
			}

			HTTP/1.1 201 Created
			Content-Type: application/vnd.api+json

			{
			    "data": {
			        "id": "84155378-88d5-456e-844d-103596e3fb2c",
			        "type": "proofs",
			        "attributes": {
			            "created_at": "2021-03-28T18:01:50.387Z",
			            "expires_at": null,
			            "external_reference_id": null
			        },
			        "relationships": {
			            "proof_type": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
			                }
			            },
			            "entity": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
			                    "related": "https://sandbox-api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
			                }
			            }
			        }
			    },
			    "meta": {
			        "api_version": "2026-04-16"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

============
Delete Proof
============

Deletes a proof.

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/proofs/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Proof."

Examples
========

.. tabs::

   .. tab:: Example
   
     .. http:example:: curl

			DELETE /v3/proofs/ed46925b-a830-482d-917d-015858cf7ab9 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
		
		    HTTP/1.1 204 No Content
		    Content-Type: application/vnd.api+json

   

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


==============
Get Proofs
==============

Returns a list of proofs on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/proofs``

.. note:: For all returned data attributes, see :doc:`Proofs Object <proofs-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[proofs]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "proof_type", ":ref:`Proof Types Object <proof_types_object_v34>`"
   "entity", ":ref:`Identity Object <identity_object_v34>` or :ref:`Address Object <addresses_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "created_at", "The ``created_at`` field."
   "expires_at", "The ``expires_at`` field."
   "external_reference_id", "The ``external_reference_id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/proofs HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "84155378-88d5-456e-844d-103596e3fb2c",
                    "type": "proofs",
                    "attributes": {
                        "created_at": "2021-03-28T18:01:50.387Z",
                        "expires_at": null,
                        "external_reference_id": null
                    },
                    "relationships": {
                        "proof_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
                                "related": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
                            }
                        },
                        "entity": {
                            "links": {
                                "self": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
                                "related": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/proofs?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/proofs?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter external_reference_id

    .. http:example:: curl

        GET /v3/proofs?filter[external_reference_id]=proof-001 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "84155378-88d5-456e-844d-103596e3fb2c",
                    "type": "proofs",
                    "attributes": {
                        "created_at": "2021-03-28T18:01:50.387Z",
                        "expires_at": null,
                        "external_reference_id": "proof-001"
                    },
                    "relationships": {
                        "proof_type": {
                            "links": {
                                "self": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/proof_type",
                                "related": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/proof_type"
                            }
                        },
                        "entity": {
                            "links": {
                                "self": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/relationships/entity",
                                "related": "https://api.didww.com/v3/proofs/84155378-88d5-456e-844d-103596e3fb2c/entity"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/proofs?filter%5Bexternal_reference_id%5D=proof-001&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/proofs?filter%5Bexternal_reference_id%5D=proof-001&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _proofs_object_v34:

=============
Proofs Object
=============

Proofs Object attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "expires_at", "``Date&Time``", "Proof expiration date."
   "created_at", "``Date&Time``", "Proof creation date."
   "external_reference_id", "``string``", "Optional identifier for the proof in the customer's external system. Maximum length is 100 characters."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "proof_type", "to-one", ":ref:`Proof Types Object <proof_types_object_v34>`. Returns the proof type linked to the proof."
   "entity", "to-one", ":ref:`Identity Object <identity_object_v34>` or :ref:`Addresses Object <addresses_object_v34>`. Returns the entity linked to the proof."


.. |br| raw:: html

   <br />

.. _permanent_documents_v34:

==============================
Permanent Supporting Documents
==============================

Allows creating, retrieving, or deleting permanent documents.

Supported methods: ``GET``, ``POST``, ``DELETE``.

.. toctree::
  :maxdepth: 1

  get-permanent-document.rst
  get-permanent-documents.rst
  create-permanent-document.rst
  delete-permanent-document.rst
  permanent-documents-object.rst


=================================
Get Permanent Supporting Document
=================================

Returns a single permanent supporting document in the account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/permanent_supporting_documents/{id}``

.. note:: For all returned data attributes, see :doc:`Permanent Supporting Documents Object <permanent-documents-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the permanent supporting document."
   "include", "``string``", "No", "Related resources to include in the response. See :ref:`Inclusion <api_includes>`."

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "identity", ":ref:`Identity Object <identity_object_v34>`"

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": {
                "id": "d1a1a686-969a-4c02-954c-ae500ba74a1d",
                "type": "permanent_supporting_documents",
                "attributes": {
                    "created_at": "2021-03-28T18:51:59.590Z",
                    "external_reference_id": null
                },
                "relationships": {
                    "template": {
                        "links": {
                            "self": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/template",
                            "related": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/template"
                        }
                    },
                    "identity": {
                        "links": {
                            "self": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/identity",
                            "related": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/identity"
                        }
                    }
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "404", "No", ":ref:`Not Found <api_not_found>`"
   "401", "No", ":ref:`Unauthorized <api_key>`"


.. |br| raw:: html

   <br />

.. _create_permanent_supporting_document_v34:

====================================
Create Permanent Supporting Document
====================================

Creates a permanent supporting document.

Request
=======

HTTP Method: ``POST``

URI Path: ``/v3/permanent_supporting_documents``

URI Query Parameters
--------------------

Request Body Object Attributes
------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "external_reference_id", "``string``", "No", "Optional identifier for the permanent supporting document in the customer's external system. Maximum length is 100 characters."

Request Body Object Relationship
--------------------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "files", "``string``", "Yes", "The ID of :ref:`encrypted files <encrypted_files_object_v34>`."
   "template", "``string``", "Yes", "The ID of :ref:`supporting documents <supporting_document_templates_object_v34>`."
   "identity", "``string``", "Yes", "The ID of :ref:`identity <identity_object_v34>`."

Examples
========

.. tabs::

   .. tab:: Example

     .. http:example:: curl

			POST /v3/permanent_supporting_documents HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			{
			  "data": {
			    "type": "permanent_supporting_documents",
			    "relationships": {
			      "files": {
			        "data": [
			          {
			            "id": "94ec30ef-9f9c-49d6-97a9-d76e93b818c5",
			            "type": "encrypted_files"
			          }
			        ]
			      },
			      "template": {
			        "data": {
			          "id": "47051582-bbe6-4d68-95f5-d7322bbaa74e",
			          "type": "supporting_document_templates"
			        }
			      },
			      "identity": {
			        "data": {
			          "id": "01798514-ccf8-495b-b4ee-01b91c533e53",
			          "type": "identities"
			        }
			      }
			    }
			  }
			}

		    HTTP/1.1 201 Created
		    Content-Type: application/vnd.api+json

			{
			    "data": {
			        "id": "d1a1a686-969a-4c02-954c-ae500ba74a1d",
			        "type": "permanent_supporting_documents",
			        "attributes": {
			            "created_at": "2021-03-28T18:51:59.590Z",
			            "external_reference_id": null
			        },
			        "relationships": {
			            "template": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/template",
			                    "related": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/template"
			                }
			            },
			            "identity": {
			                "links": {
			                    "self": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/identity",
			                    "related": "https://sandbox-api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/identity"
			                }
			            }
			        }
			    },
			    "meta": {
			        "api_version": "2026-04-16"
			    }
			}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

====================================
Delete Permanent Supporting Document
====================================

Deletes a permanent document. 

Request
=======

HTTP Method: ``DELETE``

URI Path: ``/v3/permanent_supporting_documents/{id}``

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of Permanent supporting document."

Examples
========

.. tabs::

   .. tab:: Example
   
     .. http:example:: curl

			DELETE /v3/permanent_supporting_documents/19510da3-c07e-4fa9-a696-6b9ab89cc172 HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
        
		
		    HTTP/1.1 204 No Content
		    Content-Type: application/vnd.api+json

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


==================================
Get Permanent Supporting Documents
==================================

Returns a list of permanent supporting documents on your account.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/permanent_supporting_documents``

.. note:: For all returned data attributes, see :doc:`Permanent Supporting Documents Object <permanent-documents-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "include", "``string``", "No", ":ref:`Inclusion <api_includes>`"
   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[permanent_supporting_documents]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"
   "sort", "``string``", "No", ":ref:`Sorting <api_sorting>`"

Includes
--------

.. csv-table::
   :header: "Value", "Description"

   "template", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`"
   "identity", ":ref:`Identity Object <identity_object_v34>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "external_reference_id", "``string``", "No", "No", "The ``external_reference_id`` field."

Sorting
-------

.. csv-table::
   :header: "Value", "Sorts by:"

   "created_at", "The ``created_at`` field."
   "external_reference_id", "The ``external_reference_id`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request

    .. http:example:: curl

        GET /v3/permanent_supporting_documents HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "d1a1a686-969a-4c02-954c-ae500ba74a1d",
                    "type": "permanent_supporting_documents",
                    "attributes": {
                        "created_at": "2021-03-28T18:51:59.590Z",
                        "external_reference_id": null
                    },
                    "relationships": {
                        "template": {
                            "links": {
                                "self": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/template",
                                "related": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/template"
                            }
                        },
                        "identity": {
                            "links": {
                                "self": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/identity",
                                "related": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/identity"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/permanent_supporting_documents?page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/permanent_supporting_documents?page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

   .. tab:: Filter external_reference_id

    .. http:example:: curl

        GET /v3/permanent_supporting_documents?filter[external_reference_id]=doc-001 HTTP/1.1
        Host: api.didww.com
        Content-Type: application/vnd.api+json
        Accept: application/vnd.api+json
        Api-Key: [API token]

        HTTP/1.1 200 OK
        Content-Type: application/vnd.api+json

        {
            "data": [
                {
                    "id": "d1a1a686-969a-4c02-954c-ae500ba74a1d",
                    "type": "permanent_supporting_documents",
                    "attributes": {
                        "created_at": "2021-03-28T18:51:59.590Z",
                        "external_reference_id": "doc-001"
                    },
                    "relationships": {
                        "template": {
                            "links": {
                                "self": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/template",
                                "related": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/template"
                            }
                        },
                        "identity": {
                            "links": {
                                "self": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/relationships/identity",
                                "related": "https://api.didww.com/v3/permanent_supporting_documents/d1a1a686-969a-4c02-954c-ae500ba74a1d/identity"
                            }
                        }
                    }
                }
            ],
            "meta": {
                "total_records": 1,
                "api_version": "2026-04-16"
            },
            "links": {
                "first": "https://api.didww.com/v3/permanent_supporting_documents?filter%5Bexternal_reference_id%5D=doc-001&page%5Bnumber%5D=1&page%5Bsize%5D=50",
                "last": "https://api.didww.com/v3/permanent_supporting_documents?filter%5Bexternal_reference_id%5D=doc-001&page%5Bnumber%5D=1&page%5Bsize%5D=50"
            }
        }

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401", "No", ":ref:`Unauthorized <api_key>`"


.. _permanent_documents_object_v34:

=====================================
Permanent Supporting Documents Object
=====================================

Permanent documents attributes.

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "created_at", "``Date&Time``", "Permanent documents creation date."
   "external_reference_id", "``string``", "Optional identifier for the permanent supporting document in the customer's external system. Maximum length is 100 characters."

Relationships
=============

.. csv-table::
   :header: "Name", "Type", "Description"

   "template", "to-one", ":ref:`Supporting Document Template Object <supporting_document_templates_object_v34>`. Returns the template linked to the permanent supporting document."
   "identity", "to-one", ":ref:`Identity Object <identity_object_v34>`. Returns the identity linked to the permanent supporting document."


.. |br| raw:: html

   <br />

.. _proof_types_v34:

===========
Proof Types
===========

Returns a single or a list of Proof Types for identities and addresses.

Supported methods: ``GET``

.. toctree::
  :maxdepth: 1
  
  get-proof-type.rst
  get-proof-types.rst
  proof-types-object.rst
  
  
  
  


.. |br| raw:: html

   <br />

==============
Get Proof Type
==============

Returns a single proof type.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/proof_types/``

.. note:: For all returned data attributes, see :doc:`Proof Types Object <proof-types-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "id", "``string``", "Yes", "Unique ID identifier of the Proof Type."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
     .. http:example:: curl

			GET /v3/proof_types/c8e004b0-87ec-4987-b4fb-ee89db099f0e HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
			    "data": {
			        "id": "ab1fb565-ac55-4c73-bc55-64dc61e70169",
			        "type": "proof_types",
			        "attributes": {
			            "name": "Utility Bill",
			            "entity_type": "Address"
			        }
			    },
			    "meta": {
			        "api_version": "2026-04-16"
			    }
			}

    
Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. |br| raw:: html

   <br />

===============
Get Proof Types
===============

Returns the list of proof types for identities or addresses.

Request
=======

HTTP Method: ``GET``

URI Path: ``/v3/proof_types``

.. note:: For all returned data attributes, see :doc:`Proof Types Object <proof-types-object>`.

URI Query Parameters
--------------------

.. csv-table::
   :header: "Name", "Type", "Is Required?", "Description"

   "filter[<filter_name>]", "``string``", "No", ":ref:`Filtering <api_filters>`"
   "fields[proof_types]", "``string``", "No", ":ref:`Sparse fieldsets <api_sparse_fieldsets>`"

Filters
-------

.. csv-table::
   :header: "Filter Name", "Type", "Allow Blank", "Allow Array", "Filters by:"

   "entity_type", "``string``", "Yes", "Yes", "The ``entity_type`` field."

Examples
========

.. tabs::

   .. tab:: Simple Request
   
	 .. http:example:: curl

			GET /v3/proof_types HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]
		
		
			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json
		
			{
				"data": [
					{
						"id": "d2c1b3fb-29f7-46ca-ba82-b617f4630b78",
						"type": "proof_types",
						"attributes": {
							"name": "Copy of Phone Bill",
							"entity_type": "Address"
						}
					},
					{
						"id": "ab1fb565-ac55-4c73-bc55-64dc61e70169",
						"type": "proof_types",
						"attributes": {
							"name": "Utility Bill",
							"entity_type": "Address"
						}
					},
					{
						"id": "634aea96-43d9-49a2-bd4e-6e8e2ce4e5e9",
						"type": "proof_types",
						"attributes": {
							"name": "Rental Receipt",
							"entity_type": "Address"
						}
					},
					{
						"id": "49f42cbd-d051-43e0-9d30-883e154bad0d",
						"type": "proof_types",
						"attributes": {
							"name": "Other",
							"entity_type": "Address"
						}
					}
				],
				"meta": {
					"total_records": 4,
					"api_version": "2026-04-16"
				}
			}

   .. tab:: Filter by entity_type

	 .. http:example:: curl

			GET /v3/proof_types?filter[entity_type]=Address HTTP/1.1
			Host: api.didww.com
			Content-Type: application/vnd.api+json
			Accept: application/vnd.api+json
			Api-Key: [API token]

			HTTP/1.1 200 OK
			Content-Type: application/vnd.api+json

			{
			   "data":    [
						{
					 "id": "58b80af0-81d5-4828-abd8-37ea48f3893d",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Copy of Phone Bill",
						"entity_type": "Address"
					 }
				  },
						{
					 "id": "d29b6637-36fe-477c-941c-19965a81e96c",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Utility Bill",
						"entity_type": "Address"
					 }
				  },
						{
					 "id": "af64c2cb-8db2-4076-a667-9014a48f24a4",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Rental Receipt",
						"entity_type": "Address"
					 }
				  },
						{
					 "id": "9e24acf0-fc18-4079-b546-4f316d0e9003",
					 "type": "proof_types",
					 "attributes":          {
						"name": "Other",
						"entity_type": "Address"
					 }
				  }
			   ],
			   "meta":    {
				  "total_records": 4,
				  "api_version": "2026-04-16"
			   }
			}

Other Responses
===============

.. csv-table::
   :header: "Code", "Success", "Description"

   "401","No",":ref:`Unauthorized <api_key>`" 


.. _proof_types_object_v34:

.. |br| raw:: html

   <br />

==================
Proof Types Object
==================

The proof types object attributes. 

Attributes
==========

.. csv-table::
   :header: "Name", "Type", "Description"

   "name", "``string``", "The name of proof type."
   "entity_type", "``string``", "The entity type: Personal, Business or Address."




API Versioning
---------------

The DIDWW API v3 uses versioning to ensure backward compatibility while enabling new features and enhancements. Versioning is based on the date of your first request using API v3.

    - Each customer is assigned a fixed API version when they first use the API.
    - The version will not change automatically. You are responsible for upgrading via the DIDWW User Panel when ready.
    - New versions may introduce changes to existing behavior or add new parameters and resources.

You can view your current API version in the response metadata field: ``meta.api_version``.

To review or change your current version, visit the `API page in the User Panel <https://my.didww.com/#/api>`_.

----

.. raw:: html

    <br>

Upgrading Your API Version
^^^^^^^^^^^^^^^^^^^^^^^^^^

You may test or adopt a newer API version by including the ``X-DIDWW-API-Version`` header in your requests. This header overrides the default version for the current request only.

.. http:example:: curl

   GET /v3/voice_in_trunk_groups HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Api-Key: [API Token]
   X-DIDWW-API-Version: 2022-05-10

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": [
       {
         "id": "12345678-abcd-4321-efgh-9876543210ab",
         "type": "voice_in_trunk_groups",
         "attributes": {
           "created_at": "2023-09-01T08:06:37.162Z",
           "name": "TG test",
           "capacity_limit": null
         },
         "relationships": {
           "voice_in_trunks": {}
         },
         "meta": {
           "trunks_count": 2
         }
       }
     ],
     "meta": {
       "total_records": 1,
       "api_version": "2022-05-10"
     }
   }

You can manage your default API version in the `DIDWW User Panel <https://my.didww.com/#/api>`_.

.. important::

   - If the ``X-DIDWW-API-Version`` header specifies a version **older** than your currently assigned version, it will be **ignored**.
   - Downgrading your API version is not supported.
   - The ``meta.api_version`` field in the response reflects the version used for that request.

----

.. raw:: html

    <br>

Related Changelogs
^^^^^^^^^^^^^^^^^^

Review the changelog entries to understand the impact of a version upgrade:

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`git-commit` **Version 2021-04-19**
      :link: changelog_2021_04_19
      :link-type: ref

      View changes introduced in API version 2021-04-19.

   .. grid-item-card:: :octicon:`git-commit` **Version 2021-12-15**
      :link: changelog_2021_12_15
      :link-type: ref

      View changes introduced in API version 2021-12-15.

   .. grid-item-card:: :octicon:`git-commit` **Version 2022-05-10**
      :link: changelog_2022_05_10
      :link-type: ref

      View changes introduced in API version 2022-05-10.

   .. grid-item-card:: :octicon:`git-commit` **Version 2026-04-16**
      :link: changelog_2026_04_16
      :link-type: ref

      View changes introduced in API version 2026-04-16.



.. |br| raw:: html

   <br />

.. _user-panel-api-examples-random-dids:
.. _user-panel-api-examples-did-group:
.. _api-examples-buy-available-dids:

====================================
Buy Available DID Number(s)
====================================

This example shows the **end-to-end process for purchasing a DID number**
from DID inventory.

This flow allows the platform to assign an available DID number from the
inventory that matches the selected criteria.

To buy a DID number from DID inventory, follow these steps:

- :ref:`Step 1: Find the Country <user-panel-api-examples-random-dids_step1>`
- :ref:`Step 2: Show Inventory Filters for the Selected Country <user-panel-api-examples-random-dids_step2>`
- :ref:`Step 3: Retrieve DID Availability, Pricing, and Coverage <user-panel-api-examples-random-dids_step3>`
- :ref:`Step 4: Create the Order <user-panel-api-examples-random-dids_step4>`

.. note::

   The UUIDs shown in the examples below are for illustration purposes only.

   Always execute requests in your own environment and use the UUIDs returned in API responses.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-random-dids_step1:

Step 1: Find the Country ID
===========================

Retrieve the unique ID for the target country using the ``/countries`` endpoint.
From the response, save the ``country.id`` for use in later steps when
retrieving cities, regions, NANPA prefixes, and DID Groups.

For more information, see the :ref:`/v3/countries <countries_v34_get_countries>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Find a country by ISO code*

      Use this approach when your application already knows the target country
      (for example, from a stored customer selection or a predefined checkout flow).
      Filter by ISO code to retrieve the matching country and its ``country.id``.

      .. http:example:: curl

         GET /v3/countries?filter[iso]=US HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

      .. note::
         This example filters by country ISO code. Adjust filters as needed to match
         your use case.

   .. tab-item:: *List countries available for purchase*

      Use this approach when building a **country dropdown** for end users.
      This request returns countries that have DID Groups in coverage and DID numbers
      available for purchase. You can sort the results by name and use each item’s
      ``attributes.name`` for display and ``id`` as the selected ``country.id`` for
      later steps.

      ``filter[is_available]`` is a boolean filter:

      - When ``true``, returns countries with DID numbers available for purchase.
      - When ``false``, returns countries that exist in coverage but currently have no
        DID numbers available for purchase.

      .. http:example:: curl

         GET /v3/countries?filter[is_available]=true&sort=name HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                     "type": "countries",
                     "attributes": {
                         "name": "Canada",
                         "prefix": "1",
                         "iso": "CA"
                     }
                 },
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-random-dids_step2:

Step 2: Show Inventory Filters for the Selected Country
========================================================

After the user selects a country and your application saves the
``country.id``, the next step is to help the user narrow the available DID
inventory.

At this stage, your site should display the filters that are supported for the
selected country. The available filters depend on the numbering rules and
inventory structure for that country.

Available filtering options for this flow include:

- **DID Group Types** filters DID inventory by number category, such as Local, Mobile, National, or Toll-free.
- **Cities**  filters DID inventory by city within the selected country.
- **Regions** filters DID inventory by region within the **United States**, **Canada**, and the **United Kingdom**.
- **NANPA Prefixes (NPA/NXX)** filters **Local** DID inventory in the **United States** and **Canada** by area code and central office code.

.. note:: Use the filtering method that matches the selected country and your search experience.

Building the Filtering Experience Example
-----------------------------------------

Guide the user through the filtering flow:

1. The user selects a country from the country list.
2. Your application saves the selected ``country.id``.
3. Your site displays the inventory filters available for that country.
4. The user chooses a filter option and selects a value.
5. Your application saves the returned resource ID, such as ``city.id``, or ``nanpa_prefix.id``.
6. Use the saved ID in the next step to retrieve DID Inventory using ``GET /v3/did_groups``.

For example:

- If the user selects **United States** or **Canada**, your site can also
  allow the user to select a **region** and then choose **NPA/NXX** prefix.
- To display NPA/NXX options for the United States, the customer should first
  select a **state**. After that, your application can retrieve and display the
  list of available NANPA prefixes for that state.

.. note::

   Do not show all possible filters unconditionally. Instead, show or enable only the
   filters that are relevant to the selected country and to the search flow
   supported by your application.

Filtering Examples
------------------------------

.. tab-set::
   :class: my-tabs
   :sync-group: did-filter

   .. tab-item:: *Search by City*
      :sync: city

      Use this filter when your application allows the user to narrow DID availability by **city**.

      Before you can filter DID inventory by city in the next step, you must first retrieve the corresponding ``city.id`` using the ``/cities`` endpoint.

      To narrow the results, use the saved ``country.id`` together with the city name entered or selected by the user.

      For more information, see the :ref:`/v3/cities <cities_v34_get_cities>` endpoint documentation.

      .. http:example:: curl

         GET /v3/cities?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[name]=New%20York HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "368bf92f-c36e-473f-96fc-d53ed1b4028b",
                     "type": "cities",
                     "attributes": {
                         "name": "New York"
                     }
                 }
             ]
         }

   .. tab-item:: *Search by NANPA Prefix (NPA/NXX)*
      :sync: nanpa

      Use this filter when your application allows the user to narrow DID
      inventory by **NPA/NXX**.

      This filtering option is available only for **United States** and
      **Canada**, because these countries use the **North American Numbering
      Plan (NANP)**.

      Before you can filter DID inventory by NANPA prefix in the next step, you
      must first retrieve the corresponding ``nanpa_prefix.id``. To do this,
      first retrieve the selected **state** or **province** using the
      ``/regions`` endpoint, and save the returned ``region.id``.

      Then use the saved ``country.id`` together with ``region.id`` to retrieve
      available NANPA prefixes by using the ``/nanpa_prefixes`` endpoint.

      From the response, save the returned ``nanpa_prefix.id``. You will use this
      value in the next step to filter DID Groups by NANPA prefix.

      The flow is:

      1. Save the selected ``country.id``.
      2. Retrieve the selected state or province and save ``region.id``.
      3. Retrieve NANPA prefixes using ``country.id`` and ``region.id``.
      4. Save the selected ``nanpa_prefix.id`` for the next step.

      .. rubric:: 1. Retrieve the State or Province

      First, use the saved ``country.id`` to retrieve the state or province
      selected by the user.

      For more information, see the
      :ref:`/v3/regions <regions_v34_get_regions>` endpoint documentation.

      .. http:example:: curl

         GET /v3/regions?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[name]=New%20York HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "ab7e83bc-814b-4cfa-a14c-d2df3de2a545",
                     "type": "regions",
                     "attributes": {
                         "name": "New York",
                         "iso": "US-NY"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

      .. rubric:: 2. Retrieve NPA/NXX Values for the Selected Region

      Next, use the saved ``country.id`` and ``region.id`` to retrieve the
      available NANPA prefixes for that state or province.

      Your application can then display the returned ``npa`` and ``nxx``
      values in a dropdown or searchable list so the user can select the
      required code.

      Save the selected ``nanpa_prefix.id`` for use in the next step when
      retrieving DID Inventory using ``GET /did_groups``.

      For more information, see the
      :ref:`/v3/nanpa_prefixes <nanpa_v34_get_nanpa>` endpoint documentation.

      .. http:example:: curl

         GET /v3/nanpa_prefixes?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[region.id]=ab7e83bc-814b-4cfa-a14c-d2df3de2a545 HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "48b91ed5-13db-4920-a4cb-d0260d692053",
                     "type": "nanpa_prefixes",
                     "attributes": {
                         "npa": "212",
                         "nxx": "111"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-random-dids_step3:

Step 3: Retrieve DID Availability, Pricing, and Number Selection Availability
=============================================================================

Use the ``/did_groups`` endpoint to retrieve the DID number inventory groups
that match the selected inventory criteria.

This endpoint is the primary source for building DID number coverage and
availability in your application. It allows you to present users with:

- available DID number types, such as Local, Mobile, National, and Toll-free
- supported prefixes and geographic areas
- available features, such as voice and SMS
- pricing options and included channel configurations
- whether registration is required before activation

Include ``stock_keeping_units`` in the request to retrieve SKU pricing and
included channel configurations for each DID Group.

From the ``GET /did_groups`` response, save the ``stock_keeping_units.id``
that will be used to create the order in the next step.

For more information, see the :ref:`/v3/did_groups <did_groups_v34_get_did_groups>` endpoint documentation.

.. tab-set::
   :class: my-tabs
   :sync-group: did-filter

   .. tab-item:: *Filter by City*
      :sync: city

      Use this approach when the inventory was located using ``city.id`` in
      :ref:`Step 2 <user-panel-api-examples-random-dids_step2>`.

      Then apply ``filter[city.id]`` to retrieve DID Groups available in the selected city.

      .. http:example:: curl

         GET /v3/did_groups?include=stock_keeping_units&filter[city.id]=368bf92f-c36e-473f-96fc-d53ed1b4028b HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9",
               "type": "did_groups",
               "attributes": {
                 "prefix": "212",
                 "features": [
                   "voice_in"
                 ],
                 "is_metered": false,
                 "area_name": "New York",
                 "allow_additional_channels": true,
                 "service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/country",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/country"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/city",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/did_group_type",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/did_group_type"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/region",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/stock_keeping_units",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/stock_keeping_units"
                   },
                   "data": [
                     {
                       "type": "stock_keeping_units",
                       "id": "a7ecfee0-693e-459c-8eff-244121847ac2"
                     },
                     {
                       "type": "stock_keeping_units",
                       "id": "e2406add-fd8a-475c-b959-81e9619d7a4b"
                     }
                   ]
                 },
                 "address_requirement": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/address_requirement",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/address_requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": false,
                 "is_available": true,
                 "total_count": 620
               }
             }
           ],
           "included": [
             {
               "id": "a7ecfee0-693e-459c-8eff-244121847ac2",
               "type": "stock_keeping_units",
               "attributes": {
                 "channels_included_count": 0
               }
             },
             {
               "id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
               "type": "stock_keeping_units",
               "attributes": {
                 "channels_included_count": 2
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *Filter by NANPA Prefix*
      :sync: nanpa

      Use this approach when the inventory was located using
      ``nanpa_prefix.id`` in :ref:`Step 2 <user-panel-api-examples-random-dids_step2>`.

      Then apply ``filter[nanpa_prefix.id]`` to retrieve DID Groups that match the selected NANPA prefix.

      .. http:example:: curl

         GET /v3/did_groups?include=stock_keeping_units&filter%5Bnanpa_prefix.id%5D=48b91ed5-13db-4920-a4cb-d0260d692053 HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9",
               "type": "did_groups",
               "attributes": {
                 "prefix": "212",
                 "features": [
                   "voice_in"
                 ],
                 "is_metered": false,
                 "area_name": "New York",
                 "allow_additional_channels": true,
                 "service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/country",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/country"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/city",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/did_group_type",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/did_group_type"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/region",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/stock_keeping_units",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/stock_keeping_units"
                   },
                   "data": [
                     {
                       "type": "stock_keeping_units",
                       "id": "a7ecfee0-693e-459c-8eff-244121847ac2"
                     },
                     {
                       "type": "stock_keeping_units",
                       "id": "e2406add-fd8a-475c-b959-81e9619d7a4b"
                     }
                   ]
                 },
                 "address_requirement": {
                   "links": {
                     "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/address_requirement",
                     "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/address_requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": false,
                 "is_available": true,
                 "total_count": 620
               }
             }
           ],
           "included": [
             {
               "id": "a7ecfee0-693e-459c-8eff-244121847ac2",
               "type": "stock_keeping_units",
               "attributes": {
                 "channels_included_count": 0
               }
             },
             {
               "id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
               "type": "stock_keeping_units",
               "attributes": {
                 "channels_included_count": 2
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-random-dids_step4:

Step 4: Create the DID Order
============================

Create the order using the selected ``stock_keeping_units.id`` retrieved in the previous step.

This ensures the order is created for a **DID number** that matches the
selected inventory criteria from the previous steps.

For more information, see the :ref:`/v3/orders <orders_v34_create_order>` endpoint documentation.

.. note::

   - A positive prepaid balance is required to successfully create the order.
   - For simplicity, detailed item attributes are not included in this response example.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Buy Numbers from Inventory*

      In :ref:`Step 3 <user-panel-api-examples-random-dids_step3>`, the inventory was identified using the selected ``sku.id``.

      Use the selected ``sku.id`` to create an order for an available DID number from the matching inventory.

      In this example, we purchase a number with 2 included channels.

      For more information, see the :ref:`/v3/orders <orders_v34_create_order>` endpoint documentation.

      .. http:example:: curl

         POST /v3/orders HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "orders",
             "attributes": {
               "allow_back_ordering": true,
               "items": [
                 {
                   "type": "did_order_items",
                   "attributes": {
                     "sku_id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
                     "qty": 1
                   }
                 }
               ]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
            "data": {
                "id": "eb23b1a4-f4fd-4960-9f46-750ec920cde8",
                "type": "orders",
                "attributes": {
                    "amount": "8.0",
                    "status": "pending",
                    "created_at": "2026-03-18T11:41:20.443Z",
                    "description": "DID",
                    "reference": "RNQ-961086",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "4.0",
                                "mrc": "4.0",
                                "prorated_mrc": false,
                                "billed_from": null,
                                "billed_to": null,
                                "did_group_id": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
         }

   .. tab-item:: *Buy Numbers with Selected NANPA Prefix*

      In :ref:`Step 3 <user-panel-api-examples-random-dids_step3>`, the inventory
      was identified using the selected ``nanpa_prefix.id`` together with
      ``sku.id``.

      Use the selected ``nanpa_prefix.id`` together with ``sku.id`` to create an
      order for an available DID number that matches the selected NANPA prefix.

      In this example, we purchase a number with 2 included channels.

      For more information, see the :ref:`/v3/orders <orders_v34_create_order>`
      endpoint documentation.

      .. http:example:: curl

         POST /v3/orders HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "orders",
             "attributes": {
               "allow_back_ordering": false,
               "items": [
                 {
                   "type": "did_order_items",
                   "attributes": {
                     "nanpa_prefix_id": "48b91ed5-13db-4920-a4cb-d0260d692053",
                     "sku_id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
                     "qty": 1
                   }
                 }
               ]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
            "data": {
                "id": "372cc3c7-49a2-41ef-be64-85b7b297e4e3",
                "type": "orders",
                "attributes": {
                    "amount": "0.09",
                    "status": "pending",
                    "created_at": "2026-03-18T12:06:49.115Z",
                    "description": "DID",
                    "reference": "PJB-535885",
                    "items": [
                        {
                            "type": "did_order_items",
                            "attributes": {
                                "qty": 1,
                                "nrc": "0.0",
                                "mrc": "0.09",
                                "prorated_mrc": false,
                                "billed_from": null,
                                "billed_to": null,
                                "did_group_id": "7f3a4f3f-8aba-4447-9cb5-66a4e8e4f6ff"
                            }
                        }
                    ],
                    "callback_method": null,
                    "callback_url": null
                }
            },
            "meta": {
                "api_version": "2026-04-16"
            }
         }


.. |br| raw:: html

   <br />

.. _user-panel-api-examples-verification:
.. _api-examples-buy-a-did-that-requires-verification:

===========================================
Buy a DID Number That Requires Verification
===========================================

This example shows the **end-to-end process for purchasing a DID number**
that is subject to **regulatory verification requirements** and completing the
verification flow required to activate it.

Certain DID numbers require end-user registration based on country, number type,
or applicable regulatory rules. When registration applies, additional
information such as an identity, address, proofs, and supporting documents must
be collected, validated, and submitted before the DID can be activated.

The flow outlined below covers discovering available numbers and registration
requirements, collecting and validating end-user data, and initiating the
verification process needed for DID activation.

To purchase a DID and complete the required verification flow, follow these steps:

- :ref:`Step 1: Find the Country ID <user-panel-api-examples-verification-step1>`
- :ref:`Step 2: Find the City ID <user-panel-api-examples-verification-step2>`
- :ref:`Step 3: Retrieve DID Availability, Pricing, and Registration Requirements <user-panel-api-examples-verification-step3>`
- :ref:`Step 4: Create the DID Order <user-panel-api-examples-verification-step4>`
- :ref:`Step 5: Retrieve the DID ID Created by the DID Order <user-panel-api-examples-verification-step5>`
- :ref:`Step 6: Retrieve and Review Registration Requirements <user-panel-api-examples-verification-step6>`
- :ref:`Step 7: Create an Identity <user-panel-api-examples-verification-step7>`
- :ref:`Step 8: Create an Address <user-panel-api-examples-verification-step8>`
- :ref:`Step 9: Encrypt and Upload Documents <user-panel-api-examples-verification-step9>`
- :ref:`Step 10: Create Identity and Address Proofs <user-panel-api-examples-verification-step10>`
- :ref:`Step 11: Create a Permanent Supporting Document (If Required) <user-panel-api-examples-verification-step11>`
- :ref:`Step 12: Validate Identity and Address Against Requirements <user-panel-api-examples-verification-step12>`
- :ref:`Step 13: Assign End-User Details and Start DID Verification <user-panel-api-examples-verification-step13>`

.. note::
   The UUIDs shown in the examples below are for illustration purposes only.

   Always execute requests in your own environment and use the actual UUIDs
   returned in API responses.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step1:

Step 1: Find the Country ID
===========================

Retrieve the unique ID for the target country using the ``/countries`` endpoint.
From the response, save the ``country.id`` for use in later steps (for example,
when retrieving requirements or building address data).

For more information, see the :ref:`/v3/countries <countries_v34_get_countries>` endpoint documentation.

.. tab-set::

   .. tab-item:: *Find a country by ISO code*

      Use this approach when your application already knows the target country
      (for example, from a stored customer selection or a predefined checkout flow).
      Filter by ISO code to retrieve the matching country and its ``country.id``.

      .. http:example:: curl

         GET /v3/countries?filter[iso]=DE HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7",
                     "type": "countries",
                     "attributes": {
                         "name": "Germany",
                         "prefix": "49",
                         "iso": "DE"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

      .. note::
         This example filters by country ISO code. Adjust filters as needed to match
         your use case.

   .. tab-item:: *List countries available for purchase*

      Use this approach when building a **country dropdown** for end users.
      This request returns countries that have DID Groups in coverage and DID numbers
      available for purchase. You can sort the results by name and use each item’s
      ``attributes.name`` for display and ``id`` as the selected ``country.id`` for
      later steps.

      ``filter[is_available]`` is a boolean filter:

      - When ``true``, returns countries with DID numbers available for purchase.
      - When ``false``, returns countries that exist in coverage but currently have no
        DID numbers available for purchase.

      .. http:example:: curl

         GET /v3/countries?filter[is_available]=true&sort=name HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "7549be3c-1077-433d-9a77-25416373660d",
                     "type": "countries",
                     "attributes": {
                         "name": "Sweden",
                         "prefix": "46",
                         "iso": "SE"
                     }
                 },
                 {
                     "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                     "type": "countries",
                     "attributes": {
                         "name": "Canada",
                         "prefix": "1",
                         "iso": "CA"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step2:

Step 2: Find the City ID
========================

Depending on your application flow, selecting a city may be optional or required.
If your application allows users to narrow DID availability by **city** (for
example, when displaying a coverage list for local numbers), you should retrieve
and store the corresponding ``city.id``.

If your application does **not** differentiate availability by city (for example,
when listing all cities within a country or purchasing non–city-specific DIDs),
this step can be skipped.

Use the saved ``country.id`` to retrieve the city where the DID will be purchased.
From the response, save the ``city.id`` for use in later steps when retrieving
DID Groups or building address data.

For more information, see the :ref:`/v3/cities <cities_v34_get_cities>` endpoint documentation.

.. http:example:: curl

    GET /v3/cities?filter[country.id]=f711b8ee-7576-4d40-9dd4-f51a69cee8a7&filter[name]=Aachen HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "bc7df5b9-3852-401c-b21d-8c8871efd86f",
                "type": "cities",
                "attributes": {
                    "name": "Aachen"
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2026-04-16"
        }
    }

.. note::

   This example filters the response by a single city name. Adjust the request
   parameters as needed to match your use case.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-sku-and-requirements:
.. _user-panel-api-examples-verification-step3:

Step 3: Retrieve DID Availability, Pricing, and Registration Requirements
=========================================================================

This step uses the ``/did_groups`` endpoint, which is the **primary source for
building DID number coverage and availability** in your application.

It allows you to present end users with:

- available DID number types (Local, Mobile, National, Toll-free)
- supported prefixes and geographic areas
- available features (such as voice and SMS)
- pricing options and included channel options
- whether regulatory registration is required before activation

Include ``stock_keeping_units`` and ``address_requirement`` in the request to obtain
the following information:

- **Stock Keeping Units (SKU)** – Represents individual inventory units within
  the DID Group. Each SKU defines the price of the DID and the number of included
  channels.
- **Registration requirement** – Indicates whether end-user registration is
  required for DIDs in this area. Optionally, the restriction message can be
  displayed to the user before purchase to inform them that additional details
  will be required to activate the number.

From the ``GET /did_groups`` response, save the following values:

- ``stock_keeping_units.id`` – Required to create the DID order in the next step.
- ``address_requirement.id`` – Optional at this step. It can be used in later steps to validate identity and address information once the DID country and type are known and registration requirements apply (see :ref:`user-panel-api-examples-verification-step12`).

For more information, see the :ref:`/v3/did_groups <did_groups_v34_get_did_groups>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Filter by City*

      Use this approach when your flow narrows down availability by location
      (for example, after the user selects a country and a city/area). The response
      can be used to list purchasable DID Groups for that location and to determine
      whether registration is required before ordering.

      .. http:example:: curl

          GET /v3/did_groups?include=stock_keeping_units,address_requirement&filter[city.id]=bc7df5b9-3852-401c-b21d-8c8871efd86f HTTP/1.1
          Host: api.didww.com
          Api-Key: [API token]
          Accept: application/vnd.api+json

          HTTP/1.1 200 OK
          Content-Type: application/vnd.api+json

          {
              "data": [
                  {
                      "id": "16f7a8ea-cbfd-4429-8b94-995421d73814",
                      "type": "did_groups",
                      "attributes": {
                          "prefix": "3",
                          "features": [
                                "voice_in",
                                "voice_out"
                          ],
                          "is_metered": false,
                          "area_name": "Aachen",
                          "allow_additional_channels": true
                      },
                      "relationships": {
                          "stock_keeping_units": {
                              "data": [
                                  {
                                      "type": "stock_keeping_units",
                                      "id": "9438cb3c-8e82-4d48-8b66-ec995dc13132"
                                  },
                                  {
                                      "type": "stock_keeping_units",
                                      "id": "fedaec98-af1e-4441-bd7e-1c6668312ad5"
                                  }
                              ]
                          },
                          "address_requirement": {
                              "data": {
                                  "type": "address_requirements",
                                  "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7"
                              }
                          }
                      },
                      "meta": {
                          "needs_registration": true,
                          "is_available": true,
                          "total_count": 98
                      }
                  }
              ],
              "included": [
                  {
                      "id": "9438cb3c-8e82-4d48-8b66-ec995dc13132",
                      "type": "stock_keeping_units",
                      "attributes": {
                          "setup_price": "5.0",
                          "monthly_price": "0.4",
                          "channels_included_count": 0
                      }
                  },
                  {
                      "id": "fedaec98-af1e-4441-bd7e-1c6668312ad5",
                      "type": "stock_keeping_units",
                      "attributes": {
                          "setup_price": "5.0",
                          "monthly_price": "2.1",
                          "channels_included_count": 2
                      }
                  },
                  {
                      "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7",
                      "type": "address_requirements",
                      "attributes": {
                          "identity_type": "any",
                          "personal_area_level": "world_wide",
                          "business_area_level": "world_wide",
                          "address_area_level": "area",
                          "personal_proof_qty": 1,
                          "business_proof_qty": 1,
                          "address_proof_qty": 0,
                          "personal_mandatory_fields": ["id_number"],
                          "business_mandatory_fields": ["vat_id"],
                          "service_description_required": false,
                          "restriction_message": "Germany Local DID End User registration requirements:\n\nFor personal identity verification:\n* Name, last name\n* Contact phone number\n* German passport or ID copy\n\nFor business identity verification:\n* Name, last name\n* Contact phone number\n* Company name\n* German company incorporation certificate copy\n\nFor address verification:\n* Address matching the DID area code\n* Utility bill (less than 6 months old)\n"
                      }
                  }
              ]
          }

   .. tab-item:: *Display Country Coverage*

      Use this approach when your UI begins with a **country selection** and presents
      available DID options, such as on a **Buy Numbers** page with filters by DID
      Group type and features.

      By including country, region, DID Group type, SKUs, and requirement-related
      resources, your application can show registration conditions before purchase when applicable.

      .. http:example:: curl

           GET /v3/did_groups?filter[country.id]=dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e&sort=area_name&include=country,region,stock_keeping_units,did_group_type,address_requirement,address_requirement.personal_onetime_document,address_requirement.business_onetime_document,address_requirement.personal_permanent_document,address_requirement.business_permanent_document HTTP/1.1
           Host: api.didww.com
           Api-Key: [API token]
           Accept: application/vnd.api+json

           HTTP/1.1 200 OK
           Content-Type: application/vnd.api+json

           {
               "data": [
                   {
                       "id": "2187c36d-28fb-436f-8861-5a0f5b5a3ee1",
                       "type": "did_groups",
                       "attributes": {
                           "prefix": "241",
                           "features": [
                               "voice_in",
                               "t38"
                           ],
                           "is_metered": false,
                           "area_name": "Aachen",
                           "allow_additional_channels": true
                       },
                       "relationships": {
                           "country": {
                               "data": {
                                   "type": "countries",
                                   "id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e"
                               }
                           },
                           "did_group_type": {
                               "data": {
                                   "type": "did_group_types",
                                   "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                               }
                           },
                           "region": {
                               "data": null
                           },
                           "stock_keeping_units": {
                               "data": [
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "b98e368b-20d4-45e1-a7c3-319351b084fd"
                                   },
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "63bab5b4-c65f-4412-bca1-5085f5318317"
                                   }
                               ]
                           },
                           "address_requirement": {
                               "data": {
                                   "type": "address_requirements",
                                   "id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6"
                               }
                           }
                       },
                       "meta": {
                           "available_dids_enabled": false,
                           "needs_registration": true,
                           "is_available": true,
                           "total_count": 8
                       }
                   },
                   {
                       "id": "0b8e8c19-f3a8-4d90-a18f-657393703379",
                       "type": "did_groups",
                       "attributes": {
                           "prefix": "821",
                           "features": [
                               "voice_in",
                               "t38"
                           ],
                           "is_metered": false,
                           "area_name": "Augsburg",
                           "allow_additional_channels": true
                       },
                       "relationships": {
                           "country": {
                               "data": {
                                   "type": "countries",
                                   "id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e"
                               }
                           },
                           "did_group_type": {
                               "data": {
                                   "type": "did_group_types",
                                   "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                               }
                           },
                           "region": {
                               "data": null
                           },
                           "stock_keeping_units": {
                               "data": [
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "1a9c4d79-1306-455d-99c1-c5fd48abeae2"
                                   },
                                   {
                                       "type": "stock_keeping_units",
                                       "id": "b31df3bb-bd5d-4315-b7c0-08a4f865c029"
                                   }
                               ]
                           },
                           "address_requirement": {
                               "data": {
                                   "type": "address_requirements",
                                   "id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6"
                               }
                           }
                       },
                       "meta": {
                           "available_dids_enabled": false,
                           "needs_registration": false,
                           "is_available": true,
                           "total_count": 11
                       }
                   }
               ],
               "included": [
                   {
                       "id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e",
                       "type": "countries",
                       "attributes": {
                           "name": "Germany",
                           "prefix": "49",
                           "iso": "DE"
                       }
                   },
                   {
                       "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
                       "type": "did_group_types",
                       "attributes": {
                           "name": "Local"
                       }
                   },
                   {
                       "id": "2c165e9d-c6f5-4fe1-ad0e-bacf5bab3d86",
                       "type": "did_group_types",
                       "attributes": {
                           "name": "National"
                       }
                   },
                   {
                       "id": "b98e368b-20d4-45e1-a7c3-319351b084fd",
                       "type": "stock_keeping_units",
                       "attributes": {
                           "setup_price": "0.0",
                           "monthly_price": "0.8",
                           "channels_included_count": 0
                       }
                   },
                   {
                       "id": "63bab5b4-c65f-4412-bca1-5085f5318317",
                       "type": "stock_keeping_units",
                       "attributes": {
                           "setup_price": "0.0",
                           "monthly_price": "4.8",
                           "channels_included_count": 2
                       }
                   },
                   {
                       "id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6",
                       "type": "address_requirements",
                       "attributes": {
                           "identity_type": "any",
                           "personal_area_level": "country",
                           "business_area_level": "country",
                           "address_area_level": "city",
                           "personal_proof_qty": 2,
                           "business_proof_qty": 1,
                           "address_proof_qty": 1,
                           "personal_mandatory_fields": [
                               "country"
                           ],
                           "business_mandatory_fields": [
                               "country"
                           ],
                           "service_description_required": true,
                           "restriction_message": "German Local DID End User registration requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* German passport or ID copy\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n\r\nFor address verification:\r\n* Address matching: the DID area code, address in the certificate/ID (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\n ."
                       }
                   },
                   {
                       "id": "94be4d74-c968-4d81-91c5-2d11b4e45328",
                       "type": "supporting_document_templates",
                       "attributes": {
                           "name": "LOI Example",
                           "permanent": false,
                           "url": "https://api.didww.com/storage/public/xptvgb8derrz0ru95wr9oi68g9tg?response-content-disposition=attachment%3B+filename%3D%22LOI+Example.pdf%22"
                       }
                   },
                   {
                       "id": "206ccec2-1166-461f-9f58-3a56823db548",
                       "type": "supporting_document_templates",
                       "attributes": {
                           "name": "Generic LOI",
                           "permanent": false,
                           "url": "https://api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn?response-content-disposition=attachment%3B+filename%3D%22Generic+LOI.pdf%22"
                       }
                   }
               ],
               "meta": {
                   "total_records": 38,
                   "api_version": "2026-04-16"
               }
           }

.. important::

     - If ``needs_registration`` is ``true``, the DID remains inactive until end-user details
       are assigned and the verification process is created, completed, and approved.
     - If ``needs_registration`` is ``false``, no registration requirements apply
       (``address_requirement.data`` is ``null``), and the DID can be activated without registration.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step4:

Step 4: Create the DID Order
============================

Create the DID order using the selected ``stock_keeping_units.id``.
From the order response, save the ``order.id``, which is required in the next step to retrieve the DID created by the order.

For more information, see the :ref:`/v3/orders <orders_v34_create_order>` endpoint documentation.

.. note::

   - A positive prepaid balance is required to successfully create a DID order.
   - For simplicity, detailed item attributes are not included in this response example.

.. http:example:: curl

    POST /v3/orders HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "orders",
        "attributes": {
          "allow_back_ordering": true,
          "items": [
            {
              "type": "did_order_items",
              "attributes": {
                "sku_id": "fedaec98-af1e-4441-bd7e-1c6668312ad5",
                "qty": 1
              }
            }
          ]
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "38ba6528-7460-410c-8fcc-262afb005ab3",
            "type": "orders",
            "attributes": {
                "amount": "2.1",
                "status": "pending",
                "created_at": "2026-01-08T09:10:20.270Z",
                "description": "DID",
                "reference": "YOY-267643"
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step5:

Step 5: Retrieve the DID ID Created by the DID Order
====================================================

.. note::

   You may retrieve the DID ID immediately after the order is created, as shown
   in this step, or retrieve it later depending on your application flow and
   user interface design.

   Retrieving the DID ID at this stage is optional. The DID ID is not required to
   retrieve registration requirements or to create identity and address resources.
   However, it is required later when assigning end-user details and starting DID
   verification (see :ref:`user-panel-api-examples-verification-step13`).

Retrieve the DID resource created by the order using the saved ``order.id``.
From the response, save the ``did.id`` for future reference.

For more information, see the :ref:`/v3/dids <dids_v34>` resource documentation.

.. http:example:: curl

    GET /v3/dids?filter[order.id]=38ba6528-7460-410c-8fcc-262afb005ab3 HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "ad74ee84-aac8-4006-8c91-c08c59a32200",
                "type": "dids",
                "attributes": {
                    "blocked": true,
                    "capacity_limit": null,
                    "description": null,
                    "terminated": false,
                    "awaiting_registration": true,
                    "created_at": "2026-01-16T07:38:42.000Z",
                    "billing_cycles_count": null,
                    "number": "4924111111112",
                    "expires_at": "2026-02-16T07:38:42.508Z",
                    "channels_included_count": 2,
                    "dedicated_channels_count": 0
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2026-04-16"
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step6:

Step 6: Retrieve and Review Registration Requirements
=====================================================

Depending on your application flow, registration requirements may already be
known. For example, they may be displayed together with a DID Group while
displaying number availability or coverage information, or they may be retrieved
dynamically based on user selections such as country and DID Group type. If the
requirement is already known, use the saved ``address_requirement.id`` from Step 3
(:ref:`Get the SKU ID and Registration Requirement
<user-panel-api-examples-sku-and-requirements>`) to retrieve the full registration
requirement details.

In all cases, the retrieved requirement defines the identity, address, proofs,
and supporting documents that must be created in the next steps and serves as
the authoritative source for validation and verification.

The registration requirement specifies:

- which identity types (Personal or Business) are allowed
- which identity fields are mandatory
- how many identity and address proofs must be provided
- which proof types are accepted
- whether address proofs are required
- whether permanent and/or one-time supporting documents are required
- whether a service description must be provided
- any country, area, or city restrictions that apply

Before continuing to the next steps, review the **accepted proof types** defined
in the registration requirement. These proof types determine which document
categories the end user is allowed to submit for identity or address verification.

Your application should use this information to display valid document options
to the user (for example, Passport or Utility Bill) and to ensure that each
uploaded and encrypted document is linked to an accepted proof type when
creating proofs in :ref:`Step 10 <user-panel-api-examples-verification-step10>`.

Accepted proof types are provided in the requirement response under the following
relationships:

- **Business identity proofs** ``relationships.business_proof_types.data[].id``
- **Personal identity proofs** ``relationships.personal_proof_types.data[].id``
- **Address proofs** (if required) ``relationships.address_proof_types.data[].id``

Each proof created later must reference one of these accepted proof types,
together with an encrypted document and the corresponding identity or address.

For more information, see the :ref:`Address Requirements <address_requirements_v34>` resource documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Retrieve by Requirement ID*

      Use this approach when you already have the ``address_requirement.id`` (for example,
      it was returned in Step 3 together with the selected SKU/DID Group). This
      request returns the full requirement details, including accepted proof types
      and supporting document templates.

      .. http:example:: curl

            GET /v3/address_requirements?filter[id]=c6f606d8-106a-43d6-997e-17c7da5ae5d7&include=personal_proof_types,business_proof_types,address_proof_types,personal_permanent_document,business_permanent_document,personal_onetime_document,business_onetime_document HTTP/1.1
            Host: api.didww.com
            Api-Key: [API token]
            Accept: application/vnd.api+json

            HTTP/1.1 200 OK
            Content-Type: application/vnd.api+json

            {
                "data": [
                    {
                        "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7",
                        "type": "address_requirements",
                        "attributes": {
                            "identity_type": "any",
                            "personal_area_level": "world_wide",
                            "business_area_level": "world_wide",
                            "address_area_level": "area",
                            "personal_proof_qty": 1,
                            "business_proof_qty": 1,
                            "address_proof_qty": 0,
                            "personal_mandatory_fields": ["id_number"],
                            "business_mandatory_fields": ["vat_id"],
                            "service_description_required": false,
                            "restriction_message": "German Local DID End User registration requirements: ..."
                        },
                        "relationships": {
                            "personal_permanent_document": {
                                "data": {
                                    "type": "supporting_document_templates",
                                    "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                                }
                            },
                            "business_permanent_document": {
                                "data": {
                                    "type": "supporting_document_templates",
                                    "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                                }
                            },
                            "personal_onetime_document": {
                                "data": null
                            },
                            "business_onetime_document": {
                                "data": null
                            },
                            "personal_proof_types": {
                                "data": [
                                    {
                                        "type": "proof_types",
                                        "id": "108b1fcf-686e-4017-a6c7-cf38c175f76a"
                                    }
                                ]
                            },
                            "business_proof_types": {
                                "data": [
                                    {
                                        "type": "proof_types",
                                        "id": "80253913-cd8b-4ce2-91a9-9299587ac409"
                                    }
                                ]
                            },
                            "address_proof_types": {
                                "data": []
                            }
                        }
                    }
                ],
                "included": [
                    {
                        "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
                        "type": "supporting_document_templates",
                        "attributes": {
                            "name": "Belgium Registration Form",
                            "permanent": true,
                            "url": "https://api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra?response-content-disposition=attachment%3B+filename%3D%22Belgium+Registration+Form.pdf%22"
                        }
                    },
                    {
                        "id": "108b1fcf-686e-4017-a6c7-cf38c175f76a",
                        "type": "proof_types",
                        "attributes": {
                            "name": "Passport",
                            "entity_type": "personal"
                        }
                    },
                    {
                        "id": "80253913-cd8b-4ce2-91a9-9299587ac409",
                        "type": "proof_types",
                        "attributes": {
                            "name": "Passport",
                            "entity_type": "business"
                        }
                    }
                ]
            }

   .. tab-item:: *Retrieve by Country and DID Group Type*

      Use this approach when the registration ``address_requirement.id`` is not known in advance and
      your application allows the user to check requirements based on their selection.
      After the user selects a **country** and a **DID Group type**, retrieve the
      matching requirements (including ``country`` and ``did_group_type``) and display:

        - the ``restriction_message``
        - any available supporting document template download links (when present)

      .. http:example:: curl

          GET /v3/address_requirements?include=country,did_group_type,personal_permanent_document,business_permanent_document HTTP/1.1
          Host: api.didww.com
          Api-Key: [API token]
          Accept: application/vnd.api+json

          HTTP/1.1 200 OK
          Content-Type: application/vnd.api+json

          {
            "data": [
              {
                "id": "6f71cc7b-8c13-4958-8623-60f750b8bcca",
                "type": "address_requirements",
                "attributes": {
                  "identity_type": "any",
                  "personal_area_level": "world_wide",
                  "business_area_level": "world_wide",
                  "address_area_level": "area",
                  "personal_proof_qty": 1,
                  "business_proof_qty": 0,
                  "address_proof_qty": 0,
                  "personal_mandatory_fields": null,
                  "business_mandatory_fields": null,
                  "service_description_required": false,
                  "restriction_message": "French Local DID End User registration requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n\r\nFor address verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.\r\n\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process."
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/country",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "7d9f8011-40a4-4fd7-a970-c3b679a75daf"
                    }
                  },
                  "did_group_type": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/did_group_type",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/did_group_type"
                    },
                    "data": {
                      "type": "did_group_types",
                      "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                    }
                  },
                  "personal_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_permanent_document",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_permanent_document"
                    },
                    "data": {
                      "type": "supporting_document_templates",
                      "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                    }
                  },
                  "business_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_permanent_document",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_permanent_document"
                    },
                    "data": null
                  },
                  "personal_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_onetime_document",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_onetime_document"
                    }
                  },
                  "business_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_onetime_document",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_onetime_document"
                    }
                  },
                  "personal_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_proof_types",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_proof_types"
                    },
                    "data": [
                      {
                        "type": "proof_types",
                        "id": "19cd7b22-559b-41d4-99c9-7ad7ad63d5d1"
                      }
                    ]
                  },
                  "business_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_proof_types",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_proof_types"
                    }
                  },
                  "address_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/address_proof_types",
                      "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/address_proof_types"
                    }
                  }
                }
              },
              {
                "id": "273d3bec-9a13-45b0-8fb4-c06bf46c1b34",
                "type": "address_requirements",
                "attributes": {
                  "identity_type": "any",
                  "personal_area_level": "world_wide",
                  "business_area_level": "world_wide",
                  "address_area_level": "world_wide",
                  "personal_proof_qty": 0,
                  "business_proof_qty": 0,
                  "address_proof_qty": 2,
                  "personal_mandatory_fields": null,
                  "business_mandatory_fields": null,
                  "service_description_required": true,
                  "restriction_message": "Japanese Local DID End User registration requirements:\r\n\r\n* For personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* Company incorporation certificate copy\r\n\r\nFor address verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.\r\n\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process."
                },
                "relationships": {
                  "country": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/country",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/country"
                    },
                    "data": {
                      "type": "countries",
                      "id": "eb89ebf7-2c8c-4e7d-9aea-89cddeced3c8"
                    }
                  },
                  "did_group_type": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/did_group_type",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/did_group_type"
                    },
                    "data": {
                      "type": "did_group_types",
                      "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                    }
                  },
                  "personal_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_permanent_document",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_permanent_document"
                    },
                    "data": null
                  },
                  "business_permanent_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_permanent_document",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_permanent_document"
                    },
                    "data": null
                  },
                  "personal_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_onetime_document",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_onetime_document"
                    }
                  },
                  "business_onetime_document": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_onetime_document",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_onetime_document"
                    }
                  },
                  "personal_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_proof_types",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_proof_types"
                    },
                    "data": []
                  },
                  "business_proof_types": {
                    "links": {
                      "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_proof_types",
                      "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_proof_types"
                    }
                  },
                }
              }
            ],
            "included": [
              {
                "id": "7549be3c-1077-433d-9a77-25416373660d",
                "type": "countries",
                "attributes": {
                  "name": "Sweden",
                  "prefix": "46",
                  "iso": "SE"
                },
              },
              {
                "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                "type": "countries",
                "attributes": {
                  "name": "Canada",
                  "prefix": "1",
                  "iso": "CA"
                },
              },
              {
                "id": "fccd5be9-41dc-4daf-8894-234ecc916731",
                "type": "countries",
                "attributes": {
                  "name": "China",
                  "prefix": "86",
                  "iso": "CN"
                },
              },
              {
                "id": "6bba60f1-e724-4d12-9ea4-a3a64705800f",
                "type": "did_group_types",
                "attributes": { "name": "Mobile" }
              },
              {
                "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
                "type": "did_group_types",
                "attributes": { "name": "Local" }
              },
              {
                "id": "2c165e9d-c6f5-4fe1-ad0e-bacf5bab3d86",
                "type": "did_group_types",
                "attributes": { "name": "National" }
              },
              {
                "id": "d6530a8c-924c-469a-98c0-9525602e6192",
                "type": "did_group_types",
                "attributes": { "name": "Global" }
              },
              {
                "id": "ec95e831-fc36-489a-a531-0fd1984ab6e8",
                "type": "did_group_types",
                "attributes": { "name": "Toll-free" }
              },
              {
                "id": "eb810289-8620-44e1-982d-13e6cee70404",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Document Template 1",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/owwqi77007ks4qx198b7su3eukg6?response-content-disposition=attachment%3B+filename%3D%22TestPermanDoc.png%22"
                }
              },
              {
                "id": "f65149c1-b551-4444-97d7-22939445c42a",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Document Template 2",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/txm3ftmuhyhypm6553b2874iuljg?response-content-disposition=attachment%3B+filename%3D%22TestDoc4.pdf%22"
                }
              },
              {
                "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Belgium Registration Form",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra?response-content-disposition=attachment%3B+filename%3D%22Belgium+Registration+Form.pdf%22"
                }
              },
              {
                "id": "4199435f-646e-4e9d-a143-8f3b972b10c5",
                "type": "supporting_document_templates",
                "attributes": {
                  "name": "Germany Special Registration Form",
                  "permanent": true,
                  "url": "https://api.didww.com/storage/public/4rghqnqtba0fa7mbdgig086xej1e?response-content-disposition=attachment%3B+filename%3D%22Germany+Special+Registration+Form.pdf%22"
                }
              }
            ],
            "meta": {
              "total_records": 52,
              "api_version": "2026-04-16"
            }
          }

      .. tip::
          In the UI, filter the returned requirements by the selected
          ``country.id`` and ``did_group_type.id``. Once a match is found, display
          its ``restriction_message`` and provide download links for any included
          supporting document templates.

Registration requirement field reference
----------------------------------------

Use the requirement attributes and relationships to decide what to create in the
next steps.

.. list-table::
   :widths: 13 15 45
   :header-rows: 1

   * - Category
     - API fields
     - How to interpret and apply them

   * - **Identity type**
     - ``identity_type``
     - Defines which identity types are allowed:

       - ``any``: personal and business identities are allowed.
       - ``personal``: only a personal identity is allowed.
       - ``business``: only a business identity is allowed.

       The identity you create **must match** this value.

   * - **Identity restrictions**
     - ``personal_area_level``, |br| ``business_area_level``
     - Defines geographic restrictions for the identity:

       - ``world_wide``: the identity can belong to any country.
       - ``country``: the identity country must match the DID country.

       When ``country`` is required, set the identity country using the
       ``relationships.country`` relationship when creating the identity.

   * - **Address restrictions**
     - ``address_area_level``
     - Defines where the address must be located:

       - ``world_wide``: any country is allowed.
       - ``country``: address must match the DID country.
       - ``area`` or ``city``: address must match the DID area or city.

       Address relationships and attributes (such as ``country``,
       ``city_name``) must comply with these restrictions.

   * - **Mandatory identity fields**
     - ``personal_mandatory_fields``, |br| ``business_mandatory_fields``
     - Lists identity fields that must be provided when creating the identity.

   * - **Proof quantity requirements**
     - ``personal_proof_qty``, |br| ``business_proof_qty``, |br|
       ``address_proof_qty``
     - Specifies how many proofs must be submitted:

       - ``business_proof_qty = 1`` means exactly one business proof is required.
       - ``address_proof_qty = 0`` means no address proof is required.

   * - **Accepted proof types**
     - ``relationships.personal_proof_types``, |br|
       ``relationships.business_proof_types``, |br|
       ``relationships.address_proof_types``
     - Defines which proof types are accepted for each entity.

       Save the corresponding ``proof_type.id`` for use when creating proofs.

   * - **Supporting documents**
     - ``personal_permanent_document``, |br|
       ``business_permanent_document``, |br|
       ``personal_onetime_document``, |br|
       ``business_onetime_document``
     - Defines whether permanent or one-time supporting documents are required.

       - Permanent documents can be reused for future verifications.
       - One-time documents must be submitted with the verification task.

   * - **Service description**
     - ``service_description_required``
     - Indicates whether a service description must be provided during
       verification.

   * - **Restriction message**
     - ``restriction_message``
     - Provides a human-readable summary of regulatory requirements for the DID
       area.

   * - **Supporting document templates**
     - ``included[].type = supporting_document_templates``
     - Defines required supporting documents when
       ``personal_permanent_document`` or ``business_permanent_document`` is present.

       Each template includes:

       - ``name`` – the document name displayed to the end user
       - ``permanent`` – whether the document can be reused for future verifications
       - ``url`` – a downloadable template that must be completed, encrypted,
         and uploaded

       Example: ``Belgium Registration Form`` is a permanent document.

   * - **Proof type definitions**
     - ``included[].type = proof_types``
     - Describes the proof types accepted for identity or address verification.

       Each proof type includes:

       - ``name`` – the document type (e.g. Passport)
       - ``entity_type`` – whether it applies to ``personal`` or ``business`` identities

       Use these entries together with the corresponding
       ``relationships.proof_types`` to select the correct proof when creating
       identity or address proofs.

.. note::
   Registration requirements vary by DID Group, country, and identity type.
   Retrieve and follow the requirement linked to your DID Group.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step7:

Step 7: Create an Identity
==========================

Collect the required information from the end user purchasing the DID. This
includes selecting the identity type (**personal** or **business**) and
providing all mandatory fields defined by the applicable regulatory
requirements, such as name, contact details, and country information.

Create an identity that will later be assigned to the DID when creating the
verification task in
:ref:`Step 13 <user-panel-api-examples-verification-step13>`. From the response,
save the ``identity.id``, which is required to create an address for the identity
in the next step.

Ensure the identity complies with the regulatory requirements retrieved in
:ref:`Step 6 <user-panel-api-examples-verification-step6>`, including the
allowed identity type (personal or business), mandatory fields, applicable
country restrictions, and the number and type of proofs required for the DID
number.

For more information, see the :ref:`Identity <identities_v34>` resource documentation.

.. note::
   - Identity attributes depend on the registration requirement and the selected identity type. Always include any fields listed under ``personal_mandatory_fields`` or ``business_mandatory_fields`` from :ref:`Step 6 <user-panel-api-examples-verification-step6>`.
   - If the requirement restricts the identity to a specific country (``personal_area_level = Country`` or ``business_area_level = Country``), set the identity country using the ``relationships.country`` relationship.
   - For business identities, ``first_name`` and ``last_name`` typically represent the authorized contact person.
   - Identities may be reused for multiple DID verifications, provided they continue to meet the applicable requirements.

.. http:example:: curl

    POST /v3/identities HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
        "data": {
            "type": "identities",
            "attributes": {
                "identity_type": "business",
                "company_name": "Example Company Ltd",
                "first_name": "John",
                "last_name": "Smith",
                "phone_number": "3233461122",
                "vat_id": "BE0123456789"
            },
            "relationships": {
                "country": {
                    "data": {
                        "type": "countries",
                        "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
                    }
                }
            }
        }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
            "type": "identities",
            "attributes": {
                "first_name": "John",
                "last_name": "Smith",
                "phone_number": "3233461122",
                "company_name": "Example Company Ltd",
                "vat_id": "BE0123456789",
                "identity_type": "business",
                "verified": false
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

.. tip::
   Before continuing, you can validate whether the created **identity** meets the
   regulatory requirements by validating it against the ``address_requirement.id``
   (see :ref:`Step 12 <user-panel-api-examples-verification-step12>`).

   This allows you to detect issues (such as an invalid identity type or missing
   mandatory fields) early, before assigning the identity to the DID. If the
   identity complies with the requirement, the validation request succeeds
   without errors.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step8:

Step 8: Create an Address
=========================

Collect the required address information from the end user purchasing the DID.
This typically includes street address, city, postal code, and country, based on
the applicable regulatory requirements.

Create an address that will later be assigned to the DID in
:ref:`Step 13 <user-panel-api-examples-verification-step13>`, and link it to the
identity created in
:ref:`Step 7 <user-panel-api-examples-verification-step7>`.

Ensure it complies with the regulatory requirements retrieved in
:ref:`Step 6 <user-panel-api-examples-verification-step6>`, including the
acceptable geographic scope (for example, ``address_area_level = country``) and
any other applicable requirements.

From the response, save the ``address.id``. This value is required only if the
registration requirement specifies an address proof (``address_proof_qty > 0``).
Address proofs are linked to the address (not the identity), and the proof type must be one of the accepted proof types listed under
``relationships.address_proof_types`` in the requirement response (:ref:`Step 6 <user-panel-api-examples-verification-step6>`).

For more information, see the :ref:`Addresses <addresses_v34>` resource documentation.

.. http:example:: curl

    POST /v3/addresses HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "addresses",
        "attributes": {
          "address": "10 Example Street",
          "city_name": "Antwerp",
          "postal_code": "2000",
          "description": "Business registration address"
        },
        "relationships": {
          "identity": {
            "data": {
              "type": "identities",
              "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
            }
          },
          "country": {
            "data": {
              "type": "countries",
              "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
            }
          }
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "04072428-07e4-4026-9d11-b49a770a95a8",
            "type": "addresses",
            "attributes": {
                "address": "10 Example Street",
                "city_name": "Antwerp",
                "postal_code": "2000",
                "description": "Business registration address",
                "verified": false,
                "created_at": "2026-01-09T09:22:23.066Z"
            },
            "relationships": {
                "identity": {
                    "data": {
                        "type": "identities",
                        "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                    }
                },
                "country": {
                    "data": {
                        "type": "countries",
                        "id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
                    }
                }
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

.. tip::
   Before continuing, you can validate the **address** or both the **identity**
   and **address** together against the ``address_requirement.id`` to ensure they meet
   the regulatory requirements (see
   :ref:`Step 12 <user-panel-api-examples-verification-step12>`).

   This helps detect issues early—such as an invalid identity type or missing
   mandatory fields—before assigning the identity or address to the DID. If the
   submitted data complies with the requirement, the validation request
   completes successfully without errors.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step9:

Step 9: Encrypt and Upload Documents
====================================

After reviewing the registration requirements in
:ref:`Step 6 <user-panel-api-examples-verification-step6>` and collecting the
required identity and address information, your application may need to request
supporting documents from the end user.

Depending on the requirement, this can include identity proofs (for example,
a passport or national ID) and/or address proofs (such as a utility bill).
These documents are provided by the user based on the accepted proof types and
supporting document rules defined in the registration requirement.

If a registration requirement specifies identity proofs or supporting documents,
those documents must be encrypted before upload. All documents submitted to the
DIDWW API require encryption to ensure secure handling.

Document encryption protects sensitive personal and business information during
transmission and storage. It ensures that identity and address documents remain
confidential.

Encryption always produces a file with the ``.enc`` suffix. Only encrypted files
are accepted by the ``/v3/encrypted_files`` endpoint.

Encrypt the document
--------------------

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Browser-based encryption*

      Encrypt the document in the browser using the DIDWW encryption
      library. This approach is commonly used in web applications.

      Encryption library:
          - `@didww/encrypt <https://github.com/didww/didww-encrypt>`_

      Encryption steps:
          1. Select the original document (for example, ``passport.pdf``).
          2. Encrypt the file using the library.
          3. Save the encrypted output with the ``.enc`` suffix
             (for example, ``passport.pdf.enc``).

      The result of this process is a ready-to-use encrypted file that can be uploaded to the API in the next step.

   .. tab-item:: *Server-side encryption*

      Encrypt the document on the server using one of the supported SDKs.
      This approach is commonly used in backend services.

      .. grid:: 1 1 1 3
           :gutter: 4
           :padding: 0

           .. grid-item-card:: :iconify:`devicon:ruby` **Ruby Gem**
              :link: https://github.com/didww/didww-v3-ruby/blob/master/lib/didww/encrypt.rb
              :link-type: url
              :text-align: left

              Use the APIv3 Ruby gem to perform file encryption on the server side.

           .. grid-item-card:: :iconify:`material-icon-theme:php` **PHP SDK**
              :link: https://github.com/didww/didww-api-3-php-sdk/blob/master/src/Encrypt.php
              :link-type: url
              :text-align: left

              Use the official PHP SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`devicon:java` **Java SDK**
              :link: https://github.com/didww/didww-api-3-java-sdk/blob/main/src/main/java/com/didww/sdk/Encrypt.java
              :link-type: url
              :text-align: left

              Use the official Java SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`devicon:python` **Python SDK**
              :link: https://github.com/didww/didww-api-3-python-sdk/blob/main/src/didww/encrypt.py
              :link-type: url
              :text-align: left

              Use the official Python SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`skill-icons:typescript` **TypeScript SDK**
              :link: https://github.com/didww/didww-api-3-typescript-sdk/blob/main/src/encrypt.ts
              :link-type: url
              :text-align: left

              Use the official TypeScript SDK to implement server-side encryption.

           .. grid-item-card:: :iconify:`logos:go` **Go Encryption Sample**
              :link: https://github.com/didww/go-encrypt-sample
              :link-type: url
              :text-align: left

               Use the Go sample project to implement server-side file encryption compatible with DIDWW API v3.

           .. grid-item-card:: :iconify:`devicon:dot-net` **.NET Encryption Sample**
              :link: https://github.com/didww/didww-api-3-dotnet-sdk/blob/main/src/Didww.Api3/Encrypt.cs
              :link-type: url
              :text-align: left

              Use the .NET sample implementation to add server-side file encryption compatible with DIDWW API v3.

      Encryption steps:
          1. Load the original document on the server.
          2. Encrypt the file using one of the supported libraries.
          3. Save the encrypted output with the ``.enc`` suffix.

      The result of this process is a ready-to-use encrypted file.

Upload the encrypted file
-------------------------

.. note::
   - Uploaded encrypted files expire after **24 hours**
   - Accepted file formats: **.pdf**, **.jpg**, **.png**
   - Each request uploads **one encrypted file**
   - Each file must not exceed **20 MB**

Upload the encrypted ``.enc`` file using the ``/v3/encrypted_files`` endpoint. This endpoint uses ``Content-Type: multipart/form-data`` and does **not** accept
JSON request bodies.

Each uploaded encrypted file is stored securely and results in a unique **encrypted file ID**, returned as ``data.id`` in the response.

..

Save this ``encrypted_file.id`` value, as it is required in later steps when:

- creating identity or address proofs (see :ref:`Step 10: Create Identity and Address Proofs <user-panel-api-examples-verification-step10>`)
- attaching permanent supporting documents, if required (see :ref:`Step 11: Create a Permanent Supporting Document <user-panel-api-examples-verification-step11>`)
- attaching one-time supporting documents, if required (see :ref:`Step 13: Assign End-User Details and Start DID Verification <user-panel-api-examples-verification-step13>`)

For more details, see the :ref:`Encrypted Files <encrypted_files_v34>` resource documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: curl

      .. code-block:: bash

         curl --location 'https://api.didww.com/v3/encrypted_files' \
           --header 'Accept: application/vnd.api+json' \
           --header 'Content-Type: multipart/form-data' \
           --header 'Api-Key: [API token]' \
           --form 'encrypted_files[encryption_fingerprint]={{encryption_fingerprint}}' \
           --form 'encrypted_files[description]=passport' \
           --form 'encrypted_files[file]=@"/path/to/passport.pdf.enc"'

   .. tab-item:: Response

      .. code-block:: json

         {
             "data": {
                 "id": "66df7731-fcf9-4bf3-a03f-2881bd44fe9c",
                 "type": "encrypted_files",
                 "attributes": {
                     "description": "passport",
                     "expires_at": "2026-01-17T07:38:42.508Z"
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

.. note::
   Legacy batch parameters such as ``encrypted_files[items][][file]`` are not
   supported in version ``2026-04-16`` and return ``400 Bad Request``.

   To upload multiple documents (for example, an identity proof and a
   permanent supporting document), send a separate request for each file and
   save the ``encrypted_file.id`` returned by each response.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step10:

Step 10: Create Identity and Address Proofs
===========================================

After the required documents have been encrypted and uploaded
(:ref:`Step 9 <user-panel-api-examples-verification-step9>`), they must be
associated with the appropriate identity or address as **proofs**.

Proof records represent the relationship between an uploaded document and the
entity it validates. Depending on the registration requirement, proofs may be
required for an identity (personal or business), an address, or both.

If the registration requirement specifies that proofs are required, create proof
records and link them to the corresponding entities involved in the verification
process. Each proof references an encrypted document, an accepted proof type,
and the entity it applies to.

These proof records are evaluated later in
:ref:`Step 12 <user-panel-api-examples-verification-step12>`, where the identity
and address are validated against the registration requirement

.. note::
   Proofs are required only when the corresponding quantity
   (``business_proof_qty``, ``personal_proof_qty``, or ``address_proof_qty``)
   is greater than ``0`` in the registration requirement.

Each proof requires:

    - an ``encrypted_file.id`` obtained in :ref:`Step 9 <user-panel-api-examples-verification-step9>` where the user uploads a document, the application encrypts it, and the encrypted file is submitted to the API
    - a ``proof_type.id`` accepted by the registration requirement retrieved in :ref:`Step 6 <user-panel-api-examples-verification-step6>`
    - an ``entity`` the proof applies to (use ``identities.id`` for identity proofs or ``addresses.id`` for address proofs)

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Create an identity proof*

      Use this approach when the registration requirement specifies
      ``business_proof_qty`` or ``personal_proof_qty`` greater than ``0``.

      .. note::
           The ``proof_type.id`` **must** be selected from the accepted proof types
           defined in the registration requirement retrieved in
           :ref:`Step 6 <user-panel-api-examples-verification-step6>`:

           - use ``relationships.personal_proof_types.data[].id`` for **personal** identities
           - use ``relationships.business_proof_types.data[].id`` for **business** identities

      .. http:example:: curl

         POST /v3/proofs HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "proofs",
                 "relationships": {
                     "files": {
                         "data": [
                             {
                                 "type": "encrypted_files",
                                 "id": "66df7731-fcf9-4bf3-a03f-2881bd44fe9c"
                             }
                         ]
                     },
                     "proof_type": {
                         "data": {
                             "type": "proof_types",
                             "id": "80253913-cd8b-4ce2-91a9-9299587ac409"
                         }
                     },
                     "entity": {
                         "data": {
                             "type": "identities",
                             "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "f03ec8b2-535e-46a4-a951-60922203a48c",
                 "type": "proofs",
                 "attributes": {
                     "created_at": "2026-01-09T13:20:09.232Z",
                     "expires_at": null
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

   .. tab-item:: *Create an address proof*

      Use this approach **only if** the registration requirement specifies
      ``address_proof_qty`` greater than ``0``.

      .. note::
           The proof type **must** be one of the accepted proof types listed under
           ``address_proof_types`` in the registration requirement retrieved in
           :ref:`Step 6 <user-panel-api-examples-verification-step6>`.
           Link the proof to the address by setting ``entity.type`` to ``addresses`` and
           ``entity.id`` to your ``address.id``.

      .. http:example:: curl

         POST /v3/proofs HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "proofs",
                 "relationships": {
                     "files": {
                         "data": [
                             {
                                 "type": "encrypted_files",
                                 "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
                             }
                         ]
                     },
                     "proof_type": {
                         "data": {
                             "type": "proof_types",
                             "id": "ffffffff-1111-2222-3333-444444444444"
                         }
                     },
                     "entity": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "f03ec8b2-535e-46a4-a951-60922203a48d",
                 "type": "proofs",
                 "attributes": {
                     "created_at": "2026-01-09T13:20:09.232Z",
                     "expires_at": null
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step11:

Step 11: Create a Permanent Supporting Document (If Required)
=============================================================

Some registration requirements mandate a **permanent supporting document**
(template-based document) to be submitted together with the **identity**.

A permanent supporting document is required when the registration requirement
contains one of the following:

- ``business_permanent_document`` (for business identities)
- ``personal_permanent_document`` (for personal identities)

.. note::
   If both ``business_permanent_document`` and ``personal_permanent_document`` are
   ``null`` in the requirement response, no permanent supporting document is
   required and this step can be skipped.

Each permanent supporting document requires:

- an ``encrypted_file.id`` obtained in
  :ref:`Step 9 <user-panel-api-examples-verification-step9>` after the user
  uploads the completed document and it is encrypted by the application
- a ``supporting_document_template.id`` defined by the registration requirement
  retrieved in :ref:`Step 6 <user-panel-api-examples-verification-step6>`
- an ``identity.id`` corresponding to the personal or business identity created in
  :ref:`Step 7 <user-panel-api-examples-verification-step7>`

For additional details, see the
:ref:`Permanent Supporting Documents <create_permanent_supporting_document_v34>`
resource documentation.

.. http:example:: curl

    POST /v3/permanent_supporting_documents HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
        "data": {
            "type": "permanent_supporting_documents",
            "relationships": {
                "files": {
                    "data": [
                        {
                            "type": "encrypted_files",
                            "id": "e5686c72-76fd-461e-bcfa-66c19be680f5"
                        }
                    ]
                },
                "template": {
                    "data": {
                        "type": "supporting_document_templates",
                        "id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
                    }
                },
                "identity": {
                    "data": {
                        "type": "identities",
                        "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                    }
                }
            }
        }
    }

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "363abdd4-2286-4b53-ab42-9726d61adc77",
            "type": "permanent_supporting_documents",
            "attributes": {
                "created_at": "2026-01-12T08:55:57.553Z"
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step12:

Step 12: Validate Identity and Address Against Requirements
===========================================================

Validate the identity, address, and all submitted proofs against the
registration requirement **before** starting the DID verification task.

This validation confirms that all regulatory conditions have been met and allows you
to detect missing or invalid data early, such as incomplete identity fields,
missing proofs, unsupported proof types, or address scope mismatches.

.. note::
    Validation is required only when the DID Group has a registration requirement
    (``needs_registration = true``).

The validation checks that:

- all mandatory identity fields are present
- the required number and type of proofs and supporting documents have been submitted
- the address meets the geographic restrictions defined by the requirement

If the validation succeeds, the identity and address are considered compliant
and can be safely assigned to the DID in the next step to start verification.

For additional details about requirement validation, see :ref:`Address Requirement Validations <address_requirement_validations_v34>`.

.. http:example:: curl

    POST /v3/address_requirement_validations HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
        "data": {
            "type": "address_requirement_validations",
            "relationships": {
                "address_requirement": {
                    "data": {
                        "type": "address_requirements",
                        "id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7"
                    }
                },
                "identity": {
                    "data": {
                        "type": "identities",
                        "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                    }
                },
                "address": {
                    "data": {
                        "type": "addresses",
                        "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                    }
                }
            }
        }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "e67bc7f0-71c1-451b-978e-d9188bcd39fa",
            "type": "address_requirement_validations"
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }

.. note::

    If the validation request is rejected, review the error details and adjust
    the identity, address, proofs, or supporting documents accordingly.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-verification-step13:

Step 13: Assign End-User Details and Start DID Verification
===========================================================

Create the verification task that assigns the validated **identity and address** to the DID and initiates the regulatory verification process.

.. note:: This step should be performed **only after** the identity, address, proofs, and documents have been successfully validated in :ref:`Step 12 <user-panel-api-examples-verification-step12>`.

The verification task evaluates all previously submitted data, including:

- the identity
- the address
- identity and address proofs (if required)
- permanent supporting documents (if required)
- one-time supporting documents (if required)

For more information, see :ref:`Address Verifications <address_verifications_v34>`.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Basic verification*

      Use this structure when the registration requirement does **not**
      specify a one-time supporting document.

      .. http:example:: curl

         POST /v3/address_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "address_verifications",
                 "attributes": {
                     "callback_url": "https://example.com/callback",
                     "callback_method": "post"
                 },
                 "relationships": {
                     "dids": {
                         "data": [
                             {
                                 "type": "dids",
                                 "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
                             }
                         ]
                     },
                     "address": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "066395a4-7904-4a68-97d2-a2fc007d0634",
                 "type": "address_verifications",
                 "attributes": {
                     "service_description": null,
                     "callback_url": "https://example.com/callback",
                     "callback_method": "post",
                     "status": "pending",
                     "reject_reasons": null,
                     "reference": "SVA-822866",
                     "created_at": "2026-01-12T09:46:19.214Z"
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

   .. tab-item:: *Verification with one-time document*

      Use this structure **only** when the registration requirement retrieved in :ref:`Step 6 <user-panel-api-examples-verification-step6>` defines a
      **one-time supporting document** under ``personal_onetime_document`` or ``business_onetime_document``.

      .. http:example:: curl

         POST /v3/address_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "address_verifications",
                 "attributes": {
                     "callback_url": "https://example.com/callback",
                     "callback_method": "post"
                 },
                 "relationships": {
                     "onetime_files": {
                         "data": [
                             {
                                 "type": "encrypted_files",
                                 "id": "11111111-2222-3333-4444-555555555555"
                             }
                         ]
                     },
                     "dids": {
                         "data": [
                             {
                                 "type": "dids",
                                 "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
                             }
                         ]
                     },
                     "address": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "066395a4-7904-4a68-97d2-a2fc007d0634",
                 "type": "address_verifications",
                 "attributes": {
                     "service_description": null,
                     "callback_url": "https://example.com/callback",
                     "callback_method": "post",
                     "status": "pending",
                     "reject_reasons": null,
                     "reference": "SVA-822866",
                     "created_at": "2026-01-12T09:46:19.214Z"
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

   .. tab-item:: *Verification with service description*

      Use this structure when the registration requirement retrieved in
      :ref:`Step 6 <user-panel-api-examples-verification-step6>` allows or requires
      providing a **service description** (``service_description_required = true``).

      The service description explains the intended use of the DID number
      (for example, customer support, outbound sales, or application notifications)
      and is evaluated as part of the regulatory verification process.

      .. http:example:: curl

         POST /v3/address_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
             "data": {
                 "type": "address_verifications",
                 "attributes": {
                     "callback_url": "https://example.com/callback",
                     "callback_method": "post",
                     "service_description": "Inbound customer support calls for a SaaS platform"
                 },
                 "relationships": {
                     "dids": {
                         "data": [
                             {
                                 "type": "dids",
                                 "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
                             }
                         ]
                     },
                     "address": {
                         "data": {
                             "type": "addresses",
                             "id": "04072428-07e4-4026-9d11-b49a770a95a8"
                         }
                     }
                 }
             }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
             "data": {
                 "id": "066395a4-7904-4a68-97d2-a2fc007d0634",
                 "type": "address_verifications",
                 "attributes": {
                     "service_description": "Inbound customer support calls for a SaaS platform",
                     "callback_url": "https://example.com/callback",
                     "callback_method": "post",
                     "status": "pending",
                     "reject_reasons": null,
                     "reference": "SVA-822866",
                     "created_at": "2026-01-12T09:46:19.214Z"
                 }
             },
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

Monitor the verification process until it becomes **Approved** or
**Rejected** by retrieving the verification status from the
``GET /v3/address_verifications`` endpoint.

The verification status indicates whether the submitted identity, address,
proofs, and supporting documents have been approved or rejected. If the
verification is rejected, the response includes a rejection reason that
explains what must be corrected before resubmitting.

.. note::
   A ``callback_url`` and ``callback_method`` can be configured for address
   verifications to receive HTTP callbacks when the verification status
   changes. |br|
   Callback events are sent when the verification is **approved** or
   **rejected**. The payload includes the verification ID, resource type
   (``address_verifications``), the current status, and a rejection reason when
   applicable.

   See :ref:`Callback configuration <callbacks_details_v34>` for more
   information.


.. |br| raw:: html

   <br />

.. _user-panel-api-examples-available-dids:
.. _api-examples-select-reserve-and-buy-available-dids:

==========================================================
Select, Reserve & Buy Available DID Number(s)
==========================================================

This example shows the **end-to-end process for purchasing a specific DID number**
from DID inventory by selecting it from the list of currently available numbers
and reserving it before placing the order.

This flow is used when your account has access to ``GET /v3/available_dids`` and you
want to provide users with the option to browse and select a full DID number
from the list of available numbers. This is useful when a user wants to choose
a preferred number, such as a memorable, recognizable, or visually appealing
number, instead of ordering any available DID that matches only general
inventory criteria.

Unlike a regular DID purchase, where the order is created using only the
selected inventory criteria or ``sku.id``, purchasing a specific DID number
requires an additional reservation step before the order is placed.

Because the selected DID number is a specific inventory item, you must first
retrieve the list of available DID numbers and allow the user to select a
number.

After the number is selected, you must create a **DID reservation** before
placing the order. The reservation temporarily holds the selected number for
your account so that another customer cannot purchase it while the order is
being completed.

DID reservations expire after a limited time. Check the ``expires_at`` field in
the reservation response to determine when the reservation ends. If the selected
number is not purchased before the reservation expires, it is released back to inventory
and becomes available for other customers to purchase.

To buy a specific available number from DID inventory, follow these steps:

- :ref:`Step 1: Find the Country ID <user-panel-api-examples-available-dids_step1>`
- :ref:`Step 2: Find the City ID <user-panel-api-examples-available-dids_step2>`
- :ref:`Step 3: Retrieve DID Availability, Pricing, and Number Selection Status <user-panel-api-examples-available-dids_step3>`
- :ref:`Step 4: Retrieve Available DIDs and Select a Number <user-panel-api-examples-available-dids_step4>`
- :ref:`Step 5: Create a DID Reservation <user-panel-api-examples-available-dids_step5>`
- :ref:`Step 6: Create the Order <user-panel-api-examples-available-dids_step6>`

.. important::

   - The ``GET /v3/available_dids`` feature is not enabled by default. To enable it, contact sales@didww.com.
   - Number selection availability may vary by country and city.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-available-dids_step1:

Step 1: Find the Country ID
===========================

Retrieve the unique ID for the target country using the ``/countries`` endpoint.
From the response, save the ``country.id`` for use in later steps when
retrieving cities and DID Groups.

For more information, see the :ref:`/v3/countries <countries_v34_get_countries>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Find a country by ISO code*

      Use this approach when your application already knows the target country
      (for example, from a stored customer selection or a predefined checkout flow).
      Filter by ISO code to retrieve the matching country and its ``country.id``.

      .. http:example:: curl

         GET /v3/countries?filter[iso]=US HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

      .. note::
         This example filters by country ISO code. Adjust filters as needed to match
         your use case.

   .. tab-item:: *List countries available for purchase*

      Use this approach when building a **country dropdown** for end users.
      This request returns countries that have DID Groups in coverage and DID numbers
      available for purchase. You can sort the results by name and use each item’s
      ``attributes.name`` for display and ``id`` as the selected ``country.id`` for
      later steps.

      ``filter[is_available]`` is a boolean filter:

      - When ``true``, returns countries with DID numbers available for purchase.
      - When ``false``, returns countries that exist in coverage but currently have no
        DID numbers available for purchase.

      .. http:example:: curl

         GET /v3/countries?filter[is_available]=true&sort=name HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
             "data": [
                 {
                     "id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
                     "type": "countries",
                     "attributes": {
                         "name": "Canada",
                         "prefix": "1",
                         "iso": "CA"
                     }
                 },
                 {
                     "id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
                     "type": "countries",
                     "attributes": {
                         "name": "United States",
                         "prefix": "1",
                         "iso": "US"
                     }
                 }
             ],
             "meta": {
                 "api_version": "2026-04-16"
             }
         }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-available-dids_step2:

Step 2: Find the City ID
========================

Depending on your application flow, selecting a city may be optional or required.
If your application allows users to narrow DID availability by **city** (for
example, when displaying a coverage list for local numbers), you should retrieve
and store the corresponding ``city.id``.

If your application does **not** differentiate availability by city (for example,
when listing all cities within a country or purchasing non–city-specific DIDs),
this step can be skipped.

Use the saved ``country.id`` to retrieve the city where the DID will be
purchased. From the response, save the ``city.id`` for use in later steps when
retrieving DID Groups that support number selection.

For more information, see the :ref:`/v3/cities <cities_v34_get_cities>` endpoint documentation.

.. http:example:: curl

    GET /v3/cities?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[name]=Los%20Angeles HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "f6672960-da2b-48a4-9f30-0065a8c54182",
                "type": "cities",
                "attributes": {
                    "name": "Los Angeles"
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2026-04-16"
        }
    }

.. note::

   This example filters the response by a single city name. Adjust the request
   parameters as needed to match your use case.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-available-dids_step3:

Step 3: Retrieve DID Availability, Pricing, and Number Selection Status
=======================================================================

Use the ``/did_groups`` endpoint, which is the **primary source for
building DID number coverage and availability** in your application.

It lets you present DID inventory for the selected location, including
available DID Groups, pricing, included channel options, and whether a DID
Group supports **number selection**.

When the DID Group returns ``available_dids_enabled = true``, your application
can offer number selection for that DID Group and retrieve specific available
numbers in the :ref:`next step <user-panel-api-examples-available-dids_step4>`..

From the ``GET /did_groups`` response, save the following values as needed:

- ``did_group.id`` – Required to retrieve the list of available DID numbers in :ref:`Step 4 <user-panel-api-examples-available-dids_step4>`.
- ``stock_keeping_units.id`` – Used to display pricing options, allow the user to choose the preferred channel amount, and :ref:`create the order <user-panel-api-examples-available-dids_step6>`.

For more information, see the :ref:`/v3/did_groups <did_groups_v34_get_did_groups>` endpoint documentation.

.. http:example:: curl

    GET /v3/did_groups?filter[country.id]=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter[city.id]=f6672960-da2b-48a4-9f30-0065a8c54182&filter[available_dids_enabled]=true HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
        "data": [
            {
                "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
                "type": "did_groups",
                "attributes": {
                    "prefix": "213",
                    "features": [
                        "voice_in"
                    ],
                    "is_metered": false,
                    "area_name": "Los Angeles",
                    "allow_additional_channels": true
                },
                "meta": {
                    "available_dids_enabled": true,
                    "needs_registration": false,
                    "is_available": true,
                    "total_count": 2369
                }
            }
        ],
        "meta": {
            "total_records": 1,
            "api_version": "2026-04-16"
        }
    }

.. important::

   Only DID Groups with ``available_dids_enabled = true`` support retrieving
   specific numbers using the ``/available_dids`` endpoint.

   - If the DID Group does **not** support this feature, use :ref:`Buy a DID Number from DID Inventory <user-panel-api-examples-did-group>`.
   - If the DID requires **verification** before activation, follow :ref:`Buy a DID Number that Requires Verification <user-panel-api-examples-verification>`.

----

.. raw:: html

   <br>

.. _user-panel-api-examples-available-dids_step4:

Step 4: Retrieve Available DIDs and Select a Number
=====================================================

Use the ``/available_dids`` endpoint to retrieve specific DID numbers that are currently available for purchase.

Call ``GET /v3/available_dids`` with ``include=did_group.stock_keeping_units`` to
retrieve available numbers together with their pricing options.

You may also filter by ``[filter]did_group.id`` to narrow the results to a specific DID
Group selected in :ref:`Step 3 <user-panel-api-examples-available-dids_step3>`.

From the ``GET /available_dids`` response, save the following values:

- ``available_dids.id`` – Required to create a DID reservation for the selected number in :ref:`Step 5 <user-panel-api-examples-available-dids_step5>`.
- ``stock_keeping_units.id`` – Required later when creating the order for the reserved DID number.

For more information, see the :ref:`/v3/available_dids <available_dids_v34_get_available_dids>` endpoint documentation.

.. http:example:: curl

    GET /v3/available_dids?include=did_group.stock_keeping_units&filter[did_group.id]=7fa8ba67-0622-4ac3-8ade-4aadf92566c5 HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Accept: application/vnd.api+json

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json

    {
      "data": [
        {
          "id": "ea9884ee-887e-4c20-befb-286db7cf55da",
          "type": "available_dids",
          "attributes": {
            "number": "12132933575"
          },
          "relationships": {
            "did_group": {
              "links": {
                "self": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/relationships/did_group",
                "related": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/did_group"
              },
              "data": {
                "type": "did_groups",
                "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5"
              }
            },
            "nanpa_prefix": {
              "links": {
                "self": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/relationships/nanpa_prefix",
                "related": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/nanpa_prefix"
              }
            }
          }
        }
      ],
      "included": [
        {
          "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
          "type": "did_groups",
          "attributes": {
            "prefix": "213",
            "features": [
              "voice_in"
            ],
            "is_metered": false,
            "area_name": "Los Angeles",
            "allow_additional_channels": true,
            "service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
          },
          "relationships": {
            "country": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/country",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/country"
              }
            },
            "city": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/city",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/city"
              }
            },
            "did_group_type": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/did_group_type",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/did_group_type"
              }
            },
            "region": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/region",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/region"
              }
            },
            "stock_keeping_units": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/stock_keeping_units",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/stock_keeping_units"
              },
              "data": [
                {
                  "type": "stock_keeping_units",
                  "id": "72f3a8a8-cd1e-41fc-8d4c-829e4fb8cdea"
                },
                {
                  "type": "stock_keeping_units",
                  "id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393"
                }
              ]
            },
            "address_requirement": {
              "links": {
                "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/address_requirement",
                "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/address_requirement"
              }
            }
          },
          "meta": {
            "available_dids_enabled": true,
            "needs_registration": false,
            "is_available": true,
            "total_count": 2371
          }
        },
        {
          "id": "72f3a8a8-cd1e-41fc-8d4c-829e4fb8cdea",
          "type": "stock_keeping_units",
          "attributes": {
            "channels_included_count": 0
          }
        },
        {
          "id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393",
          "type": "stock_keeping_units",
          "attributes": {
            "channels_included_count": 2
          }
        }
      ],
      "meta": {
        "total_count": 2368,
        "api_version": "2026-04-16"
      }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-available-dids_step5:

Step 5: Create a DID Reservation
================================

Reserve the selected number before creating the order. This temporarily locks
the DID for your account and prevents other users from purchasing it while the
order is being created.

Create the reservation using the ``available_dids.id`` value obtained in the
previous step.

The reservation remains active until the time shown in ``expires_at``. If you
need to extend the reservation, resend the ``POST /v3/did_reservations``
request for the same available DID before the reservation expires.

From the response, save the ``did_reservations.id`` and check ``expires_at`` to
see when the reservation expires.

For more information, see :doc:`Create DID Reservation <../2026-04-16/coverage-resources/did-reservation/create-did-reservation>`.

.. http:example:: curl

    POST /v3/did_reservations HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "did_reservations",
        "attributes": {
          "description": "Reserved for customer"
        },
        "relationships": {
          "available_did": {
            "data": {
              "type": "available_dids",
              "id": "4048d28a-6cab-46c9-98e9-d69d2466c131"
            }
          }
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6",
            "type": "did_reservations",
            "attributes": {
                "expires_at": "2026-03-19T11:38:15.074Z",
                "created_at": "2026-03-19T11:37:15.079Z",
                "description": "Reserved for customer"
            },
            "relationships": {
                "available_did": {
                    "data": {
                        "type": "available_dids",
                        "id": "4048d28a-6cab-46c9-98e9-d69d2466c131"
                    }
                }
            }
        }
    }

----

.. raw:: html

   <br>

.. _user-panel-api-examples-available-dids_step6:

Step 6: Create the Order
========================

Create the order using the selected ``stock_keeping_units.id`` and the saved
``did_reservations.id``.

This ensures the order is created for the **exact reserved DID number** selected
in the previous steps.

For more information, see the :ref:`/v3/orders <orders_v34_create_order>` endpoint documentation.

.. note::

   - A positive prepaid balance is required to successfully create the order.
   - For simplicity, detailed item attributes are not included in this response example.

.. http:example:: curl

    POST /v3/orders HTTP/1.1
    Host: api.didww.com
    Api-Key: [API token]
    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json

    {
      "data": {
        "type": "orders",
        "attributes": {
          "allow_back_ordering": false,
          "items": [
            {
              "type": "did_order_items",
              "attributes": {
                "sku_id": "7a2d041e-0f08-4f61-a59b-f2eca3af23f9",
                "did_reservation_id": "af7677ea-819c-4fc0-b0a6-588be5d434b2"
              }
            }
          ]
        }
      }
    }

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json

    {
        "data": {
            "id": "0f2dd6a8-7539-444a-b7c1-e89b3fe7d170",
            "type": "orders",
            "attributes": {
                "amount": "8.0",
                "status": "pending",
                "created_at": "2026-03-19T12:08:23.567Z",
                "description": "DID",
                "reference": "ZME-571778",
                "items": [
                    {
                        "type": "did_order_items",
                        "attributes": {
                            "qty": 1,
                            "nrc": "4.0",
                            "mrc": "4.0",
                            "prorated_mrc": false,
                            "billed_from": null,
                            "billed_to": null,
                            "did_group_id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5"
                        }
                    }
                ],
                "callback_method": null,
                "callback_url": null
            }
        },
        "meta": {
            "api_version": "2026-04-16"
        }
    }



.. |br| raw:: html

    <br/>

.. _user-panel-api-examples:

Use Case Examples
-----------------

Follow step-by-step examples for common DID number purchase flows. Use these
examples when you need to buy numbers based on different selection methods,
such as location, prefix, verification requirements, or specific number
availability. The examples also include emergency calling registration flows.
Each use case shows which API endpoints to call, which values to save, and how
to move through the flow.

.. note::

   These examples apply to API version **2026-04-16 (latest)**. For the previous version, see :ref:`2022-05-10 <user-panel-api-examples-v33>`.

.. grid:: 1 1 1 3
   :gutter: 5

   .. grid-item-card:: **Buy DID Number(s) that Requires Verification**
      :link: api-examples-buy-a-did-that-requires-verification
      :link-type: ref
      :text-align: center

      Learn how to purchase and verify a DID number when regulatory requirements apply.

   .. grid-item-card:: **Buy Available DID Number(s)**
      :link: api-examples-buy-available-dids
      :link-type: ref
      :text-align: center

      Learn how to filter DID inventory and order a matching number using API v3.

   .. grid-item-card:: **Select, Reserve & Buy Available DID Number(s)**
      :link: api-examples-select-reserve-and-buy-available-dids
      :link-type: ref
      :text-align: center

      Learn how to retrieve available DID numbers, reserve a selected number, and complete the purchase using API v3.

   .. grid-item-card:: **Register Emergency Calling Service**
      :link: api-examples-register-emergency-calling-service
      :link-type: ref
      :text-align: center

      Learn how to register existing DIDs for emergency calling by using emergency requirements, validations, and verifications.

   .. grid-item-card:: **Update Emergency Calling Service**
      :link: api-examples-update-emergency-calling-service
      :link-type: ref
      :text-align: center

      Learn how to replace the address of an existing emergency calling service by submitting a new emergency verification.

.. toctree::
  :maxdepth: 1
  :hidden:

    Buy DID Number(s) that Requires Verification <buy-dids-with-verification.rst>
    Buy Available DID Number(s) <buy-dids.rst>
    Select, Reserve & Buy Available DID Number(s) <buy-reserved-dids.rst>
    Register Emergency Calling Service <register-emergency-calling-service.rst>
    Update Emergency Calling Service <update-emergency-calling-service.rst>


.. |br| raw:: html

   <br />

.. _api-examples-register-emergency-calling-service:

=========================================
Register Emergency Calling Service
=========================================

.. raw:: html

    <div class="postman-run-button"
    data-postman-action="collection/fork"
    data-postman-var-1="17396892-33f2da62-506c-44d5-b8fe-b8c753d35864"
    data-postman-collection-url="entityId=17396892-33f2da62-506c-44d5-b8fe-b8c753d35864&entityType=collection&workspaceId=c7e9c67d-ac71-4c91-a5ef-b12f6619f415"
    data-postman-param="env%5BDIDWW%20Sandbox%5D=W3sia2V5IjoiaG9zdCIsInZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoic2FuZGJveC1hcGkuZGlkd3cuY29tIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImFwaUtleSIsInZhbHVlIjoieW91ckRpZHd3QXBpS2V5IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoieW91ckRpZHd3QXBpS2V5Iiwic2Vzc2lvbkluZGV4IjoxfV0=">
    </div>
    <p></p>
    <script type="text/javascript">
    (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
    (n = o.createElement("script")),
    (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
    }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
    </script>

This example shows the **end-to-end process for registering DIDs for emergency calling**
by using the Emergency Resources introduced in the latest API version.

Use this flow when you already own the DIDs and want to activate emergency calling
for them by submitting the required identity and address information for review.

To register emergency calling for your DIDs, follow these steps:

- :ref:`Step 1: Select the DIDs to register <api-examples-register-emergency-calling-service-step1>`
- :ref:`Step 2: Check Emergency Requirements <api-examples-register-emergency-calling-service-step2>`
- :ref:`Step 3: Select or Create an Identity <api-examples-register-emergency-calling-service-step3>`
- :ref:`Step 4: Select or Create an Address <api-examples-register-emergency-calling-service-step4>`
- :ref:`Step 5: Validate the Identity and Address <api-examples-register-emergency-calling-service-step5>`
- :ref:`Step 6: Submit Emergency Verification in New Calling Service <api-examples-register-emergency-calling-service-step6>`
- :ref:`Step 7: Monitor Emergency Verification Status <api-examples-register-emergency-calling-service-step7>`

.. note::

   The UUIDs shown in the examples below are for illustration purposes only.

   Always execute requests in your own environment and use the UUIDs returned in
   API responses.

----

.. raw:: html

   <br>

Before you begin
================

- A DIDWW API key is required to authenticate the requests shown in this guide. Make sure you have an :ref:`API key <api_key>` ready before starting the flow.
- Make sure you already have at least one active DID that supports the ``emergency`` feature. If you do not have a compatible DID yet, first buy one by following :ref:`Buy Available DID Number(s) <api-examples-buy-available-dids>`.

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step1:

Step 1: Select the DIDs to Register
===================================

This step uses the ``/dids`` endpoint, which is the **primary source for
selecting the existing DIDs that can be submitted for emergency registration**
in your application.

It allows you to present or validate:

- which DIDs already owned by the account belong to DID Groups with the
  ``emergency`` feature
- which of those DIDs do not yet have emergency routing enabled
- which country and DID Group type apply to the selected DIDs
- whether a DID is already linked to another Emergency Calling Service
- whether a DID already returns compliance relationships that affect the next steps

Include ``did_group.country``, ``did_group.did_group_type``,
``emergency_calling_service``, ``identity``, and ``address_verification`` in the request to obtain the following
information:

- **Country** - identifies the DID country and is required in the next step to
  retrieve the exact emergency requirement that applies to the selected DIDs
- **DID Group type** - identifies the DID type, such as Local or National, and
  is also required in the next step to retrieve the matching emergency
  requirement
- **Emergency Calling Service relationship** - shows whether the DID is already
  assigned to another Emergency Calling Service
- **Identity relationship** - shows whether the DID is already linked to a
  specific identity
- **Address Verification relationship** - helps distinguish the registration
  scenarios shown in the tabs below

From the ``GET /v3/dids`` response, save the following values:

- ``did.id`` - Required to create the emergency verification in
  :ref:`Step 6 <api-examples-register-emergency-calling-service-step6>`.
- ``did_group.country.id`` and ``did_group.did_group_type.id`` - Required in
  :ref:`Step 2 <api-examples-register-emergency-calling-service-step2>` to
  retrieve the matching emergency requirement for the selected DIDs.
- ``identity.id`` - If present, use it according to the registration scenario
  shown in the selected tab below.
- ``address_verification.id`` - If present, use it together with ``identity.id``
  to identify the end user registration scenario shown below.

.. important::

   All DIDs submitted in a single emergency verification should belong to the same
   country and DID Group type. Keep the selected DIDs consistent from the start,
   because a single emergency verification request cannot mix incompatible DID
   combinations.

.. note::

   - ``filter[did_group.features]=emergency`` limits the results to DIDs whose
     DID Groups support emergency calling registration.
   - ``filter[emergency_enabled]=false`` only shows that emergency routing is
     not active on the DID yet. It does **not** guarantee that the DID is free
     to be used in a new Emergency Calling Service.
   - Review ``emergency_calling_service`` before continuing. If it is already
     present, ``POST /v3/emergency_verifications`` can fail because the DID is
     already assigned to another Emergency Calling Service.

For more information, see :doc:`Get DIDs <../2026-04-16/inventory-resources/did/get-dids>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *DIDs without identity*

      This case shows a DID with no existing emergency registration or prior
      identity linkage. The rest of the flow can start without having to reuse
      an already assigned identity or address.

      In this case:

      - ``emergency_calling_service.data`` is ``null``
      - ``identity.data`` is ``null``
      - ``address_verification.data`` is ``null``

      This means the remaining steps can start with a clean selection of
      identity and address data.

      .. http:example:: curl

         GET /v3/dids?include=did_group.country,did_group.did_group_type,emergency_calling_service,identity,address_verification&filter[did_group.features]=emergency&filter[emergency_enabled]=false HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901",
               "type": "dids",
               "attributes": {
                 "blocked": false,
                 "capacity_limit": null,
                 "description": null,
                 "terminated": false,
                 "awaiting_registration": false,
                 "created_at": "2026-04-21T09:15:11.000Z",
                 "billing_cycles_count": null,
                 "number": "37052032111",
                 "expires_at": "2026-05-21T09:15:11.761Z",
                 "channels_included_count": 6,
                 "dedicated_channels_count": 0,
                 "emergency_enabled": false
               },
               "relationships": {
                 "did_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/did_group",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/did_group"
                   },
                   "data": {
                     "type": "did_groups",
                     "id": "8c76122b-402d-4217-880a-4050ee884acb"
                   }
                 },
                 "order": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/order",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/order"
                   }
                 },
                 "capacity_pool": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/capacity_pool",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/capacity_pool"
                   }
                 },
                 "shared_capacity_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/shared_capacity_group",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/shared_capacity_group"
                   }
                 },
                 "address_verification": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/address_verification",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/address_verification"
                   },
                   "data": null
                 },
                 "voice_in_trunk": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/voice_in_trunk",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/voice_in_trunk"
                   }
                 },
                 "voice_in_trunk_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/voice_in_trunk_group",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/voice_in_trunk_group"
                   }
                 },
                 "emergency_calling_service": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/emergency_calling_service",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/emergency_calling_service"
                   },
                   "data": null
                 },
                 "emergency_verification": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/emergency_verification",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/emergency_verification"
                   }
                 },
                 "identity": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/relationships/identity",
                     "related": "https://staging-api.didww.com/v3/dids/3d2bb4b1-7c8d-4ec0-9d5d-c2a0d8b8a901/identity"
                   },
                   "data": null
                 }
               }
             }
           ],
           "included": [
             {
               "id": "8c76122b-402d-4217-880a-4050ee884acb",
               "type": "did_groups",
               "attributes": {
                 "prefix": "5",
                 "features": [
                   "voice_in",
                   "voice_out",
                   "emergency"
                 ],
                 "is_metered": false,
                 "area_name": "Vilnius",
                 "allow_additional_channels": true,
                 "service_restrictions": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/country",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "661d8448-8897-4765-acda-00cc1740148d"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/city",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/region",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/stock_keeping_units",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/stock_keeping_units"
                   }
                 },
                 "address_requirement": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/address_requirement",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/address_requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": true,
                 "is_available": true,
                 "total_count": 254
               }
             },
             {
               "id": "661d8448-8897-4765-acda-00cc1740148d",
               "type": "countries",
               "attributes": {
                 "name": "Lithuania",
                 "prefix": "370",
                 "iso": "LT"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/regions"
                   }
                 }
               }
             },
             {
               "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
               "type": "did_group_types",
               "attributes": {
                 "name": "Local"
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/dids?filter%5Bdid_group.features%5D=emergency&filter%5Bemergency_enabled%5D=false&include=did_group.country%2Cdid_group.did_group_type%2Cemergency_calling_service%2Cidentity%2Caddress_verification&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/dids?filter%5Bdid_group.features%5D=emergency&filter%5Bemergency_enabled%5D=false&include=did_group.country%2Cdid_group.did_group_type%2Cemergency_calling_service%2Cidentity%2Caddress_verification&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *DIDs with identity from end user registration*

      This scenario applies to numbers that were purchased with end user
      registration required.

      In such cases, the number cannot be activated until the required end user
      registration details are completed. As part of that process, the customer
      must provide identity and address information, and the DID is assigned both
      an identity and an address verification record.

      Once the end user registration process is successfully completed and the
      number is activated, the DID already has both ``identity`` and
      ``address_verification`` relationships.

      Because the DID is already tied to one approved customer identity, emergency
      verification must continue with that same identity. A different identity
      cannot be assigned later in the flow unless the DID is reassigned to a new
      identity and the end user registration process is completed again for that
      new identity. After that, emergency verification can proceed using the newly
      assigned identity.

      This is why in
      :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>` and
      :ref:`Step 4 <api-examples-register-emergency-calling-service-step4>` you
      must keep using that same identity and select an address linked to it.
      Emergency verification checks that the DID remains assigned to the same
      approved customer identity that was used during end user registration. If
      you later submit emergency verification with an address linked to a
      different identity, the request can fail with the mismatch error shown in
      :ref:`Step 6 <api-examples-register-emergency-calling-service-step6>`.

      In this case:

      - ``identity.data`` is present
      - ``address_verification.data`` is present
      - the same identity must be reused in
        :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`
        and :ref:`Step 4 <api-examples-register-emergency-calling-service-step4>`

      .. note::

         This information should be clearly shown to the end user during identity
         selection. The DID is already linked to an identity that was used to
         activate the number, so the same identity must be selected to activate
         emergency service for this DID.

      .. http:example:: curl

         GET /v3/dids?include=did_group.country,did_group.did_group_type,emergency_calling_service,identity,address_verification&filter[did_group.features]=emergency&filter[emergency_enabled]=false HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "9f81f2ef-ad6c-402b-97af-06fff514454e",
               "type": "dids",
               "attributes": {
                 "blocked": false,
                 "capacity_limit": null,
                 "description": null,
                 "terminated": false,
                 "awaiting_registration": false,
                 "created_at": "2026-04-16T12:12:34.000Z",
                 "billing_cycles_count": null,
                 "number": "37052032110",
                 "expires_at": "2026-05-21T08:10:39.095Z",
                 "channels_included_count": 6,
                 "dedicated_channels_count": 0,
                 "emergency_enabled": false
               },
               "relationships": {
                 "did_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/did_group",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/did_group"
                   },
                   "data": {
                     "type": "did_groups",
                     "id": "8c76122b-402d-4217-880a-4050ee884acb"
                   }
                 },
                 "order": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/order",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/order"
                   }
                 },
                 "capacity_pool": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/capacity_pool",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/capacity_pool"
                   }
                 },
                 "shared_capacity_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/shared_capacity_group",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/shared_capacity_group"
                   }
                 },
                 "address_verification": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/address_verification",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/address_verification"
                   },
                   "data": {
                     "type": "address_verifications",
                     "id": "8ee9ea68-992c-442d-84b3-37d69a2ba8f5"
                   }
                 },
                 "voice_in_trunk": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/voice_in_trunk",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/voice_in_trunk"
                   }
                 },
                 "voice_in_trunk_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/voice_in_trunk_group",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/voice_in_trunk_group"
                   }
                 },
                 "emergency_calling_service": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/emergency_calling_service",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/emergency_calling_service"
                   },
                   "data": null
                 },
                 "emergency_verification": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/emergency_verification",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/emergency_verification"
                   }
                 },
                 "identity": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/relationships/identity",
                     "related": "https://staging-api.didww.com/v3/dids/9f81f2ef-ad6c-402b-97af-06fff514454e/identity"
                   },
                   "data": {
                     "type": "identities",
                     "id": "1193bf05-f01c-467f-b688-d0526ab50414"
                    }
                 }
               }
             }
           ],
           "included": [
             {
               "id": "8c76122b-402d-4217-880a-4050ee884acb",
               "type": "did_groups",
               "attributes": {
                 "prefix": "5",
                 "features": [
                   "voice_in",
                   "voice_out",
                   "emergency"
                 ],
                 "is_metered": false,
                 "area_name": "Vilnius",
                 "allow_additional_channels": true,
                 "service_restrictions": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/country",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "661d8448-8897-4765-acda-00cc1740148d"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/city",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/region",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/stock_keeping_units",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/stock_keeping_units"
                   }
                 },
                 "address_requirement": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/address_requirement",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/address_requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": true,
                 "is_available": true,
                 "total_count": 254
               }
             },
             {
               "id": "661d8448-8897-4765-acda-00cc1740148d",
               "type": "countries",
               "attributes": {
                 "name": "Lithuania",
                 "prefix": "370",
                 "iso": "LT"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/regions"
                   }
                 }
               }
             },
             {
               "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
               "type": "did_group_types",
               "attributes": {
                 "name": "Local"
               }
             },
             {
               "id": "1193bf05-f01c-467f-b688-d0526ab50414",
               "type": "identities",
               "attributes": {
                 "external_reference_id": null,
                 "first_name": "string",
                 "last_name": "string",
                 "phone_number": "37052032100",
                 "id_number": null,
                 "birth_date": null,
                 "identity_type": "business",
                 "company_name": "test",
                 "company_reg_number": null,
                 "vat_id": null,
                 "description": "string",
                 "personal_tax_id": null,
                 "created_at": "2026-04-21T07:50:38.639Z",
                 "verified": true,
                 "contact_email": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/relationships/country",
                     "related": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/relationships/proofs",
                     "related": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/proofs"
                   }
                 },
                 "addresses": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/relationships/addresses",
                     "related": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/addresses"
                   }
                 },
                 "permanent_documents": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/relationships/permanent_documents",
                     "related": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/permanent_documents"
                   }
                 },
                 "birth_country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/relationships/birth_country",
                     "related": "https://staging-api.didww.com/v3/identities/1193bf05-f01c-467f-b688-d0526ab50414/birth_country"
                   }
                 }
               }
             },
             {
               "id": "8ee9ea68-992c-442d-84b3-37d69a2ba8f5",
               "type": "address_verifications",
               "attributes": {
                 "status": "approved",
                 "reference": "DFH-637703",
                 "external_reference_id": null
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/dids?filter%5Bdid_group.features%5D=emergency&filter%5Bemergency_enabled%5D=false&include=did_group.country%2Cdid_group.did_group_type%2Cemergency_calling_service%2Cidentity%2Caddress_verification&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/dids?filter%5Bdid_group.features%5D=emergency&filter%5Bemergency_enabled%5D=false&include=did_group.country%2Cdid_group.did_group_type%2Cemergency_calling_service%2Cidentity%2Caddress_verification&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *DIDs with identity from porting*

      This scenario applies to numbers that were ported into your DIDWW account.

      During the port-in process, the number owner must provide identity
      information to complete the porting request and activate the number. This is
      done in the DIDWW User Panel through the porting tool. As a result, once the
      number has been successfully ported and activated, it may already have an
      identity associated with it from the earlier porting flow.

      In such cases, the DID has an ``identity`` relationship, so
      ``identity.data`` is available. However, because no approved address
      verification was created as part of that process,
      ``address_verification.data`` is not available and is returned as ``null``.

      The existing identity can be reused later in the emergency registration flow,
      but it is not required. A different identity may also be selected for
      emergency verification.

      In this case:

      - ``identity.data`` is present
      - ``address_verification.data`` is ``null``
      - the existing identity may be reused, but it does not have to be kept for
        :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`
        and :ref:`Step 4 <api-examples-register-emergency-calling-service-step4>`

      .. note::

         For implementation purposes, when ``identity.data`` exists but
         ``address_verification.data`` is ``null``, the linked identity comes from
         porting. It may be displayed and preselected in the UI, but the user
         can replace it with another identity during emergency registration. This
         case should be handled the same way as a DID without a linked identity.

      .. http:example:: curl

         GET /v3/dids?include=did_group.country,did_group.did_group_type,emergency_calling_service,identity,address_verification&filter[did_group.features]=emergency&filter[emergency_enabled]=false HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa",
               "type": "dids",
               "attributes": {
                 "blocked": false,
                 "capacity_limit": null,
                 "description": null,
                 "terminated": false,
                 "awaiting_registration": false,
                 "created_at": "2026-04-21T08:42:56.000Z",
                 "billing_cycles_count": null,
                 "number": "37052032113",
                 "expires_at": "2026-05-21T08:44:55.761Z",
                 "channels_included_count": 6,
                 "dedicated_channels_count": 0,
                 "emergency_enabled": false
               },
               "relationships": {
                 "did_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/did_group",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/did_group"
                   },
                   "data": {
                     "type": "did_groups",
                     "id": "8c76122b-402d-4217-880a-4050ee884acb"
                   }
                 },
                 "order": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/order",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/order"
                   }
                 },
                 "capacity_pool": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/capacity_pool",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/capacity_pool"
                   }
                 },
                 "shared_capacity_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/shared_capacity_group",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/shared_capacity_group"
                   }
                 },
                 "address_verification": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/address_verification",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/address_verification"
                   },
                   "data": null
                 },
                 "voice_in_trunk": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/voice_in_trunk",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/voice_in_trunk"
                   }
                 },
                 "voice_in_trunk_group": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/voice_in_trunk_group",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/voice_in_trunk_group"
                   }
                 },
                 "emergency_calling_service": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/emergency_calling_service",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/emergency_calling_service"
                   },
                   "data": null
                 },
                 "emergency_verification": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/emergency_verification",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/emergency_verification"
                   }
                 },
                 "identity": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/relationships/identity",
                     "related": "https://staging-api.didww.com/v3/dids/cc4c423f-68b5-4e1a-878c-2328eb24f3fa/identity"
                   },
                   "data": {
                     "type": "identities",
                     "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                   }
                 }
               }
             }
           ],
           "included": [
             {
               "id": "8c76122b-402d-4217-880a-4050ee884acb",
               "type": "did_groups",
               "attributes": {
                 "prefix": "5",
                 "features": [
                   "voice_in",
                   "voice_out",
                   "emergency"
                 ],
                 "is_metered": false,
                 "area_name": "Vilnius",
                 "allow_additional_channels": true,
                 "service_restrictions": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/country",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "661d8448-8897-4765-acda-00cc1740148d"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/city",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/city"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 },
                 "region": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/region",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/region"
                   }
                 },
                 "stock_keeping_units": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/stock_keeping_units",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/stock_keeping_units"
                   }
                 },
                 "address_requirement": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/relationships/address_requirement",
                     "related": "https://staging-api.didww.com/v3/did_groups/8c76122b-402d-4217-880a-4050ee884acb/address_requirement"
                   }
                 }
               },
               "meta": {
                 "available_dids_enabled": true,
                 "needs_registration": true,
                 "is_available": true,
                 "total_count": 254
               }
             },
             {
               "id": "661d8448-8897-4765-acda-00cc1740148d",
               "type": "countries",
               "attributes": {
                 "name": "Lithuania",
                 "prefix": "370",
                 "iso": "LT"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/regions"
                   }
                 }
               }
             },
             {
               "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
               "type": "did_group_types",
               "attributes": {
                 "name": "Local"
               }
             },
             {
               "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
               "type": "identities",
               "attributes": {
                 "external_reference_id": null,
                 "first_name": "John",
                 "last_name": "Smith",
                 "phone_number": "3233461122",
                 "id_number": null,
                 "birth_date": null,
                 "company_name": "Example Company Ltd",
                 "company_reg_number": null,
                 "vat_id": "BE0123456789",
                 "description": null,
                 "personal_tax_id": null,
                 "identity_type": "business",
                 "created_at": "2026-01-09T07:30:12.546Z",
                 "verified": true,
                 "contact_email": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/country",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/proofs",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/proofs"
                   }
                 },
                 "addresses": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/addresses",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/addresses"
                   }
                 },
                 "permanent_documents": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/permanent_documents",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/permanent_documents"
                   }
                 },
                 "birth_country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/birth_country",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/birth_country"
                   }
                 }
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/dids?filter%5Bdid_group.features%5D=emergency&filter%5Bemergency_enabled%5D=false&include=did_group.country%2Cdid_group.did_group_type%2Cemergency_calling_service%2Cidentity%2Caddress_verification&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/dids?filter%5Bdid_group.features%5D=emergency&filter%5Bemergency_enabled%5D=false&include=did_group.country%2Cdid_group.did_group_type%2Cemergency_calling_service%2Cidentity%2Caddress_verification&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step2:

Step 2: Check Emergency Requirements
====================================

Use the ``/emergency_requirements`` endpoint to present end users with the
emergency registration requirements and other relevant information for the
selected **country** and **DID Group type**.

.. note:: If the user has already selected a specific DID in :ref:`Step 1
    <api-examples-register-emergency-calling-service-step1>` for which they want
    to enable emergency service, the application may preselect and display the
    corresponding country and DID Group type, and then retrieve the exact
    requirement that applies to that DID.

This step should be used not only for backend validation, but also to build the
information the end user needs before continuing with emergency registration.

Your application should use this step to:

- list the emergency supported countries returned by the API and, after a
  country is selected, show the DID Group types supported for that country to
  narrow down the available options
- let the user first select a country, or preselect it if it is already known
- once both the country and DID Group type are selected, retrieve and display
  the exact emergency requirement for that combination
- present the returned requirement details to the end user before continuing, so
  they can understand what identity and address information will be required in
  the next steps
- determine which identity and address data must be selected or created before
  the emergency verification is submitted

From the requirement that matches the selected country and DID Group type
such as ``local``, ``mobile``, or another supported number type, use the
following fields in later steps of the flow:

- ``emergency_requirement.id`` for the validation step
- ``identity_type`` to decide whether a ``personal`` or ``business`` identity is allowed
- ``address_area_level`` to understand how specific the address must be
- ``address_mandatory_fields`` to know which address fields become required
- ``personal_area_level`` / ``business_area_level`` to understand identity country restrictions
- ``personal_mandatory_fields`` / ``business_mandatory_fields`` to know which identity fields become required when the user selects an existing identity or creates a new one

In this step, display the following information to the user before continuing:

- ``requirement_restriction_message`` to show additional registration guidance together with the selected country and DID Group type whenever it is present
- ``meta.setup_price`` and ``meta.monthly_price`` to show the expected emergency service pricing per number before submission
- ``estimate_setup_time`` to show the estimated verification time, for example ``Estimated verification time: 7-14 days``

For more information, see :doc:`Emergency Requirement object <../2026-04-16/emergency-resources/emergency-requirements/emergency-requirement-object>`.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Load requirements for selection*

      Use this approach when your UI needs to display all available emergency
      registration combinations before the user chooses which DIDs to register.

      By including ``country`` and ``did_group_type``, your application can present
      human-readable values such as **Lithuania** and **Local** instead of
      showing only UUIDs from relationship data.

      This request does not yet determine which requirement applies to the
      selected DIDs. It is used earlier in the flow to show what combinations
      are supported at all, so the user can understand the available emergency
      registration scope before the exact requirement is loaded for the DIDs
      selected in :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`.

      This is especially useful when you want to:

      - build a country picker for emergency registration
      - show which DID Group types are supported in each country
      - show the requirement restrictions and pricing before the user continues with the flow

      .. http:example:: curl

         GET /v3/emergency_requirements?include=country,did_group_type HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "37067e8b-c9c4-4b77-af7f-f514d28e68fd",
               "type": "emergency_requirements",
               "attributes": {
                 "identity_type": "any",
                 "address_area_level": "country",
                 "personal_area_level": "world_wide",
                 "business_area_level": "world_wide",
                 "address_mandatory_fields": [],
                 "personal_mandatory_fields": [],
                 "business_mandatory_fields": [],
                 "estimate_setup_time": "7-14 days",
                 "requirement_restriction_message": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/37067e8b-c9c4-4b77-af7f-f514d28e68fd/relationships/country",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/37067e8b-c9c4-4b77-af7f-f514d28e68fd/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "3d1c2c4e-4b06-4c94-8f0b-43eea90929a0"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/37067e8b-c9c4-4b77-af7f-f514d28e68fd/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/37067e8b-c9c4-4b77-af7f-f514d28e68fd/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 }
               },
               "meta": {
                 "setup_price": 0,
                 "monthly_price": "0.5"
               }
             },
             {
               "id": "a80051e5-5f77-4003-b164-63b1ccfc5377",
               "type": "emergency_requirements",
               "attributes": {
                 "identity_type": "any",
                 "address_area_level": "country",
                 "personal_area_level": "world_wide",
                 "business_area_level": "world_wide",
                 "address_mandatory_fields": [],
                 "personal_mandatory_fields": [],
                 "business_mandatory_fields": [],
                 "estimate_setup_time": "7-14 days",
                 "requirement_restriction_message": "Requirement restriction message"
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/a80051e5-5f77-4003-b164-63b1ccfc5377/relationships/country",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/a80051e5-5f77-4003-b164-63b1ccfc5377/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "7549be3c-1077-433d-9a77-25416373660d"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/a80051e5-5f77-4003-b164-63b1ccfc5377/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/a80051e5-5f77-4003-b164-63b1ccfc5377/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 }
               },
               "meta": {
                 "setup_price": 0,
                 "monthly_price": "0.75"
               }
             },
             {
               "id": "f788cef0-b278-4f21-a870-23950e67d0a1",
               "type": "emergency_requirements",
               "attributes": {
                 "identity_type": "any",
                 "address_area_level": "country",
                 "personal_area_level": "world_wide",
                 "business_area_level": "world_wide",
                 "address_mandatory_fields": [],
                 "personal_mandatory_fields": [],
                 "business_mandatory_fields": [],
                 "estimate_setup_time": "7-14 days",
                 "requirement_restriction_message": "Requirement restriction message"
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/relationships/country",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "661d8448-8897-4765-acda-00cc1740148d"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 }
               },
               "meta": {
                 "setup_price": 0,
                 "monthly_price": "1.0"
               }
             }
           ],
           "included": [
             {
               "id": "3d1c2c4e-4b06-4c94-8f0b-43eea90929a0",
               "type": "countries",
               "attributes": {
                 "name": "Argentina",
                 "prefix": "54",
                 "iso": "AR"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/3d1c2c4e-4b06-4c94-8f0b-43eea90929a0/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/3d1c2c4e-4b06-4c94-8f0b-43eea90929a0/regions"
                   }
                 }
               }
             },
             {
               "id": "7549be3c-1077-433d-9a77-25416373660d",
               "type": "countries",
               "attributes": {
                 "name": "Sweden",
                 "prefix": "46",
                 "iso": "SE"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/7549be3c-1077-433d-9a77-25416373660d/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/7549be3c-1077-433d-9a77-25416373660d/regions"
                   }
                 }
               }
             },
             {
               "id": "661d8448-8897-4765-acda-00cc1740148d",
               "type": "countries",
               "attributes": {
                 "name": "Lithuania",
                 "prefix": "370",
                 "iso": "LT"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/regions"
                   }
                 }
               }
             },
             {
               "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
               "type": "did_group_types",
               "attributes": {
                 "name": "Local"
               }
             }
           ],
           "meta": {
             "total_records": 65,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/emergency_requirements?include=country%2Cdid_group_type&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "next": "https://staging-api.didww.com/v3/emergency_requirements?include=country%2Cdid_group_type&page%5Bnumber%5D=2&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/emergency_requirements?include=country%2Cdid_group_type&page%5Bnumber%5D=2&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *Load the matching requirement*

      Use this approach when the DIDs were already selected in
      :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>` and
      you want to retrieve the exact emergency requirement that applies to those
      DIDs.

      By filtering with the saved ``country.id`` and ``did_group_type.id``, your
      application can load only the matching requirement instead of presenting the
      full list of supported combinations.

      This is the requirement that should be treated as the source of truth for
      the rest of the flow. It determines which identity type is accepted, how
      specific the address must be, which fields become mandatory, and what
      setup time or pricing can be shown before submission.

      This is especially useful when you want to:

      - load the exact requirement for the selected DIDs before collecting identity and address data
      - show a confirmation view with the requirement details that apply to the selected DIDs
      - determine which fields become required before the user continues

      .. http:example:: curl

         GET /v3/emergency_requirements?include=country,did_group_type&filter[country.id]=661d8448-8897-4765-acda-00cc1740148d&filter[did_group_type.id]=994ea201-4a4d-4b27-ac4b-b5916ac969a3 HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "f788cef0-b278-4f21-a870-23950e67d0a1",
               "type": "emergency_requirements",
               "attributes": {
                 "identity_type": "any",
                 "address_area_level": "country",
                 "personal_area_level": "world_wide",
                 "business_area_level": "world_wide",
                 "address_mandatory_fields": [],
                 "personal_mandatory_fields": [],
                 "business_mandatory_fields": [],
                 "estimate_setup_time": "7-14 days",
                 "requirement_restriction_message": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/relationships/country",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/country"
                   },
                   "data": {
                     "type": "countries",
                     "id": "661d8448-8897-4765-acda-00cc1740148d"
                   }
                 },
                 "did_group_type": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/relationships/did_group_type",
                     "related": "https://staging-api.didww.com/v3/emergency_requirements/f788cef0-b278-4f21-a870-23950e67d0a1/did_group_type"
                   },
                   "data": {
                     "type": "did_group_types",
                     "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                   }
                 }
               },
               "meta": {
                 "setup_price": 0,
                 "monthly_price": "1.0"
               }
             }
           ],
           "included": [
             {
               "id": "661d8448-8897-4765-acda-00cc1740148d",
               "type": "countries",
               "attributes": {
                 "name": "Lithuania",
                 "prefix": "370",
                 "iso": "LT"
               },
               "relationships": {
                 "regions": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/relationships/regions",
                     "related": "https://staging-api.didww.com/v3/countries/661d8448-8897-4765-acda-00cc1740148d/regions"
                   }
                 }
               }
             },
             {
               "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
               "type": "did_group_types",
               "attributes": {
                 "name": "Local"
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/emergency_requirements?filter%5Bcountry.id%5D=661d8448-8897-4765-acda-00cc1740148d&filter%5Bdid_group_type.id%5D=994ea201-4a4d-4b27-ac4b-b5916ac969a3&include=country%2Cdid_group_type&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/emergency_requirements?filter%5Bcountry.id%5D=661d8448-8897-4765-acda-00cc1740148d&filter%5Bdid_group_type.id%5D=994ea201-4a4d-4b27-ac4b-b5916ac969a3&include=country%2Cdid_group_type&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

.. important::

   Use the emergency requirement as the source of truth for what you create next.
   If the requirement expects a ``business`` identity, a personal identity will fail validation.
   If ``address_area_level`` is ``country``, the address must belong to the same country as the selected DIDs.

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step3:

Step 3: Select or Create an Identity
====================================

At this stage, you need an identity that satisfies the emergency requirement from
:ref:`Step 2 <api-examples-register-emergency-calling-service-step2>`.

If you already have a suitable identity on file, you can select and reuse it.
If not, create a new identity that matches the requirement.

The identity is the customer record that will be assigned to the emergency
verification. This is why the identity must match the requirement before you
continue. If the wrong identity type is selected, if the required fields are
missing, or if the DID already has end user registration on another identity,
the validation step or the emergency verification request can fail.

Use the result from :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`
to decide which identity path applies:

- if ``emergency_calling_service.data`` is present, do not continue with that DID
- if both ``identity.data`` and ``address_verification.data`` are present, reuse
  that exact identity
- if ``identity.data`` is present but ``address_verification.data`` is ``null``,
  the DID may only have a porting identity, which can be reused or replaced
- if both relationships are ``null``, select an existing identity or create a new
  one that satisfies the emergency requirement

Use the emergency requirement to determine:

- whether the identity must be ``personal`` or ``business``
- which identity fields are mandatory
- whether the identity country must match the DID country

From this step, save ``identity.id``. You will use it to select or create the
address in :ref:`Step 4 <api-examples-register-emergency-calling-service-step4>`.

For more information, see :doc:`Create Identity <../2026-04-16/regulation-resources/identities/create-identity>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Select an existing identity*

      Use this approach first when you already have an identity on file that
      satisfies the emergency requirement.

      If :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`
      returned both ``identity`` and ``address_verification`` for the selected DID,
      choose that same identity here. In that case, the DID already has end user
      registration and emergency verification must stay on the same identity.

      Review the returned identities and select one that matches:

      - the required ``identity_type``
      - the required ``country`` scope
      - the mandatory fields defined by the emergency requirement

      In practice, this request is useful when your application wants to let the
      user pick from previously created customer identities instead of creating a
      new record every time.

      .. http:example:: curl

         GET /v3/identities?filter[identity_type]=business&filter[country.id]=661d8448-8897-4765-acda-00cc1740148d HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
               "type": "identities",
               "attributes": {
                 "first_name": "John",
                 "last_name": "Smith",
                 "phone_number": "3233461122",
                 "id_number": null,
                 "birth_date": null,
                 "company_name": "Example Company Ltd",
                 "company_reg_number": null,
                 "vat_id": "BE0123456789",
                 "description": null,
                 "personal_tax_id": null,
                 "identity_type": "business",
                 "created_at": "2026-01-09T07:30:12.546Z",
                 "external_reference_id": null,
                 "verified": true,
                 "contact_email": null
               },
               "relationships": {
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/country",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/proofs",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/proofs"
                   }
                 },
                 "addresses": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/addresses",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/addresses"
                   }
                 },
                 "permanent_documents": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/permanent_documents",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/permanent_documents"
                   }
                 },
                 "birth_country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/birth_country",
                     "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/birth_country"
                   }
                 }
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/identities?filter%5Bidentity_type%5D=business&filter%5Bcountry.id%5D=661d8448-8897-4765-acda-00cc1740148d&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/identities?filter%5Bidentity_type%5D=business&filter%5Bcountry.id%5D=661d8448-8897-4765-acda-00cc1740148d&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *Create a new personal identity*

      Use this approach when the emergency requirement allows ``personal``
      identities and there is no suitable existing identity to reuse.

      A personal identity is typically used when the emergency requirement
      expects an individual end user instead of a business entity. Adjust the
      submitted fields according to the requirement returned in
      :ref:`Step 2 <api-examples-register-emergency-calling-service-step2>`.

      Create a new personal identity only when
      :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`
      does not force you to reuse an existing approved identity. The request
      should include every field required by the selected emergency requirement
      so that :ref:`Step 5 <api-examples-register-emergency-calling-service-step5>`
      can validate it successfully. This is the usual path when there is no
      existing suitable identity to select in the previous tab.

      .. http:example:: curl

         POST /v3/identities HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "identities",
             "attributes": {
               "first_name": "Jane",
               "last_name": "Smith",
               "phone_number": "37052032123",
               "birth_date": "1990-01-01",
               "description": "Emergency registration identity",
               "identity_type": "personal",
               "contact_email": "jane.smith@example.com"
             },
             "relationships": {
               "country": {
                 "data": {
                   "type": "countries",
                   "id": "661d8448-8897-4765-acda-00cc1740148d"
                 }
               }
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
             "type": "identities",
             "attributes": {
               "first_name": "Jane",
               "last_name": "Smith",
               "phone_number": "37052032123",
               "id_number": null,
               "birth_date": "1990-01-01",
               "company_name": null,
               "company_reg_number": null,
               "vat_id": null,
               "description": "Emergency registration identity",
               "personal_tax_id": null,
               "identity_type": "personal",
               "created_at": "2026-04-21T09:44:11.240Z",
               "external_reference_id": null,
               "verified": false,
               "contact_email": "jane.smith@example.com"
             },
             "relationships": {
               "country": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/country",
                   "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/country"
                 }
               },
               "proofs": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/proofs",
                   "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/proofs"
                 }
               },
               "addresses": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/addresses",
                   "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/addresses"
                 }
               },
               "permanent_documents": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/permanent_documents",
                   "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/permanent_documents"
                 }
               },
               "birth_country": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/relationships/birth_country",
                   "related": "https://staging-api.didww.com/v3/identities/beca16fb-0385-462f-9e2c-0d1918f6c8af/birth_country"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab-item:: *Create a new business identity*

      Use this approach when the emergency requirement allows ``business``
      identities and there is no suitable existing identity to reuse.

      A business identity is typically used when the emergency requirement
      expects a company or organizational customer. Adjust the submitted fields
      according to the requirement returned in
      :ref:`Step 2 <api-examples-register-emergency-calling-service-step2>`.

      Create a new business identity only when
      :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`
      does not force you to reuse an existing approved identity. The request
      should include every field required by the selected emergency requirement
      so that the business record can be validated and then submitted for
      emergency review. This is the usual path when there is no existing
      suitable identity to select in the previous tab.

      .. http:example:: curl

         POST /v3/identities HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "identities",
             "attributes": {
               "company_name": "Example Services UAB",
               "first_name": "Alex",
               "last_name": "Example",
               "phone_number": "37052032100",
               "description": "Emergency registration business identity",
               "identity_type": "business",
               "contact_email": "ops@example.com"
             },
             "relationships": {
               "country": {
                 "data": {
                   "type": "countries",
                   "id": "661d8448-8897-4765-acda-00cc1740148d"
                 }
               }
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112",
             "type": "identities",
             "attributes": {
               "first_name": "Alex",
               "last_name": "Example",
               "phone_number": "37052032100",
               "id_number": null,
               "birth_date": null,
               "company_name": "Example Services UAB",
               "company_reg_number": null,
               "vat_id": null,
               "description": "Emergency registration business identity",
               "personal_tax_id": null,
               "identity_type": "business",
               "created_at": "2026-04-21T09:50:38.639Z",
               "external_reference_id": null,
               "verified": false,
               "contact_email": "ops@example.com"
             },
             "relationships": {
               "country": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/relationships/country",
                   "related": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/country"
                 }
               },
               "proofs": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/relationships/proofs",
                   "related": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/proofs"
                 }
               },
               "addresses": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/relationships/addresses",
                   "related": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/addresses"
                 }
               },
               "permanent_documents": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/relationships/permanent_documents",
                   "related": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/permanent_documents"
                 }
               },
               "birth_country": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/relationships/birth_country",
                   "related": "https://staging-api.didww.com/v3/identities/e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112/birth_country"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step4:

Step 4: Select or Create an Address
===================================

Next, you need an address linked to the selected identity from
:ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`.

If you already have a suitable address on file, you can select and reuse it.
If not, create a new address that matches the emergency requirement.

The address submitted later for emergency verification must belong to the same
identity chosen in :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`.
This is especially important when the DID already has end user registration,
because emergency verification must stay on the same customer identity and use
an address linked to that identity.

Use the result from :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`
and the identity selected in :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`
to decide which address path applies:

- if the DID has both ``identity`` and ``address_verification``, select an address
  linked to that same verified identity
- if the DID has only ``identity`` and no ``address_verification``, you may reuse
  an address linked to the selected identity or create a new one
- if the DID had no linked identity in
  :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`, select
  or create an address for the identity you chose in
  :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`

Use the emergency requirement to check the address scope:

- if ``address_area_level`` is ``country``, the address must be in the same country
- if ``address_area_level`` is ``area`` or ``city``, the address must match the DID locality more precisely
- if ``address_mandatory_fields`` contains additional fields, those values must be present in the address record

From this step, save ``address.id``. You will use it for validation in
:ref:`Step 5 <api-examples-register-emergency-calling-service-step5>` and for the
emergency verification request in
:ref:`Step 6 <api-examples-register-emergency-calling-service-step6>`.

For more information, see :doc:`Create Addresses <../2026-04-16/regulation-resources/addresses/create-address>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Select an existing address*

      Use this approach first when you already have an address on file that matches
      the emergency requirement and is linked to the correct identity.

      If the selected DID already has end user registration, review the addresses
      linked to that same verified identity first and reuse a matching one.

      If the DID only has a porting identity, you may still reuse an existing
      address linked to the identity chosen in
      :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`,
      but you are not forced to keep the original porting identity or address.

      Review the returned addresses and select one that:

      - is linked to the identity chosen in
        :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`
      - matches the required country, area, or city scope
      - already contains any mandatory address fields required by the emergency requirement

      In practice, this request is useful when your application wants to reuse
      an existing customer address instead of creating another copy of the same
      location data, while still making sure the address stays on the identity
      that will be submitted for emergency verification.

      .. http:example:: curl

         GET /v3/addresses?filter[identity.id]=beca16fb-0385-462f-9e2c-0d1918f6c8af&filter[country.id]=661d8448-8897-4765-acda-00cc1740148d HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": [
             {
               "id": "a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91",
               "type": "addresses",
               "attributes": {
                 "city_name": "Vilnius",
                 "postal_code": "01100",
                 "address": "20 Example Street",
                 "description": "Emergency service address",
                 "created_at": "2026-04-21T08:02:22.720Z",
                 "verified": false,
                 "external_reference_id": null
               },
               "relationships": {
                 "identity": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/relationships/identity",
                     "related": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/identity"
                   }
                 },
                 "country": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/relationships/country",
                     "related": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/country"
                   }
                 },
                 "proofs": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/relationships/proofs",
                     "related": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/proofs"
                   }
                 },
                 "area": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/relationships/area",
                     "related": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/area"
                   }
                 },
                 "city": {
                   "links": {
                     "self": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/relationships/city",
                     "related": "https://staging-api.didww.com/v3/addresses/a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91/city"
                   }
                 }
               }
             }
           ],
           "meta": {
             "total_records": 1,
             "api_version": "2026-04-16"
           },
           "links": {
             "first": "https://staging-api.didww.com/v3/addresses?filter%5Bidentity.id%5D=beca16fb-0385-462f-9e2c-0d1918f6c8af&filter%5Bcountry.id%5D=661d8448-8897-4765-acda-00cc1740148d&page%5Bnumber%5D=1&page%5Bsize%5D=50",
             "last": "https://staging-api.didww.com/v3/addresses?filter%5Bidentity.id%5D=beca16fb-0385-462f-9e2c-0d1918f6c8af&filter%5Bcountry.id%5D=661d8448-8897-4765-acda-00cc1740148d&page%5Bnumber%5D=1&page%5Bsize%5D=50"
           }
         }

   .. tab-item:: *Create a new address*

      Use this approach when there is no existing address on file that matches the
      emergency requirement.

      The new address must be linked to the identity selected in
      :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>` and
      should contain all mandatory address fields required by the emergency
      requirement.

      This is the typical path when no saved address matches the required
      country, area, or city scope returned by the emergency requirement.

      Create a new address only for the identity that will be used in the final
      emergency verification request. If
      :ref:`Step 1 <api-examples-register-emergency-calling-service-step1>`
      showed end user registration, this means the new address must still be
      linked to that same approved identity.

      Creating the address at this stage makes sure the final emergency
      verification uses location data that already matches both the selected
      identity and the emergency requirement.

      .. http:example:: curl

         POST /v3/addresses HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "addresses",
             "attributes": {
               "address": "10 Example Street",
               "city_name": "Sample City",
               "postal_code": "76511",
               "description": "Emergency service address"
             },
             "relationships": {
               "identity": {
                 "data": {
                   "type": "identities",
                   "id": "e4b5f0b1-6543-4a9e-85cd-2ac0e7d0a112"
                 }
               },
               "country": {
                 "data": {
                   "type": "countries",
                   "id": "661d8448-8897-4765-acda-00cc1740148d"
                 }
               }
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3",
             "type": "addresses",
             "attributes": {
               "address": "10 Example Street",
               "city_name": "Vilnius",
               "postal_code": "76511",
               "description": "Emergency service address",
               "created_at": "2026-04-21T08:02:22.720Z",
               "verified": false,
               "external_reference_id": null
             },
             "relationships": {
               "identity": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/relationships/identity",
                   "related": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/identity"
                 }
               },
               "country": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/relationships/country",
                   "related": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/country"
                 }
               },
               "proofs": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/relationships/proofs",
                   "related": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/proofs"
                 }
               },
               "area": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/relationships/area",
                   "related": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/area"
                 }
               },
               "city": {
                 "links": {
                   "self": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/relationships/city",
                   "related": "https://staging-api.didww.com/v3/addresses/f2b7f0f4-2e98-4cef-a2b4-5661c3887fb3/city"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step5:

Step 5: Validate the Identity and Address
=========================================

Validate the identity and address against the selected emergency requirement
**before** starting the emergency verification.

This validation confirms that the selected customer data meets the emergency
registration conditions and helps detect missing or invalid data early, such
as:

- the wrong identity type
- missing identity or address fields
- a country mismatch
- an address that does not satisfy the required city or area scope

This validation step does not create the emergency service yet. It is a
pre-check that confirms the selected identity and address are acceptable before
the emergency verification is submitted for review.

The validation checks that:

- all mandatory identity fields are present
- the identity type matches the emergency requirement
- the address meets the geographic restrictions defined by the requirement

If the validation succeeds, the identity and address can be safely submitted in
:ref:`Step 6 <api-examples-register-emergency-calling-service-step6>`.

Use the IDs collected in the previous steps:

- ``emergency_requirement.id`` from :ref:`Step 2 <api-examples-register-emergency-calling-service-step2>`
- ``identity.id`` from :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`
- ``address.id`` from :ref:`Step 4 <api-examples-register-emergency-calling-service-step4>`

If validation fails, correct the identity or address before continuing. If it
succeeds, proceed to emergency verification submission.

For more information, see :doc:`Emergency Requirement Validations <../2026-04-16/emergency-resources/emergency-requirements/emergency-requirement-validations>` endpoint documentation.

.. http:example:: curl

   POST /v3/emergency_requirement_validations HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json

   {
     "data": {
       "type": "emergency_requirement_validations",
       "relationships": {
         "emergency_requirement": {
           "data": {
            "type": "emergency_requirements",
            "id": "f788cef0-b278-4f21-a870-23950e67d0a1"
          }
        },
        "identity": {
          "data": {
            "type": "identities",
            "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
          }
        },
        "address": {
          "data": {
            "type": "addresses",
            "id": "a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91"
          }
        }
      }
     }
   }

   HTTP/1.1 201 Created
   Content-Type: application/vnd.api+json

   {
     "data": {
       "id": "f788cef0-b278-4f21-a870-23950e67d0a1",
       "type": "emergency_requirement_validations"
     },
     "meta": {
     "api_version": "2026-04-16"
     }
   }

.. note::

   If the validation request is rejected, review the error details and correct
   the identity or address before continuing to
   :ref:`Step 6 <api-examples-register-emergency-calling-service-step6>`.

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step6:

Step 6: Create a New Emergency Verification
===========================================

Once the identity and address are valid, submit an emergency verification for the DIDs.

.. note::

   This step should be performed only after the identity and address have been
   successfully validated in :ref:`Step 5 <api-examples-register-emergency-calling-service-step5>`.

For **New Calling Service** send ``address`` and one or more ``dids``.

When this request succeeds, a new Emergency Calling Service is created automatically
and linked to the verification.

This is the step that actually starts the emergency registration review. The
request moves the selected data into the emergency verification workflow, where
it can later be approved or rejected by the DIDWW Emergency Team.

The emergency verification evaluates:

- the selected DIDs
- the submitted address
- the identity linked to that address

.. note::
   A ``callback_url`` and ``callback_method`` can be configured for emergency
   verifications to receive HTTP callbacks when the verification status
   changes. |br|
   Callback events are sent when the verification is **approved** or
   **rejected**. The payload includes the verification ID, resource type
   (``emergency_verifications``), the current status, and a rejection reason when
   applicable.

   See :ref:`Callback configuration <callbacks_details_v34>` for more
   information.

For more information, see :doc:`Create Emergency Verification <../2026-04-16/emergency-resources/emergency-verifications/create-emergency-verification>` endpoint documentation.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Submit a new emergency verification*

      This request starts the review for the selected DIDs by sending the final
      address and DID assignment data to the emergency verification endpoint.

      For New Calling Service, this request creates a new Emergency Calling
      Service automatically. The returned emergency verification becomes the
      record your application can track later in
      :ref:`Step 7 <api-examples-register-emergency-calling-service-step7>`
      until the review is approved or rejected.

      .. http:example:: curl

         POST /v3/emergency_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "emergency_verifications",
             "attributes": {
               "callback_url": "https://example.com/callbacks/emergency",
               "callback_method": "post"
             },
             "relationships": {
               "address": {
                 "data": {
                   "type": "addresses",
                   "id": "a4dcb4e3-1c7f-44ea-a60c-0d6f2a1c7d91"
                 }
               },
               "dids": {
                 "data": [
                   {
                     "type": "dids",
                     "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa"
                   }
                 ]
               }
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03",
             "type": "emergency_verifications",
             "attributes": {
               "reference": "EGZ-696952",
               "status": "pending",
               "reject_reasons": null,
               "reject_comment": null,
               "callback_url": "https://example.com/callbacks/emergency",
               "callback_method": "post",
               "created_at": "2026-04-21T08:10:43.079Z",
               "external_reference_id": null
             },
             "relationships": {
               "address": {
                 "links": {
                   "self": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/relationships/address",
                   "related": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/address"
                 }
               },
               "emergency_calling_service": {
                 "links": {
                   "self": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/relationships/emergency_calling_service",
                   "related": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/emergency_calling_service"
                 }
               },
               "dids": {
                 "links": {
                   "self": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/relationships/dids",
                   "related": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/dids"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

   .. tab-item:: *Identity mismatch with existing registration*

      While submitting the emergency verification, you can receive an
      identity-related error if the selected DID already has end user
      registration on another identity.

      This happens because the submission request does not only check the new
      address you send. It also checks whether the DID is already tied to a
      specific approved customer identity from an earlier compliance flow.
      When those identities do not match, the request is rejected to prevent
      the DID from being reassigned to a different customer identity during
      emergency registration.

      If a DID already has end user registration and that registration is linked
      to a specific identity, emergency verification must use an address that
      belongs to the same identity. If you submit an address from a different
      identity, the request fails and the error tells you which identity must be
      used.

      In that case, go back to :ref:`Step 3 <api-examples-register-emergency-calling-service-step3>`
      and :ref:`Step 4 <api-examples-register-emergency-calling-service-step4>` and
      reuse the identity and address that match the DID's existing end user
      registration.

      .. http:example:: curl

         POST /v3/emergency_verifications HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "emergency_verifications",
             "attributes": {
               "callback_url": "https://example.com/callbacks/emergency",
               "callback_method": "post"
             },
             "relationships": {
               "address": {
                 "data": {
                     "id": "df845b05-bed8-4fef-a9b1-5661c3887fb3",
                     "type": "addresses"
                 }
               },
               "dids": {
                 "data": [
                   {
                     "id": "9f81f2ef-ad6c-402b-97af-06fff514454e",
                     "type": "dids"
                   }
                 ]
               }
             }
           }
         }

         HTTP/1.1 422 Unprocessable Entity
         Content-Type: application/vnd.api+json

         {
           "errors": [
             {
               "title": "can be used only with Identity Business - Example Company Ltd",
               "detail": "dids/9f81f2ef-ad6c-402b-97af-06fff514454e - can be used only with Identity Business - Example Company Ltd",
               "code": "100",
               "source": {
                 "pointer": "/data/relationships/dids/9f81f2ef-ad6c-402b-97af-06fff514454e"
               },
               "status": "422"
             }
           ]
         }

----

.. raw:: html

   <br>

.. _api-examples-register-emergency-calling-service-step7:

Step 7: Monitor Emergency Verification Status
=============================================

After submission, monitor the process until the verification is completed and,
once approved, the resulting Emergency Calling Service reaches its operational
status.

This step is needed because the emergency verification created in
:ref:`Step 6 <api-examples-register-emergency-calling-service-step6>` starts in
review and can change state later. Your application needs the latest status to
know whether emergency registration has completed successfully or whether the
submitted data still requires correction.

Use the emergency verification resource to monitor the review result, and use
the Emergency Calling Service resource to confirm the created service status
after approval.

Once the verification is approved, the associated Emergency Calling Service
can move to ``active`` and emergency routing is enabled for the specified DIDs.

This request is useful even when callbacks are configured, because it lets your
application fetch the latest verification state on demand, for example when
displaying the current emergency registration status in a dashboard or order
details page, instead of waiting for the next callback event.

View emergency verifications
----------------------------

Use ``GET /v3/emergency_verifications/{id}`` to monitor whether the submitted
identity and address have been approved or rejected, and review other request details.

If the verification is rejected, the response includes a rejection reason that
explains what must be corrected before resubmitting.

.. http:example:: curl

   GET /v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03?include=emergency_calling_service,dids HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Accept: application/vnd.api+json

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": {
       "id": "dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03",
       "type": "emergency_verifications",
       "attributes": {
         "external_reference_id": null,
         "reference": "EGZ-696952",
         "status": "approved",
         "reject_reasons": null,
         "reject_comment": null,
         "callback_url": "https://example.com/callbacks/emergency",
         "callback_method": "post",
         "created_at": "2026-04-21T08:10:43.079Z"
       },
       "relationships": {
         "address": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/relationships/address",
             "related": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/address"
           }
         },
         "emergency_calling_service": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/relationships/emergency_calling_service",
             "related": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/emergency_calling_service"
           },
           "data": {
             "type": "emergency_calling_services",
             "id": "2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59"
           }
         },
         "dids": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/relationships/dids",
             "related": "https://api.didww.com/v3/emergency_verifications/dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03/dids"
           },
           "data": [
             {
               "type": "dids",
               "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa"
             }
           ]
         }
       }
     },
     "meta": {
       "api_version": "2026-04-16"
     }
   }

View emergency calling services
-------------------------------

Use ``GET /v3/emergency_calling_services/{id}`` after the verification is
approved to check the details of Emergency Calling Services.

This confirms whether the created service has already moved to an operational
state such as ``active`` and lets your application show the current emergency
service state for the registered DIDs.

.. note:: Once the Emergency Calling Service status becomes ``active``, the emergency-enabled DID can be assigned to an outbound trunk and used for outbound emergency traffic. For an example, see :ref:`Create Outbound Trunk <voice_out_trunks_v34_create_examples>`.

.. http:example:: curl

   GET /v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59?include=emergency_verification,dids HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Accept: application/vnd.api+json

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": {
       "id": "2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59",
       "type": "emergency_calling_services",
       "attributes": {
         "name": "Emergency Service for 37052032113",
         "reference": "SHB-485120",
         "status": "active",
         "activated_at": "2026-04-21T09:02:15.000Z",
         "canceled_at": null,
         "renew_date": "2026-05-21",
         "created_at": "2026-04-21T08:10:43.079Z"
       },
       "relationships": {
         "country": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/relationships/country",
             "related": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/country"
           }
         },
         "did_group_type": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/relationships/did_group_type",
             "related": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/did_group_type"
           }
         },
         "order": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/relationships/order",
             "related": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/order"
           }
         },
         "emergency_requirement": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/relationships/emergency_requirement",
             "related": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/emergency_requirement"
           }
         },
         "emergency_verification": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/relationships/emergency_verification",
             "related": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/emergency_verification"
           },
           "data": {
             "type": "emergency_verifications",
             "id": "dcef19d7-0d81-4cbc-9cf4-9cccf2ba3f03"
           }
         },
         "dids": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/relationships/dids",
             "related": "https://api.didww.com/v3/emergency_calling_services/2ab4b9db-7f16-47ad-a7fe-b23dbfa0bb59/dids"
           },
           "data": [
             {
               "type": "dids",
               "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa"
             }
           ]
         }
       },
       "meta": {
         "setup_price": "0.00",
         "monthly_price": "2.50"
       }
     },
     "meta": {
       "api_version": "2026-04-16"
     }
   }

.. note::

   If the registration is rejected, review the rejection details, correct the
   underlying identity or address data, and submit another
   ``POST /v3/emergency_verifications`` request for the DIDs you want to register.


.. |br| raw:: html

   <br />

.. _api-examples-update-emergency-calling-service:

================================
Update Emergency Calling Service
================================

This example shows how to update an existing Emergency Calling Service
by submitting a new emergency verification in **Existing Calling Service**.

Use this flow when an Emergency Calling Service already exists and its
registered emergency address must be changed without creating a new service.

This update flow is typically used in these situations:

- the existing Emergency Calling Service is in ``changes_required`` because the
  previous emergency verification was rejected and the address must be corrected
  and resubmitted
- the existing Emergency Calling Service is already ``active``, but the
  registered emergency address needs to be changed to a new one
- the existing Emergency Calling Service is still in ``new``, which means the
  service already exists but has not become active yet, so the address can
  still be replaced before activation finishes

To update an existing Emergency Calling Service, follow these steps:

- :ref:`Step 1: Review the Existing Emergency Calling Service <api-examples-update-emergency-calling-service-step1>`
- :ref:`Step 2: Prepare the Replacement Address <api-examples-update-emergency-calling-service-step2>`
- :ref:`Step 3: Submit Emergency Verification in Existing Calling Service <api-examples-update-emergency-calling-service-step3>`
- :ref:`Step 4: Track the Pending Update Until Activation <api-examples-update-emergency-calling-service-step4>`

.. note::

   Removing a DID from an existing Emergency Calling Service is handled through
   the DID resource, not through emergency verification creation.

----

.. raw:: html

   <br>

Before you begin
================

- A DIDWW API key is required to authenticate the requests shown in this guide. Make sure you have an :ref:`API key <api_key>` ready before starting the flow.
- You must already have an existing Emergency Calling Service to update. If you do not have one yet, first follow :ref:`Register Emergency Calling Service <api-examples-register-emergency-calling-service>`.

----

.. raw:: html

   <br>

.. _api-examples-update-emergency-calling-service-step1:

Step 1: Review the Existing Emergency Calling Service
=====================================================

Before the address can be updated, the existing Emergency Calling Service has
to be identified and checked. This is what tells your application whether that
specific service can accept an address change right now and which service rules
the replacement address still has to follow.

Retrieve the existing Emergency Calling Service so you can confirm:

- the existing Emergency Calling Service ``id``
- the current Emergency Calling Service ``status``
- the linked ``emergency_requirement`` that still defines the allowed address scope
- the currently linked emergency verification and DIDs
- the country and DID Group type assigned to that Emergency Calling Service

This step matters because the existing service defines the update context. It
shows which service is being updated, whether the service is currently allowed
to accept an address change, and which country and DID Group type rules the new
address still has to satisfy.

Address changes are allowed only when the Emergency Calling Service is in one
of these statuses:

- ``new``
- ``changes_required``
- ``active``

The update submission request fails with ``422`` if the Emergency Calling
Service is in:

- ``pending_update``
- ``in_process``
- ``canceled``

From this response, save:

- ``emergency_calling_service.id`` for :ref:`Step 4 <api-examples-update-emergency-calling-service-step4>`
- ``emergency_verification.id`` for :ref:`Step 2 <api-examples-update-emergency-calling-service-step2>`, so you can retrieve the current address linked to the service

From the linked ``emergency_requirement``, review the address rules that still
apply to this service, especially ``address_area_level`` and
``address_mandatory_fields``.

For more information, see :doc:`Get Emergency Calling Service <../2026-04-16/emergency-resources/emergency-calling-services/get-emergency-calling-service>`
endpoint documentation and the :doc:`Emergency Calling Service object <../2026-04-16/emergency-resources/emergency-calling-services/emergency-calling-service-object>`.

.. http:example:: curl

   GET /v3/emergency_calling_services?filter[reference]=SHB-485120&include=country,did_group_type,dids,emergency_verification,emergency_requirement HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Accept: application/vnd.api+json

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
       "data": [
           {
               "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
               "type": "emergency_calling_services",
               "attributes": {
                   "name": "E911 Service - New York Office",
                   "reference": "SHB-485120",
                   "status": "active",
                   "activated_at": "2026-01-15T10:30:00.000Z",
                   "canceled_at": null,
                   "renew_date": "2026-07-15",
                   "created_at": "2026-01-10T08:00:00.000Z"
               },
               "relationships": {
                   "country": {
                       "data": {
                           "type": "countries",
                           "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0"
                       }
                   },
                   "did_group_type": {
                       "data": {
                           "type": "did_group_types",
                           "id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
                       }
                   },
                   "emergency_requirement": {
                       "data": {
                           "type": "emergency_requirements",
                           "id": "6da88c80-99ab-42b7-bd10-66dcf53ca278"
                       }
                   },
                   "emergency_verification": {
                       "data": {
                           "type": "emergency_verifications",
                           "id": "d4e5f6a7-b8c9-0123-def0-123456789012"
                       }
                   },
                   "dids": {
                       "data": [
                           {
                               "type": "dids",
                               "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa"
                           }
                       ]
                   }
               },
               "meta": {
                   "setup_price": "0.00",
                   "monthly_price": "2.50"
               }
           }
       ],
       "included": [
           {
               "id": "6da88c80-99ab-42b7-bd10-66dcf53ca278",
               "type": "emergency_requirements",
               "attributes": {
                   "identity_type": "any",
                   "address_area_level": "country",
                   "personal_area_level": "world_wide",
                   "business_area_level": "world_wide",
                   "address_mandatory_fields": [],
                   "personal_mandatory_fields": [],
                   "business_mandatory_fields": [],
                   "estimate_setup_time": "15-17 days",
                   "requirement_restriction_message": "United States Local DID Emergency calling requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n\r\nFor address verification:\r\n* Address in United States (state, city, street, street number, apartment or suite information, zip code)\r\n"
               },
               "meta": {
                   "setup_price": "0.00",
                   "monthly_price": "10.20"
               }
           }
       ],
       "meta": {
           "api_version": "2026-04-16"
       }
   }

.. important::

   When you update an **active** service, the service transitions to ``pending_update``
   while the new verification is reviewed, but emergency routing remains enabled until
   the new verification is approved or rejected.

   During that review period, the existing Emergency Calling Service continues
   to be used with the current address. The replacement address only takes
   effect after the update verification is approved and the service returns to
   ``active``.

----

.. raw:: html

   <br>

.. _api-examples-update-emergency-calling-service-step2:

Step 2: Prepare the Replacement Address
=======================================

The Emergency Calling Service update flow does not change the registered
service address directly. Instead, it prepares the address record that will be
submitted for review in :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.

At this point, your application has to decide whether the current address can
still be edited or whether a new address must be created instead.

- edit the current address only if that address has not yet been approved or
  used in emergency verification
- create a new address if the current address has already been approved or used,
  because that address should no longer be modified in place

In both cases, the replacement address still has to satisfy the same
``emergency_requirement`` already linked to the existing Emergency Calling
Service. Review that requirement from
:ref:`Step 1 <api-examples-update-emergency-calling-service-step1>`,
especially:

- ``address_area_level``
- ``address_mandatory_fields``

For more information, see :doc:`Create Addresses <../2026-04-16/regulation-resources/addresses/create-address>`
endpoint documentation and the :doc:`Address object <../2026-04-16/regulation-resources/addresses/address-object>`.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Edit the current address*

      Use this path only when the current address has not yet been approved or
      used in emergency verification.

      This path exists for the case where the address record can still be
      corrected in place. In that situation, your application does not need to
      create another address record. It only needs to identify the existing
      address, update its address fields, and then submit that corrected
      address in :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.

      First retrieve the current emergency verification to get the
      ``address.id`` currently linked to the Emergency Calling Service. That
      lookup is needed because the update flow starts from the Emergency
      Calling Service and emergency verification, not from a previously known
      address ID.

      .. http:example:: curl

         GET /v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012?include=address HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
             "type": "emergency_verifications",
             "attributes": {
               "reference": "SHB-998877",
               "status": "approved",
               "reject_reasons": [],
               "reject_comment": null,
               "callback_url": "https://example.com/callbacks/emergency",
               "callback_method": "post",
               "created_at": "2026-03-23T09:15:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "address": {
                 "data": {
                   "type": "addresses",
                   "id": "46e129f1-deaa-44db-8915-2646de4d4c70"
                 }
               },
               "emergency_calling_service": {
                 "data": {
                   "type": "emergency_calling_services",
                   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                 }
               }
             }
           },
           "included": [
             {
               "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
               "type": "addresses",
               "attributes": {
                 "address": "10 Old Address Street",
                 "city_name": "New York",
                 "postal_code": "10001",
                 "description": "Current emergency address",
                 "created_at": "2026-01-10T08:55:00.000Z",
                 "verified": false,
                 "external_reference_id": null
               }
             }
           ],
           "meta": {
             "api_version": "2026-04-16"
           }
         }

      Then update that address with the corrected address data that should
      replace the current Emergency Calling Service address if the review is
      approved. This keeps the flow on the same address record and prepares the
      exact address version that the API will review in
      :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.

      .. http:example:: curl

         PATCH /v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
             "type": "addresses",
             "attributes": {
               "address": "20 Example Street",
               "city_name": "New York",
               "postal_code": "10002",
               "description": "Updated emergency address"
             }
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
             "type": "addresses",
             "attributes": {
               "address": "20 Example Street",
               "city_name": "New York",
               "postal_code": "10002",
               "description": "Updated emergency address",
               "created_at": "2026-01-10T08:55:00.000Z",
               "verified": false,
               "external_reference_id": null
             },
             "relationships": {
               "identity": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/identity",
                   "related": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/identity"
                 }
               },
               "country": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/country",
                   "related": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/country"
                 }
               },
               "proofs": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/proofs",
                   "related": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/proofs"
                 }
               },
               "area": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/area",
                   "related": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/area"
                 }
               },
               "city": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/city",
                   "related": "https://api.didww.com/v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70/city"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

      From this step, save ``address.id`` for
      :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.

   .. tab-item:: *Create a new address*

      Use this path when the current address has already been approved or
      used in emergency verification and should no longer be changed in place.

      This path exists for the case where the current address record should be
      left unchanged and a replacement address must be prepared separately.
      That usually means the existing address already has compliance history,
      so the safer and correct update path is to create a new address record
      and submit that new record in
      :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.

      First retrieve the current emergency verification to get the current
      ``address.id``. That identifies the address currently used by the
      Emergency Calling Service and gives your application a starting point for
      finding the linked identity and country needed for the new address.

      .. http:example:: curl

         GET /v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012?include=address HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
             "type": "emergency_verifications",
             "attributes": {
               "reference": "SHB-998877",
               "status": "approved",
               "reject_reasons": [],
               "reject_comment": null,
               "callback_url": "https://example.com/callbacks/emergency",
               "callback_method": "post",
               "created_at": "2026-03-23T09:15:00.000Z",
               "external_reference_id": null
             },
             "relationships": {
               "address": {
                 "data": {
                   "type": "addresses",
                   "id": "46e129f1-deaa-44db-8915-2646de4d4c70"
                 }
               },
               "emergency_calling_service": {
                 "data": {
                   "type": "emergency_calling_services",
                   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                 }
               }
             }
           },
           "included": [
             {
               "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
               "type": "addresses",
               "attributes": {
                 "address": "10 Old Address Street",
                 "city_name": "New York",
                 "postal_code": "10001",
                 "description": "Current emergency address",
                 "created_at": "2026-01-10T08:55:00.000Z",
                 "verified": false,
                 "external_reference_id": null
               }
             }
           ],
           "meta": {
             "api_version": "2026-04-16"
           }
         }

      Then retrieve that address to get the linked ``identity.id`` and
      ``country.id`` required for the create request. Those IDs are needed
      because the new address still has to stay linked to the correct identity
      and country context already used by the existing Emergency Calling
      Service.

      .. http:example:: curl

         GET /v3/addresses/46e129f1-deaa-44db-8915-2646de4d4c70?include=identity,country HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Accept: application/vnd.api+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
             "type": "addresses",
             "attributes": {
               "address": "10 Old Address Street",
               "city_name": "New York",
               "postal_code": "10001",
               "description": "Current emergency address",
               "created_at": "2026-01-10T08:55:00.000Z",
               "verified": false,
               "external_reference_id": null
             },
             "relationships": {
               "identity": {
                 "data": {
                   "type": "identities",
                   "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                 }
               },
               "country": {
                 "data": {
                   "type": "countries",
                   "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0"
                 }
               }
             }
           },
           "included": [
             {
               "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
               "type": "identities",
               "attributes": {
                 "identity_type": "business",
                 "company_name": "Example Company Ltd",
                 "first_name": "John",
                 "last_name": "Smith",
                 "phone_number": "15551234567",
                 "created_at": "2026-01-09T07:30:12.546Z",
                 "verified": true,
                 "external_reference_id": null,
                 "contact_email": null
               }
             },
             {
               "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0",
               "type": "countries",
               "attributes": {
                 "name": "United States",
                 "prefix": "1",
                 "iso": "US"
               }
             }
           ],
           "meta": {
             "api_version": "2026-04-16"
           }
         }

      After that, create the new replacement address that will be submitted in
      :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.
      This prepares a separate address record for review without changing the
      existing address that is already tied to the current Emergency Calling
      Service state.

      If the current Emergency Calling Service is already ``active``, submit a
      different address record in the update request. Do not resubmit the same
      address record already used by that service.

      .. http:example:: curl

         POST /v3/addresses HTTP/1.1
         Host: api.didww.com
         Api-Key: [API token]
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "addresses",
             "attributes": {
               "address": "20 Example Street",
               "city_name": "New York",
               "postal_code": "10002",
               "description": "Updated emergency address"
             },
             "relationships": {
               "identity": {
                 "data": {
                   "type": "identities",
                   "id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
                 }
               },
               "country": {
                 "data": {
                   "type": "countries",
                   "id": "72f22218-ab1f-4933-a74d-a6467f3f6cb0"
                 }
               }
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/vnd.api+json

         {
           "data": {
             "id": "f13240d5-d3cc-4c05-a529-fb63a0027118",
             "type": "addresses",
             "attributes": {
               "address": "20 Example Street",
               "city_name": "New York",
               "postal_code": "10002",
               "description": "Updated emergency address",
               "created_at": "2026-03-23T09:02:11.000Z",
               "verified": false,
               "external_reference_id": null
             },
             "relationships": {
               "identity": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/relationships/identity",
                   "related": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/identity"
                 }
               },
               "country": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/relationships/country",
                   "related": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/country"
                 }
               },
               "proofs": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/relationships/proofs",
                   "related": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/proofs"
                 }
               },
               "area": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/relationships/area",
                   "related": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/area"
                 }
               },
               "city": {
                 "links": {
                   "self": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/relationships/city",
                   "related": "https://api.didww.com/v3/addresses/f13240d5-d3cc-4c05-a529-fb63a0027118/city"
                 }
               }
             }
           },
           "meta": {
             "api_version": "2026-04-16"
           }
         }

      From this step, save the new ``address.id`` for
      :ref:`Step 3 <api-examples-update-emergency-calling-service-step3>`.

----

.. raw:: html

   <br>

.. _api-examples-update-emergency-calling-service-step3:

Step 3: Submit Emergency Verification in Existing Calling Service
=================================================================

The existing Emergency Calling Service is updated by creating a new emergency
verification in Existing Calling Service. This is the request that starts
the review of the replacement address for that already existing service.

Submit a new emergency verification with ``address`` and ``emergency_calling_service``.

This step is what actually starts the Emergency Calling Service update review.
The request tells the API which existing Emergency Calling Service should be
updated and which new address should replace the current service address if the
review is approved.

While submitting the update, you can still receive an error if the replacement
address is linked to the wrong identity, does not satisfy the Emergency Calling
Service requirement, or if the Emergency Calling Service is currently in a
status that does not allow updates. Those checks happen at submission time
because the API must confirm that the replacement address is valid for the
specific existing service being changed.

.. note::
   A ``callback_url`` and ``callback_method`` can be configured for emergency
   verifications to receive HTTP callbacks when the verification status
   changes. |br|
   Callback events are sent when the verification is **approved** or
   **rejected**. The payload includes the verification ID, resource type
   (``emergency_verifications``), the current status, and a rejection reason when
   applicable.

   See :ref:`Callback configuration <callbacks_details_v34>` for more
   information.

For more information, see :doc:`Create Emergency Verification <../2026-04-16/emergency-resources/emergency-verifications/create-emergency-verification>`.

.. http:example:: curl

   POST /v3/emergency_verifications HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json

   {
     "data": {
       "type": "emergency_verifications",
       "attributes": {
         "callback_url": "https://example.com/callbacks/emergency",
         "callback_method": "post"
       },
       "relationships": {
         "address": {
           "data": {
             "type": "addresses",
             "id": "f13240d5-d3cc-4c05-a529-fb63a0027118"
           }
         },
         "emergency_calling_service": {
           "data": {
             "type": "emergency_calling_services",
             "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
           }
         }
       }
     }
   }

   HTTP/1.1 201 Created
   Content-Type: application/vnd.api+json

   {
     "data": {
       "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
       "type": "emergency_verifications",
       "attributes": {
         "reference": "SHB-998877",
         "status": "pending",
         "reject_reasons": [],
         "reject_comment": null,
         "callback_url": "https://example.com/callbacks/emergency",
         "callback_method": "post",
         "created_at": "2026-03-23T09:15:00.000Z",
         "external_reference_id": null
       },
       "relationships": {
         "address": {
           "data": {
             "type": "addresses",
             "id": "f13240d5-d3cc-4c05-a529-fb63a0027118"
           }
         },
         "emergency_calling_service": {
           "data": {
             "type": "emergency_calling_services",
             "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
           }
         },
         "dids": {
           "data": []
         }
       }
     },
     "meta": {
       "api_version": "2026-04-16"
     }
   }

----

.. raw:: html

   <br>

.. _api-examples-update-emergency-calling-service-step4:

Step 4: Track the Pending Update Until Activation
=================================================

The update is not applied immediately after submission. It is reviewed
asynchronously, so your application needs to track both the new emergency
verification and the existing Emergency Calling Service until the review is
finished and the service returns to its usable state.

After the update request is submitted:

1. the new emergency verification status becomes ``pending``
2. the existing Emergency Calling Service status becomes ``pending_update``
3. once the update verification is approved, the Emergency Calling Service becomes ``active`` again with the updated address

Use these endpoints to track the change:

- :doc:`Get Emergency Verification <../2026-04-16/emergency-resources/emergency-verifications/get-emergency-verification>`
- :doc:`Get Emergency Calling Service <../2026-04-16/emergency-resources/emergency-calling-services/get-emergency-calling-service>`

Get emergency verification
--------------------------

Use the emergency verification resource first to see whether the address update was
approved or rejected.

.. http:example:: curl

   GET /v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012?include=emergency_calling_service HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Accept: application/vnd.api+json

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": {
       "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
       "type": "emergency_verifications",
       "attributes": {
         "reference": "SHB-998877",
         "status": "approved",
         "reject_reasons": [],
         "reject_comment": null,
         "callback_url": "https://example.com/callbacks/emergency",
         "callback_method": "post",
         "created_at": "2026-03-23T09:15:00.000Z",
         "external_reference_id": null
       },
       "relationships": {
         "address": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012/relationships/address",
             "related": "https://api.didww.com/v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012/address"
           }
         },
         "emergency_calling_service": {
           "data": {
             "type": "emergency_calling_services",
             "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
           },
           "links": {
             "self": "https://api.didww.com/v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012/relationships/emergency_calling_service",
             "related": "https://api.didww.com/v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012/emergency_calling_service"
           }
         },
         "dids": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012/relationships/dids",
             "related": "https://api.didww.com/v3/emergency_verifications/d4e5f6a7-b8c9-0123-def0-123456789012/dids"
           }
         }
       }
     },
     "included": [
       {
         "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
         "type": "emergency_calling_services",
         "attributes": {
           "name": "E911 Service - New York Office",
           "reference": "SHB-485120",
           "status": "active",
           "activated_at": "2026-04-03T12:40:00.000Z",
           "canceled_at": null,
           "renew_date": "2026-07-15",
           "created_at": "2026-01-10T08:00:00.000Z"
         },
         "meta": {
           "setup_price": "0.00",
           "monthly_price": "2.50"
         }
       }
     ],
     "meta": {
       "api_version": "2026-04-16"
     }
   }

Get the emergency calling service
---------------------------------

After the emergency verification is approved, retrieve the Emergency Calling
Service to confirm it has
returned from ``pending_update`` to ``active`` with the updated address in
effect.

Once the Emergency Calling Service status becomes ``active``, the
emergency-enabled DID can be assigned to an outbound trunk and used for
outbound emergency traffic. For an example, see
:doc:`Create Outbound Trunk <../2026-04-16/inventory-resources/voice-out-trunks/create-voice-out-trunk>`.

.. http:example:: curl

   GET /v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890?include=emergency_verification,dids HTTP/1.1
   Host: api.didww.com
   Api-Key: [API token]
   Accept: application/vnd.api+json

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": {
       "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "type": "emergency_calling_services",
       "attributes": {
         "name": "E911 Service - New York Office",
         "reference": "SHB-485120",
         "status": "active",
         "activated_at": "2026-04-03T12:40:00.000Z",
         "canceled_at": null,
         "renew_date": "2026-07-15",
         "created_at": "2026-01-10T08:00:00.000Z"
       },
       "relationships": {
         "country": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/country",
             "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/country"
           }
         },
         "did_group_type": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/did_group_type",
             "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/did_group_type"
           }
         },
         "order": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/order",
             "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/order"
           }
         },
         "emergency_requirement": {
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_requirement",
             "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_requirement"
           }
         },
         "emergency_verification": {
           "data": {
             "type": "emergency_verifications",
             "id": "d4e5f6a7-b8c9-0123-def0-123456789012"
           },
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/emergency_verification",
             "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/emergency_verification"
           }
         },
         "dids": {
           "data": [
             {
               "type": "dids",
               "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa"
             }
           ],
           "links": {
             "self": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships/dids",
             "related": "https://api.didww.com/v3/emergency_calling_services/a1b2c3d4-e5f6-7890-abcd-ef1234567890/dids"
           }
         }
       },
       "meta": {
         "setup_price": "0.00",
         "monthly_price": "2.50"
       }
     },
     "included": [
       {
         "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
         "type": "emergency_verifications",
         "attributes": {
           "reference": "SHB-998877",
           "status": "approved",
           "reject_reasons": [],
           "reject_comment": null,
           "callback_url": "https://example.com/callbacks/emergency",
           "callback_method": "post",
           "created_at": "2026-03-23T09:15:00.000Z",
           "external_reference_id": null
         }
       },
       {
         "id": "cc4c423f-68b5-4e1a-878c-2328eb24f3fa",
         "type": "dids",
         "attributes": {
           "number": "12125550100"
         }
       }
     ],
     "meta": {
       "api_version": "2026-04-16"
     }
   }

.. note::

   If the updated verification is rejected, review ``reject_reasons`` and
   ``reject_comment``, correct the address data, and submit another
   ``POST /v3/emergency_verifications`` request in Existing Calling Service.


.. _api_error_objects:

Error Objects
==============

The DIDWW API returns error objects in JSONAPI format. Each error includes a title, detail, code, and status to help you diagnose issues.

----

.. raw:: html

   <br>

.. _api_validation_error_object:

Validation Error Object
-----------------------

A validation error occurs when a request contains invalid or missing data.

.. list-table::
   :header-rows: 1
   :widths: 20 15 10 55

   * - **Name**
     - **Type**
     - **Nullable**
     - **Description**
   * - ``title``
     - string
     - False
     - Short error description.
   * - ``detail``
     - string
     - False
     - Detailed error description.
   * - ``code``
     - string
     - False
     - Always returns ``100``.
   * - ``pointer``
     - string
     - False
     - Path to the error attribute or relationship in the request payload.

.. _api_cant_be_blank:

Can't Be Blank Error Object
---------------------------

This validation error occurs when a required attribute is missing from the request.

.. list-table::
   :header-rows: 1
   :widths: 20 15 10 55

   * - **Name**
     - **Type**
     - **Nullable**
     - **Description**
   * - ``title``
     - string
     - False
     - Always returns ``can’t be blank``.
   * - ``detail``
     - string
     - False
     - Field-specific message describing which required attribute is missing.
   * - ``code``
     - string
     - False
     - Always returns ``100``.
   * - ``pointer``
     - string
     - False
     - Path to the missing attribute in the request payload.
   * - ``status``
     - string
     - False
     - HTTP status code ``422``.

----

.. raw:: html

   <br>

.. _api_bad_request:

Bad Request Error Object
------------------------

This error occurs when the request contains an invalid or not allowed parameter or attribute.

.. list-table::
   :header-rows: 1
   :widths: 20 15 10 55

   * - **Name**
     - **Type**
     - **Nullable**
     - **Description**
   * - ``title``
     - string
     - False
     - Short error description, for example ``Param not allowed``.
   * - ``detail``
     - string
     - False
     - Detailed message describing which parameter or attribute is not allowed.
   * - ``code``
     - string
     - False
     - Error-specific code, for example ``105`` for a parameter that is not allowed.
   * - ``status``
     - string
     - False
     - HTTP status code ``400``.

----

.. raw:: html

   <br>

.. _api_not_found:

Not Found Error Object
-----------------------

This error occurs when the requested resource cannot be found.

.. list-table::
   :header-rows: 1
   :widths: 20 15 10 55

   * - **Name**
     - **Type**
     - **Nullable**
     - **Description**
   * - ``title``
     - string
     - False
     - Record not found.
   * - ``detail``
     - string
     - False
     - The record identified by ``{id}`` could not be found.
   * - ``code``
     - string
     - False
     - Always returns ``404``.
   * - ``status``
     - string
     - False
     - HTTP status code ``404``.

----

.. raw:: html

   <br>

.. _api_insufficient_balance_error_object:

Insufficient Balance Error Object
---------------------------------

This error occurs when your account balance is too low to complete the request.

.. list-table::
   :header-rows: 1
   :widths: 20 15 10 55

   * - **Name**
     - **Type**
     - **Nullable**
     - **Description**
   * - ``title``
     - string
     - False
     - Insufficient balance.
   * - ``detail``
     - string
     - False
     - Insufficient balance.
   * - ``code``
     - string
     - False
     - HTTP status code or error code returned by the API, for example ``400``.
   * - ``status``
     - string
     - False
     - HTTP status code ``400``.
   * - ``meta.total_cost``
     - string
     - False
     - Total cost of the current order only.
   * - ``meta.available_balance``
     - string
     - False
     - Customer balance including credit at the time of the check.

Example
^^^^^^^

.. code-block:: json

   {
     "errors": [
       {
         "title": "Insufficient balance",
         "detail": "Insufficient balance",
         "code": "400",
         "status": "400",
         "meta": {
           "total_cost": "5.67",
           "available_balance": "1.5"
         }
       }
     ]
   }

----

.. raw:: html

   <br>

.. _conflict_v1:

Conflict Error Object
----------------------

This error occurs when a request conflicts with the current state of the resource (for example, when trying to delete a resource that has dependencies).

.. list-table::
   :header-rows: 1
   :widths: 20 15 10 55

   * - **Name**
     - **Type**
     - **Nullable**
     - **Description**
   * - ``title``
     - string
     - False
     - Conflict.
   * - ``detail``
     - string
     - False
     - Resource-specific message describing the conflict.
   * - ``code``
     - string
     - False
     - Always returns ``409``.
   * - ``status``
     - string
     - False
     - HTTP status code ``409``.



.. _api_filters:

Filters
--------

Filtering allows you to narrow API results using specific conditions. You can filter resources by one or more attributes using query parameters that start with ``filter``.

This feature supports both simple and complex queries, including combining multiple conditions and using arrays.

.. important::

   Filters are supported on any endpoint that responds with a resource collection.

----

.. raw:: html

   <br>

Filter by a single attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use a single filter parameter to retrieve resources matching a specific value.

In this example, cities are filtered by their ``country.id`` and returns only cities within the specified country:

.. http:example:: curl

   GET /v3/cities?filter[country.id]=72f22218-ab1f-4933-a74d-a6467f3f6cb0 HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Filter by multiple attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can combine multiple filter parameters to refine results further.

In this example, cities are filtered by both ``country.id`` and ``region.id``, and returns only cities that match both conditions:

.. http:example:: curl

   GET /v3/cities?filter[country.id]=72f22218-ab1f-4933-a74d-a6467f3f6cb0&filter[region.id]=0800cac6-a0eb-4d58-8284-e5207b65a91b HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Filter by arrays
^^^^^^^^^^^^^^^^^^^^^^^^^

You can use arrays in filters by separating values with commas.

For example, to filter DIDs that support specified features such as voice, voice_out, t38, sms, sms_out:

.. code-block::

   filter[features]=voice,voice_out,t38,sms,sms_out

.. important::

   Do **not** provide the same filter multiple times (e.g., ``filter[features]=voice&filter[features]=sms``). Instead, use a single filter with comma-separated values.



.. _api_headers:

Headers
-------

API requests and responses must use specific headers to comply with the JSON API specification.
These headers define the content type, accepted formats, and authentication requirements.

----

.. raw:: html

   <br>

Client responsibilities
^^^^^^^^^^^^^^^^^^^^^^^

Clients must include the following headers in requests:

* ``Content-Type: application/vnd.api+json`` - Required for all requests that send JSON API data. Do **not** include media type parameters.

If these headers are not correctly set, the server may reject the request.

----

.. raw:: html

   <br>

Server responsibilities
^^^^^^^^^^^^^^^^^^^^^^^

Servers must include the following headers in responses:

* ``Content-Type: application/vnd.api+json`` - All responses containing JSON API data must use this header without media type parameters.

Servers return the following errors if headers are invalid:

* **415 Unsupported Media Type** – Returned if the request contains a ``Content-Type`` header with invalid parameters.
* **406 Not Acceptable** – Returned if the request’s ``Accept`` header specifies JSON API but modifies it with parameters.

Refer to the `JSON API specification <https://jsonapi.org/format/#content-negotiation>`_ for detailed content negotiation rules.

----

.. raw:: html

   <br>

Required headers
^^^^^^^^^^^^^^^^

The table below lists the required headers for all API requests:

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - **Header**
     - **Optional**
     - **Description**
   * - ``Accept``
     - No
     - Must be ``application/vnd.api+json``.
   * - ``Content-Type``
     - No
     - Must be ``application/vnd.api+json``.
   * - ``Api-Key``
     - No
     - :ref:`Authorization Header <api_key>` used for authentication.

.. _api_includes:

Inclusion of Related Resources
------------------------------

The ``include`` parameter allows you to retrieve related resources in a single request.
This is also known as **side-loading** and reduces the need for multiple API calls by returning related objects alongside the primary resource.

The response includes a top-level ``relationships`` object containing the related data.

.. note::

   Using ``include`` reduces the number of requests needed to fetch related data and improves performance when working with linked resources.

----

.. raw:: html

   <br>

Include a single related resource
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can include a single related resource by specifying it in the ``include`` parameter.

In this example, each DID record includes its associated ``voice_in_trunk`` resource.
This allows you to retrieve additional details about related resources without sending a separate request:

.. http:example:: curl

   GET /v3/dids?include=voice_in_trunk HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Include multiple related resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can include multiple related resources by separating them with commas.

In this example, the request includes the DID's ``voice_in_trunk`` resource together with the related ``voice_in_trunk_group`` in a single request.

.. http:example:: curl

   GET /v3/dids?include=voice_in_trunk.voice_in_trunk_group HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Include nested related resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can also include relationships of already-included objects.

In this example, the request includes ``voice_in_trunk`` and its related ``voice_in_trunk_group``:

.. http:example:: curl

   GET /v3/dids?include=voice_in_trunk,voice_in_trunk_group HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json



Specification
=============

Use the specification section to learn how to work with the DIDWW API. Choose a topic to understand how to sort data, paginate results, filter resources, include related data, set headers, manage relationships, or handle errors.

.. important::

   All API request text is case-sensitive. Do not include spaces or white-space characters in parameter names or values.

.. grid:: 1 1 1 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`sort-asc` **Sorting**
      :link: sorting
      :link-type: doc

      Learn how to sort API results by one or more fields, use relationship attributes, and apply ascending or descending order.

   .. grid-item-card:: :octicon:`list-unordered` **Pagination**
      :link: pagination
      :link-type: doc

      Learn how to use page size and page number parameters to navigate large datasets and retrieve results efficiently.

   .. grid-item-card:: :octicon:`filter` **Filtering**
      :link: filtering
      :link-type: doc

      Learn how to filter API results using single or multiple conditions, including arrays, to create precise and complex queries.

   .. grid-item-card:: :octicon:`sliders` **Sparse Fieldsets**
      :link: sparse-fieldsets
      :link-type: doc

      Learn how to request a partial response by selecting specific attributes with the ``fields`` parameter to avoid over-fetching.

   .. grid-item-card:: :octicon:`repo-push` **Inclusion of Related Resources**
      :link: includes
      :link-type: doc

      Learn how to use the include parameter to retrieve related resources in a single API request and reduce multiple queries.

   .. grid-item-card:: :octicon:`file` **Headers**
      :link: headers
      :link-type: doc

      Learn about required API headers, including Content-Type, Accept, and authentication headers, for valid requests and responses.

   .. grid-item-card:: :octicon:`git-merge` **Relationships**
      :link: relationships
      :link-type: doc

      Learn how to manage resource relationships using ``PATCH`` to assign, update, or remove.

   .. grid-item-card:: :octicon:`alert` **Error Objects**
      :link: errors/index
      :link-type: doc

      Learn about JSONAPI error objects, including structure, attributes, and common error types.

.. toctree:: 
  :maxdepth: 2
  :hidden:
  
  sorting.rst
  pagination.rst
  filtering.rst
  sparse-fieldsets.rst
  includes.rst
  headers.rst
  relationships.rst
  errors/index.rst

.. raw:: html

    <style>

        /* Make sure the parent container has a relative position if needed */
    .section-container {
      position: relative;
    }

    /* Light mode: show the SVG as a background element */
    html.light .styles_waves__tcfLl {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;    /* Adjust width as necessary */
      height: auto;   /* If needed you can set a fixed height */
      z-index: -1;    /* Place it behind all other content */
      pointer-events: none; /* Ensure it won't capture mouse events */
    }

    /* Dark mode: hide the SVG background */
    html.dark .styles_waves__tcfLl {
      display: none;
    }

        .styles_title__pmgeW {
            font-size: 64px;
            line-height: 76.8px;
            color: #023f7f
        }

      :root {
        /* LIGHT THEME */
        --sd-color-primary: #005fcc;
        --sd-color-card-background: var(--sd-color-card-background);
        --sd-color-card-text: #1e1e1e;
        --sd-color-card-border: #d1d5db;
        /* Shadow variable removed from use */

        --sy-c-border: #d1d5db;
        --sy-c-bold: #374151;
        --gray-1: #e5e7eb;
        --sd-gutter-x: 1rem;
        --sd-gutter-y: 1rem;
        --page-background: #ffffff;
      }

      [data-theme="dark"],
      html.dark {
        /* DARK THEME */
        --sd-color-card-background: #111111;
        --sd-color-card-text: #f9f9f9;
        /* No shadow is applied */

        --sy-c-border: #4b5563;
        --sy-c-bold: #fff;
        --page-background: #000000;
      }

      html, body {
        background-color: var(--page-background);
        color: var(--sd-color-card-text);
        transition: background-color 0.3s ease, color 0.3s ease;
      }

      /* This style mirrors your .sd-card and .sd-text-center rules without any box-shadow.
         It uses the theme colors and spacing, and includes a small hover scale effect */
      .surface {
        background-color: var(--sd-color-card-background);
        color: var(--sd-color-card-text);
        border: 1px solid var(--sd-color-card-border);
        border-radius: 15px;
        padding: var(--sd-gutter-y) var(--sd-gutter-x);
        transition: background-color 0.3s ease, color 0.3s ease, transform 0.15s ease-in-out;
        width: 100%;
        box-sizing: border-box;
      }

      .surface:hover {
        transform: scale(1.02);
      }

      /* Optional grid layout to display items in a row */
      .surface-grid {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: var(--sd-gutter-x);
        width: 100%;
      }

      @media (max-width: 991.98px) {
        .surface-grid {
          grid-template-columns: 1fr;
        }
      }

        /* Responsive Columns: Four */
    @media (min-width: 1728px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1532px) and (max-width: 1727.98px),
           (min-width: 992px) and (max-width: 1127.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 20rem;
      }
    }

    @media (min-width: 1128px) and (max-width: 1531.98px) {
      .sd-row-cols-lg-3 > * {
        min-width: 24rem;
      }
    }

    @media (min-width: 768px) and (max-width: 991.98px),
           (min-width: 576px) and (max-width: 767.98px),
           (max-width: 575.98px) {
      .sd-row-cols-md-3 > *,
      .sd-row-cols-sm-3 > * {
        min-width: 100%;
      }
    }

    .sd-card-body {
        -ms-flex: 1 1 auto;
        flex: 1 1 auto;
        padding: 2rem 2rem 2rem 2rem;
    }

    .. .sd-row {
        margin-top: calc(var(--sd-gutter-y) * 3);
    }

    </style>

.. _api_sorting:

Sorting
--------

You can sort API results by one or more fields using the ``sort`` parameter. Separate multiple fields with commas.

If no sorting option is specified, results are sorted by their ID (for example, country ID, order ID, or CDR ID) in ascending order.

.. note::

   Sorting applies to any endpoint that returns a resource collection as primary data, regardless of the request type.

----

.. raw:: html

   <br>

Sorting DIDs by expiration date
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can retrieve a list of DIDs sorted by their ``expires_at`` attribute in ascending order (earliest expiration date first). Use this to view DIDs based on their expiration sequence and prioritize those that are expiring soon.

.. http:example:: curl

   GET /v3/dids?sort=expires_at HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Sorting by related resource attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can sort results based on attributes of related resources using dot notation.
For example, sorting DIDs by ``did_group.area_name`` organizes them according to their associated area name.

This is useful for grouping DIDs by their geographic or organizational classification.

.. http:example:: curl

   GET /v3/dids?sort=did_group.area_name HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Sorting by multiple fields
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can sort results by multiple fields, separated by commas.
Fields are applied in the order they are listed.

In this example, results are sorted first by ``did_group.area_name`` and then, for DIDs with the same area name, by ``number`` in ascending order.

This helps you organize data hierarchically, starting with broader attributes and refining by more specific ones.

.. http:example:: curl

   GET /v3/dids?sort=did_group.area_name,number HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

In this example, DIDs are sorted by ``did_group.area_name`` first, and then by ``number``.

----

.. raw:: html

   <br>

Reverse sorting
^^^^^^^^^^^^^^^^^^^^^^^^^

Prefixing a field with a minus sign (``-``) sorts it in descending order.
In this example, DIDs are sorted by ``did_group.area_name`` from Z to A, and then by ``number`` in ascending order within each area.

This is useful when you need to view the most recent or highest-value items first.

.. http:example:: curl

   GET /v3/dids?sort=-did_group.area_name,number HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json



.. _api_pagination:

Pagination
----------

Pagination helps manage large datasets by dividing results into pages. Use the ``page`` query parameter to control the size of each page and specify which page to retrieve.

If pagination is not applied, some endpoints may return all records in a single response.

.. important::

   * Pagination applies to any endpoint that returns a resource collection as primary data, regardless of the request type.
   * Page size is **50** by default, unless it is overridden at a particular endpoint.
   * The maximum page size is **100**, unless it is overridden at a particular endpoint.
   * If ``page[number]`` is not specified, page **1** is returned by default.
   * Some endpoints may disable pagination and return all records in a single response.

----

.. raw:: html

   <br>

Define page size
^^^^^^^^^^^^^^^^^^^^^^^^^

Use the ``page[size]`` parameter to set the maximum number of items returned per page.

In this example, the response will include 10 records (such as cities, countries, or DIDs) per page.
If ``page[size]`` is not specified, page size is **50** by default, unless it is overridden at a particular endpoint.

.. http:example:: curl

   GET /cities?page[size]=10 HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Retrieve a specific page
^^^^^^^^^^^^^^^^^^^^^^^^^

Use the ``page[number]`` parameter to request a specific page of results.

For example, if the ``page[size]`` is set to ``10`` and the ``page[number]`` is set to ``3``, entry numbers ``21`` to ``30`` will be returned in the data.

.. http:example:: curl

   GET /v3/cities?page[number]=3&page[size]=10 HTTP/1.1
   Host: api.didww.com
   Accept: application/vnd.api+json

----

.. raw:: html

   <br>

Pagination links
^^^^^^^^^^^^^^^^^^^^^^^^^

Paginated responses include navigation links in the top-level ``links`` object:

* ``first`` – the first page of data
* ``last`` – the last page of data
* ``prev`` – the previous page of data
* ``next`` – the next page of data

These links help you navigate through paginated results without manually calculating page numbers.


.. _api_relationships:

Assigning Related Resources
---------------------------

You can manage relationships between resources using the ``PATCH`` methods.
Relationships can be either **to-one** (a single related resource) or **to-many** (multiple related resources).

.. important::

   * Use ``PATCH`` to replace or remove relationships.
   * Servers may return **403 Forbidden** if complete replacement is not allowed.

----

.. raw:: html

   <br>

Updating to-one relationships
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use a ``PATCH`` request to update a to-one relationship.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Update an inbound trunk for a DID*

      This request updates the inbound trunk assigned to a DID:

      .. http:example:: curl

         PATCH /v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "dids",
             "id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c",
             "relationships": {
               "voice_in_trunk": {
                 "data": { "type": "voice_in_trunks", "id": "d9b6ec47-0b72-452b-b4b4-23dd9d5be7e6" }
               }
             }
           }
         }

   .. tab-item:: *Remove an inbound trunk from a DID*

      This request clears the inbound trunk relationship by setting it to ``null``:

      .. http:example:: curl

         PATCH /v3/dids/f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "type": "dids",
             "id": "1e0c45b1-1fea-4552-b41b-ffa9f5eb44c5",
             "relationships": {
               "voice_in_trunk": {
                 "data": null
               }
             }
           }
         }

----

Updating to-many relationships
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use ``PATCH`` to replace all members of a to-many relationship or clear them.

.. tab-set::
   :class: my-tabs

   .. tab-item:: *Replace all inbound trunks in an inbound trunk group*

      .. http:example:: curl

         PATCH /v3/voice_in_trunk_groups/714e8148-0aea-4cb6-8680-bd1d06453418 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "id": "714e8148-0aea-4cb6-8680-bd1d06453418",
             "type": "voice_in_trunk_groups",
             "relationships": {
               "voice_in_trunks": {
                 "data": [
                   { "type": "voice_in_trunks", "id": "ca7da6d0-aa0b-447d-8fc0-1bc58b51298c"},
                   { "type": "voice_in_trunks", "id": "e9c1b7e9-253b-46c8-b7e9-5a930ab594c5" }
                 ]
               }
             }
           }
         }

   .. tab-item:: *Clear all inbound trunks in an inbound trunk group*

      .. http:example:: curl

         PATCH /v3/voice_in_trunk_groups/c07815fc-bf9e-4cbf-a3fc-9c99b8de14d8 HTTP/1.1
         Host: api.didww.com
         Content-Type: application/vnd.api+json
         Accept: application/vnd.api+json

         {
           "data": {
             "id": "c07815fc-bf9e-4cbf-a3fc-9c99b8de14d8",
             "type": "voice_in_trunk_groups",
             "relationships": {
               "voice_in_trunks": {
                 "data": []
               }
             }
           }
         }


.. _api_sparse_fieldsets:

Sparse Fieldsets
----------------

Sparse fieldsets allow you to limit the number of attributes returned for a resource.
Use the ``fields`` query parameter to request only the specific attributes you need, reducing payload size and improving performance.

This feature is especially useful when working with large or complex datasets, or when optimizing API responses for performance, bandwidth, or security.
For example, you can:

- Retrieve only specific status attributes (e.g., ``terminated`` or ``blocked``) to monitor resource state.
- Fetch minimal data when displaying resource lists or summaries.
- Limit sensitive or unused fields in API integrations to control data exposure.

.. tip::

   Combine sparse fieldsets with other query parameters such as :ref:`filter <api_filters>` or :ref:`include <api_includes>` to build efficient and highly targeted API requests.

This follows the `JSON:API sparse fieldsets <https://jsonapi.org/format/#fetching-sparse-fieldsets>`_ specification.

.. note::

   Sparse fieldsets can be applied to any endpoint that returns a resource collection or a single resource object.
   Use this feature to retrieve only the most relevant fields for your application.

----

.. raw:: html

   <br>

Retrieve a Single Attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can request a specific attribute by passing its name in the ``fields`` parameter.

In this example, the response for DIDs includes only the ``terminated`` attribute:

.. http:example:: curl

   GET /v3/dids?fields[dids]=terminated HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": [
       {
         "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
         "type": "dids",
         "attributes": {
           "terminated": false
         }
       }
     ],
     "meta": {
       "total_records": 1,
       "api_version": "2022-05-10"
     }
   }

This is useful when you only need a single attribute from each resource, such as a DID’s termination state.

----

.. raw:: html

   <br>

Retrieve Multiple Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To include more than one attribute, list them as comma-separated values within the ``fields`` parameter.

In this example, the response includes both ``terminated`` and ``blocked`` attributes:

.. http:example:: curl

   GET /v3/dids?fields[dids]=terminated,blocked HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": [
       {
         "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
         "type": "dids",
         "attributes": {
           "terminated": false,
           "blocked": false
         }
       },
       {
         "id": "2c2a4cdd-5514-419f-abe2-2777d9b95533",
         "type": "dids",
         "attributes": {
           "terminated": false,
           "blocked": false
         }
       }
     ],
     "meta": {
       "total_records": 2,
       "api_version": "2022-05-10"
     }
   }

This approach helps minimize unnecessary data transfer while retrieving key status attributes.

----

.. raw:: html

   <br>

Apply Sparse Fieldsets to Multiple Resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When including related resources, you can define separate ``fields`` parameters for each type.

In this example, the request returns only selected attributes for both ``dids`` and their related ``did_group`` resources:

.. http:example:: curl

   GET /v3/dids?include=did_group&fields[dids]=number,terminated&fields[did_groups]=area_name HTTP/1.1
   Host: api.didww.com
   Content-Type: application/vnd.api+json
   Accept: application/vnd.api+json
   Api-Key: [API token]

   HTTP/1.1 200 OK
   Content-Type: application/vnd.api+json

   {
     "data": [
       {
         "id": "d223efc9-34c3-48e4-9f1e-7a1057808127",
         "type": "dids",
         "attributes": {
           "number": "12132211022",
           "terminated": false
         }
       }
     ],
     "included": [
       {
         "id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
         "type": "did_groups",
         "attributes": {
           "area_name": "Los Angeles"
         }
       }
     ],
     "meta": {
       "total_records": 1,
       "api_version": "2022-05-10"
     }
   }

This allows you to retrieve compact responses containing exactly the fields you need across related objects.


:orphan:

API Versions Toctree
====================

.. toctree::
   :maxdepth: 1
   :hidden:

   2022-05-10/index
   2021-12-15/index
   2021-04-19/index
   2017-09-18/index

.. _cdr_streaming:
.. _user_panel_call_events:

.. |br| raw:: html

   <br />

===========
Call Events
===========

The **DIDWW Call Events API** allows to receive real-time **Call Events** and **CDRs** through a designated HTTP endpoint. This webhook-based mechanism provides flexibility for developing applications that support near real-time call processing, CDR retrieval, billing, and call tracking.

.. grid:: 1 2 2 4
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`device-mobile` **Voice IN Call Events**
      :link: did-call-events
      :link-type: doc
      :text-align: left

      Receive real-time HTTP callbacks for inbound calls, covering start, connect, and end events.

   .. grid-item-card:: :octicon:`device-desktop` **Voice OUT Call Events**
      :link: termination-call-events
      :link-type: doc
      :text-align: left

      Receive real-time outbound call event data, including detailed CDRs, connection status, and call metrics via HTTP callbacks.

   .. grid-item-card:: :octicon:`rss` **Voice IN CDR Streaming**
      :link: did-cdr
      :link-type: doc
      :text-align: left

      Receive near real-time inbound Call Detail Records (CDRs) after call completion for monitoring, reporting, and analytics.

   .. grid-item-card:: :octicon:`broadcast` **Voice OUT CDR Streaming**
      :link: termination-cdr
      :link-type: doc
      :text-align: left

      Receive near real-time outbound Call Detail Records (CDRs) after call completion for billing, reporting, and performance monitoring.

.. important::

   The **Call Events API** can only be enabled upon customer request by contacting the DIDWW Technical Support team at `support@didww.com <mailto:support@didww.com>`_.

----

.. raw:: html

   <br>

.. This raw HTML block defines a section heading with an embedded anchor link.
.. raw:: html

   <a id="configuration-and-usage"></a>
   <h2>Call Events Configuration<a class="headerlink" href="#configuration-and-usage" title="Link to this heading"></a></h2>

Call event configuration and management are available in the **API** > **Call Events API** section.

.. figure:: https://doc.didww.com/_images/call_events_fig1.png
    :figclass: align-center
    :width: 80%
    :alt: Call Events API

    **Fig. 1.** Call Events section.

To configure the Call Events service, follow these steps:

1. **Open the Configuration Page**

   Select **CDR Streaming** or **Call Events** for **Voice IN** or **Voice OUT**, then click **Configure** in the **Call Events API** page: `Call Event Configurations <https://my.didww.com/#/call_event_configs>`_.

    .. figure:: https://doc.didww.com/_images/call_events_fig2.png
        :figclass: align-center
        :width: 80%
        :alt: Configure Voice IN Call Events

        **Fig. 2.** Call Events configuration window.

2. **Enter the Required Configuration Parameters**

    .. list-table::
       :header-rows: 1
       :widths: 25 75

       * - **Parameter**
         - **Description**
       * - **Endpoint**
         - The URL where call event notifications will be delivered (e.g., `https://example.com/`).
       * - **Enable GZIP Compression** *(Optional)*
         - If enabled, HTTP data is compressed before being sent.
       * - **Authentication** *(Optional)*

         - Use **Basic Authentication (Basic Auth)** with a username and password:

           * **Username**
             - The username associated with the endpoint URL.

           * **Password**
             - The password associated with the endpoint URL.
       * - **Headers** *(Optional)*
         - Define custom HTTP headers.

           **Examples:**

           * **X-Auth-Token**
             - Secure authentication token used for verifying requests (e.g., `your_secure_token`).

           * **X-Client-ID**
             - Unique identifier for the client or application sending the request (e.g., `unique_client_identifier`).

3. **Save the Configuration**

   Click **Submit** to finalize the setup and activate call event delivery.

----

.. raw:: html

   <a id="call-events-ip-addresses"></a>
   <h3>Call Events IP addresses<a class="headerlink" href="#call-events-ip-addresses" title="Link to this heading"></a></h3>

Call event requests are sent from the following IP addresses:

    - **IPv4:** `46.19.210.148`
    - **IPv6:** `2a01:ad00:2:3::148`

Ensure that these IP addresses are whitelisted in your receiving system.

----

.. raw:: html

   <a id="call-events-request-format"></a>
   <h3>Call Events Request format<a class="headerlink" href="#call-events-request-format" title="Link to this heading"></a></h3>

Call Events are delivered as HTTP **POST** requests to your configured endpoint.
The request payload structure varies based on the service type (Voice IN or Voice OUT).

Ensure your endpoint is configured to:

    - Accept **JSON-formatted** payloads (optionally gzip-compressed).
    - Validate event types (`start`, `connect`, `end`).
    - Parse timestamps, caller/callee numbers, and unique call identifiers for tracking.

For full details on payload schemas, supported attributes, and processing best practices, refer to the related API documentation.

.. toctree::
  :hidden:
  :maxdepth: 1

  Inbound Call Events <did-call-events.rst>
  Outbound Call Events <termination-call-events.rst>
  Inbound CDR Streaming <did-cdr.rst>
  Outbound CDR Streaming <termination-cdr.rst>


.. _did_call_events:

.. |br| raw:: html

   <br />

=====================
Voice IN Call Events
=====================

Voice IN Call Events allow you to receive real-time call events for calls to DID numbers using the HTTP protocol. Events are delivered individually with no batching delays.
All events are sent via an HTTP **POST** request, and content can optionally be **gzipped**.

Available event types:
    - **Call Start Event** – Triggered when the call routing process is completed, and the system attempts to connect the call.
    - **Call Connect Event** – Triggered when a **200 OK/Connect** response is received from the destination.
    - **Call End Event** – Triggered when the call is terminated.

.. raw:: html

   <br>

----

Request Header Example
=======================

The following is an example of an HTTP **POST** request header used to send Voice IN Call Events. It includes details such as the destination server, content type, encoding, and request size.

    .. code-block:: http

       POST /call-events HTTP/1.1
       Host: 192.0.2.5
       User-Agent: CDR-streamer
       Accept: */*
       Content-Type: application/vnd.api+json
       Content-Encoding: gzip
       Content-Length: 2358

.. raw:: html

   <br>

----

Call Start Event
================

A **Call Start Event** is triggered when the call routing process is completed by DIDWW, and the system attempts to connect the call to the destination. At this stage, a **SIP INVITE** is sent from DIDWW to initiate the call connection.

When is this event triggered?
    - After DIDWW completes call routing.
    - Before the call is answered or connected.
    - When a **SIP INVITE** is sent to the call destination.

HTTP Request Payload Example
------------------------------

The following JSON payload represents a **Call Start Event**, providing details such as the event type, unique identifier, start time, and involved phone numbers.

    .. code-block:: json

        {
            "type": "incoming-call-start-event",
            "id": "10-10282FC6-5F632C460006A397-AC8C7700",
            "attributes": {
                "time_start": "2020-03-05T11:05:33.879559+00:00",
                "did_number": "123456789123",
                "src_number": "111111222222"
            }
        }

.. raw:: html

   <br>

----

Call Connect Event
==================

A **Call Connect Event** is triggered when a **200 OK/Connect** response is received from the destination (call leg B). This indicates that the call has been successfully answered or connected.

When is this event triggered?
    - After the call destination responds with **200 OK**.
    - When the call moves from the ringing state to an active conversation.

    .. note::
       If the call is terminated before this handshake, the **Call Connect Event** will not be sent.

HTTP Request Payload Example
------------------------------

The following JSON payload represents a **Call Connect Event**, providing details such as event type, call identifier, timestamps, and involved phone numbers.

    .. code-block:: json

        {
            "type": "incoming-call-connect-event",
            "id": "10-10282FC6-5F632C460006A397-AC8C7700",
            "attributes": {
                "time_start": "2020-03-05T11:05:33.879559+00:00",
                "time_connect": "2020-03-05T11:05:38.879559+00:00",
                "did_number": "123456789123",
                "src_number": "111111222222",
                "call_id": "26-26-3F1808BB-61090891000DD511-EA83C700"
            }
        }

.. raw:: html

   <br>

----

Call End Event
==============

A **Call End Event** is triggered when the call is terminated, regardless of whether it was answered or not. This event provides details such as the start time, connection time (if applicable), end time, and total call duration.

When is this event triggered?
    - When the call is **disconnected** by either party.
    - Whether the call was **answered** (**connected**) or not.

HTTP Request Payload Example
------------------------------

The following JSON payload represents a **Call End Event**, including timestamps, call duration, and involved phone numbers.

    .. code-block:: json

        {
            "type": "incoming-call-end-event",
            "id": "10-10282FC6-5F632C460006A397-AC8C7700",
            "attributes": {
                "time_start": "2020-03-05T11:05:33.879559+00:00",
                "time_connect": "2020-03-05T11:05:38.879559+00:00",
                "time_end": "2020-03-05T11:05:58.879559+00:00",
                "duration": 20,
                "did_number": "123456789123",
                "src_number": "111111222222",
                "call_id": "26-26-3F1808BB-61090891000DD511-EA83C700"
            }
        }

.. raw:: html

   <br>

----

Call Event Attributes
=====================

.. list-table:: Voice IN (inbound) Call Event Descriptions and Examples
   :header-rows: 1
   :widths: 10 10 40 30

   * - **Attribute**
     - **Type**
     - **Description**
     - **Example**
   * - **type**
     - String

     - Event type. Possible values:

       - `incoming-call-start-event`
       - `incoming-call-connect-event`
       - `incoming-call-end-event`
     - `"incoming-call-start-event"`
   * - **id**
     - String
     - Unique call identifier. All related events share the same `id`.
     - `"10-10282FC6-5F632C460006A397-AC8C7700"`
   * - **attributes**
     - Hash
     - Structure containing all event attributes.
     - *See below for attribute details.*
   * - **time_start**
     - Timestamp
     - Timestamp when the initial SIP INVITE is received.
     - `"2024-03-05T11:05:33.879559+00:00"`
   * - **time_connect**
     - Timestamp
     - Time when the call was successfully connected (`200 OK SIP` response).

       If the call was never connected, this value is `null` in the **Call End Event**.
     - `"2024-03-05T11:05:38.879559+00:00"`
   * - **time_end**
     - Timestamp
     - Timestamp when the call was disconnected.
     - `"2024-03-05T11:05:58.879559+00:00"`
   * - **call_id**
     - String
     - SIP Call-ID for the call leg between the customer's equipment and DIDWW.

       Since DIDWW supports call rerouting (:ref:`see trunk group configuration <user_panel_trunk_group>`),

       it is not possible to determine the connected call leg at the **incoming-call-start-event** step.

       Therefore, the `call_id` attribute is **not present** in the **incoming-call-start-event** payload.
     - `"26-26-3F1808BB-61090891000DD511-EA83C700"`
   * - **duration**
     - Integer
     - Call duration in seconds.
       For unconnected calls, this value is `0`.
     - `20`
   * - **src_number**
     - String
     - Caller ID (originating phone number).
     - `"111111222222"`
   * - **did_number**
     - String
     - The DID number receiving the call.
     - `"123456789123"`

.. This CSS modifies the appearance of code blocks and admonitions in Sphinx documentation.
.. Removes default borders for a cleaner look.
.. Changes background color to a soft blue (`#F3F7FC`) for better readability.
.. Ensures code blocks have a max width (`60rem`) for layout consistency.
.. Uses monospaced fonts for preformatted text.
.. Adjusts line height for better text clarity.
.. Adds rounded corners (`border-radius: 10px`) for a modern UI.
.. Customizes string color (`.s2` class) for syntax highlighting.
.. Limits the width of admonition boxes (e.g., notes) to align with the layout.

.. raw:: html

   <style>

    .http-example .caption,.section ul .http-example .caption{
        display:inline-block;
        cursor:pointer;
        color:#2c2c2c;
        background-color: #F3F7FC !important;
        border-bottom:3px solid #dcdcdc;
        border-top-right-radius:0;
        padding:.5em 1em;
        margin:0
    }

    .http-example .caption.selected{
        font-weight:700;
        color:#246bbc;
        border:0 solid transparent;
        background-color: #F3F7FC !important;
        border-bottom:3px solid #246bbc !important
    }

    .rst-content div[class^=highlight],
    .rst-content pre.literal-block {
        border: 0;
        background: 0;
        background-color: #F3F7FC !important;
        overflow-x: auto;
        color: #2c2c2c;
        margin: 1px 0 24px;
        max-width: 60rem !important;
        box-sizing: content-box;
        border-radius: 10px;
    }

        pre {
            line-height: 125%;
        }

        .rst-content div[class^="highlight"] pre {
            font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", Courier, monospace;
            font-size: 14px;
            background-color: #F3F7FC !important;
            border-radius: 10px;
            color: rgb(44, 44, 44);
            line-height: 1.4;
            border: 0px;
        }

        .rst-content div[class^="highlight"] pre {
            background-color: #F3F7FC !important;
        }

        .highlight .s2 {
            color: rgb(64, 112, 160);
        }

    .admonition.note {
        max-width: 60rem !important;
        }

    </style>

.. _did_cdr_streaming:

.. |br| raw:: html

   <br />

==============================
Voice IN Service CDR Streaming
==============================

The **Voice IN CDR Streamer** enables customers to receive near real-time **Call Detail Records (CDRs)**.

.. important:: CDRs are **delivered within 3 seconds** after call completion to the customer's designated **HTTP endpoint**.

.. raw:: html

   <br>

----

HTTP request payload examples
=============================

The following is an example of an HTTP **POST** request header used for Voice IN CDR Streaming. It provides key details such as the destination server, content type, encoding, and request size.

    .. code-block:: http

        POST /cdr HTTP/1.1
        Host: 192.0.2.5
        User-Agent: CDR-streamer
        Accept: */*
        Content-Type: text/plain
        Content-Encoding: gzip
        Content-Length: 2358
        Expect: 100-continue

    .. warning::
       The request payload is **gzip-encoded**. Ensure that your API supports **gzip decompression**
       for proper processing of incoming CDRs.

       See `gzip compression <https://en.wikipedia.org/wiki/HTTP_compression>`_ for more details.

.. raw:: html

   <br>

**Example: Successfully Completed Call**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example represents a **successful call** that lasted **9 seconds**:
    - **Call duration is `9` seconds**, indicating that the call was successfully connected and active.
    - **`time_connect` is present**, confirming that the call was answered.
    - **Leg B (`legb`) disconnect reason is `"Bye"`**, meaning the call was normally ended.
    - **Disconnect initiator:** `3` (Call originator), meaning the caller ended the call.

    .. code-block:: json

        {
              "type": "inbound-cdr",
              "attributes": {
                "sub_customer_tf_connection_fee": 0,
                "trm_initial_interval": null,
                "sub_customer_trm_duration": null,
                "metered_channels_duration": null,
                "sub_customer_trm_next_interval": null,
                "time_connect": "2025-02-14T14:36:58.843904",
                "metered_channels_amount_no_vat": null,
                "local_tag": "14-1519849E-67AF550A000B932D-348F56C0",
                "metered_channels_next_interval": null,
                "internal_disconnect_reason": "Bye",
                "tf_rate": 0,
                "duration": 9,
                "metered_channels_connection_fee": null,
                "tf_connection_fee": 0,
                "is_last_cdr": true,
                "sub_customer_tf_duration": null,
                "customer_vat": 0,
                "success": true,
                "metered_channels_rate": null,
                "sub_customer_trm_connection_fee": 0,
                "dst_number": "77615145141",
                "disconnect_initiator": 3,
                "trm_duration": null,
                "tf_duration": null,
                "src_name": "353122345478",
                "time_start": "2025-02-14T14:36:58.75863",
                "sub_customer_trm_amount": null,
                "term_call_id": "14-14-32FA4FA2-67AF550A000B9E59-5E1F96C0",
                "early_media_present": false,
                "did_number": "321555",
                "tf_initial_interval": null,
                "trm_rate": 0,
                "tf_next_interval": null,
                "time_end": "2025-02-14T14:37:06.977841",
                "legb_disconnect_reason": "Bye",
                "sub_customer_tf_next_interval": null,
                "sub_customer_id": null,
                "internal_disconnect_code": 200,
                "trm_amount_no_vat": null,
                "sub_customer_tf_initial_interval": null,
                "trunk_destination": "sip:123456@192.0.2.67",
                "sub_customer_trm_rate": 0,
                "legb_disconnect_code": 200,
                "sub_customer_tf_rate": 0,
                "sub_customer_tf_amount": null,
                "sub_customer_trm_initial_interval": null,
                "tf_amount": null,
                "routing_attempt": 1,
                "transport_protocol_id": 1,
                "is_redirected": false,
                "out_pop_id": 1,
                "user_agent": "sems callgen",
                "trm_connection_fee": 0,
                "tf_amount_no_vat": null,
                "trm_next_interval": null,
                "metered_channels_initial_interval": null,
                "src_number": "123456789",
                "metered_channels_amount": null,
                "trm_amount": null
              },
          "id": "e20d1722-9b47-4644-92fe-fce28f26871c"
        }

.. raw:: html

   <br>

----

.. _voice_in_cdr_streaming_attributes:

Voice IN CDR Streaming Attributes
=================================

.. list-table:: Voice IN (incoming) service CDR Streaming Descriptions and Examples
   :header-rows: 1
   :widths: 15 7 35 20

   * - **Attribute**
     - **Type**
     - **Description**
     - **Example**
   * - **type**
     - String
     - CDR type identifier. Voice IN CDRs are marked as **inbound-cdr**.
     - `"inbound-cdr"`
   * - **id**
     - String
     - Unique CDR identifier in **UUID** format.
     - `"3d6af8ac-5ed1-11ea-bc9d-005056845b1e"`
   * - **attributes**
     - Hash
     - Structure containing all CDR attributes.
     - *See below for attribute details.*
   * - **time_start**
     - Timestamp
     - Start time when the initial SIP INVITE is received.
     - `"2025-02-14T14:36:58.75863"`
   * - **time_connect**
     - Timestamp
     - Time after the successful handshake (**200 OK SIP**).
     - `"2025-02-14T14:36:58.843904"`
   * - **time_end**
     - Timestamp
     - Time when the call was disconnected.
     - `"2025-02-14T14:37:06.977841"`
   * - **duration**
     - Integer
     - Call duration in seconds. For non-connected calls, duration is **0**.
     - `35`
   * - **disconnect_initiator**
     - Integer
     - Indicates which party initiated disconnection:

           - 0 - Routing engine
           - 1 - SBC
           - 2 - Called destination network
           - 3 - Call originator
     - `3`
   * - **internal_disconnect_code**
     - Integer
     - DIDWW internal disconnect code.
     - `200`
   * - **internal_disconnect_reason**
     - String
     - DIDWW internal disconnect reason.
     - `"Bye"`
   * - **legb_disconnect_code**
     - Integer
     - SIP response code received from the destination network.
     - `200`
   * - **legb_disconnect_reason**
     - String
     - SIP disconnect reason received from the destination network.
     - `"Normal Clearing"`
   * - **routing_attempt**
     - Integer
     - Number of routing attempts to reach the destination network.
     - `1`
   * - **is_last_cdr**
     - Boolean
     - Indicates if this is the last attempt to reach the destination network in the event of fail-over.
     - `true`
   * - **success**
     - Boolean
     - Indicates whether the call was successfully connected.
     - `true`
   * - **term_call_id**
     - String
     - SIP Call-ID of the call leg between DIDWW and customer equipment.
     - `"10-10-7ED7C3EC-5DBAF487000C1C19-8FCFC700"`
   * - **local_tag**
     - String
     - Internal identifier of the call record.
     - `"10-04336EB9-5DBAF4AA000E6DDB-6A41F700"`
   * - **did_number**
     - String
     - DID number in full format.
     - `"972397239159092"`
   * - **src_name**
     - String
     - Incoming caller name.
     - `"John Doe"`
   * - **src_number**
     - String
     - Incoming Caller-ID.
     - `"111111222222"`
   * - **dst_number**
     - String
     - Called destination number.
     - `"97239723915909200"`
   * - **trunk_destination**
     - String
     - Call destination in URI format.
     - `"sip:972397239159092@didww.com"`
   * - **customer_vat**
     - Numeric
     - Charged VAT amount for the call.
     - `0.20`
   * - **tf_rate**
     - Numeric
     - Customer Toll-Free rate.
     - `0.05`
   * - **tf_connection_fee**
     - Numeric
     - Customer Toll-Free connection fee.
     - `0.10`
   * - **tf_initial_interval**
     - Integer
     - Initial billing interval for Toll-Free service.
     - `60`
   * - **tf_next_interval**
     - Integer
     - Next billing interval for Toll-Free service.
     - `30`
   * - **tf_duration**
     - Integer
     - Call duration rounded to configured billing interval for Toll-Free service.
     - `120`
   * - **tf_amount**
     - Numeric
     - Customer Toll-Free accumulated amount.
     - `2.40`
   * - **tf_amount_no_vat**
     - Numeric
     - Customer Toll-Free accumulated amount **excluding VAT**.
     - `1.90`
   * - **trm_rate**
     - Numeric
     - Customer termination rate. Applies when PSTN forwarding is used.
     - `0.07`
   * - **trm_connection_fee**
     - Numeric
     - Customer termination connection fee. Applies when PSTN forwarding is used.
     - `0.15`
   * - **trm_initial_interval**
     - Integer
     - Initial billing interval length in seconds for PSTN forwarding.
     - `60`
   * - **trm_next_interval**
     - Integer
     - Next billing interval length in seconds for PSTN forwarding.
     - `30`
   * - **trm_duration**
     - Integer
     - Call duration rounded to configured billing interval for PSTN forwarding.
     - `180`
   * - **trm_amount**
     - Numeric
     - Customer PSTN termination accumulated amount.
     - `3.50`
   * - **trm_amount_no_vat**
     - Numeric
     - Customer PSTN termination accumulated amount **excluding VAT**.
     - `2.77`
   * - **metered_channels_rate**
     - Numeric
     - Metered capacity rate.
     - `0.02`
   * - **metered_channels_connection_fee**
     - Numeric
     - Metered capacity connection fee.
     - `0.05`
   * - **metered_channels_initial_interval**
     - Integer
     - Metered capacity initial billing interval in seconds.
     - `60`
   * - **metered_channels_next_interval**
     - Integer
     - Metered capacity next billing interval length.
     - `30`
   * - **metered_channels_duration**
     - Integer
     - Metered capacity charged duration.
     - `120`
   * - **metered_channels_amount**
     - Numeric
     - Customer metered capacity accumulated amount.
     - `2.40`
   * - **metered_channels_amount_no_vat**
     - Numeric
     - Customer metered capacity accumulated amount **excluding VAT**.
     - `1.90`
   * - **out_pop_id**
     - Integer
     - DIDWW **Point of Presence (PoP)** for the call leg from DIDWW to the customer:

           - 1 - USA New York
           - 2 - EU Frankfurt
           - 4 - USA Los Angeles
           - 5 - USA Miami
           - 6 - AS Singapore
           - 7 - AS Hong Kong
           - 8 - EU Amsterdam
     - `2`
   * - **transport_protocol_id**
     - Integer
     - Transport protocol used between DIDWW and the customer gateway:

           - 1 - UDP
           - 2 - TCP
           - 3 - TLS
     - `2`
   * - **user_agent**
     - String
     - User-Agent and Server header values from the customer gateway.
     - `"Asterisk PBX 16.6.0"`
   * - **is_redirected**
     - Boolean
     - Indicates if the call was redirected by a **3xx SIP response**.
     - `false`
   * - **early_media_present**
     - Boolean
     - Indicates if an early media stream was present in the destination gateway.
     - `true`

.. raw:: html

   <br>

----

Batching
========

Call Detail Records (**CDRs**) are delivered in **batches**, meaning a single HTTP `POST` request can contain multiple CDRs. This reduces the number of requests while ensuring efficient data transmission.

Key Details:
    - The CDRs are separated by new lines.
    - The maximum batch size is 1,000 CDRs per request.
    - The destination API must be capable of processing multiple CDRs within the same request.

Example: CDRs in a Batch
^^^^^^^^^^^^^^^^^^^^^^^^

Below is an example of a payload containing five CDRs.

    .. code-block:: json

        { "type" : "inbound-cdr", "attributes" : { "sub_customer_tf_connection_fee" : 0, "trm_initial_interval" : null, "sub_customer_trm_duration" : null, "metered_channels_duration" : 60, "sub_customer_trm_next_interval" : null, "time_connect" : "2025-04-18T07:47:44.412933", "metered_channels_amount_no_vat" : 0.01, "local_tag" : "21-25F86C33-680203A00004FB2D-7B9F96C0", "metered_channels_next_interval" : 60, "internal_disconnect_reason" : "Bye", "tf_rate" : 0, "duration" : 11, "metered_channels_connection_fee" : 0, "tf_connection_fee" : 0, "is_last_cdr" : true, "sub_customer_tf_duration" : null, "customer_vat" : 21, "success" : true, "metered_channels_rate" : 0.01, "sub_customer_trm_connection_fee" : 0, "dst_number" : "echotest", "disconnect_initiator" : 3, "trm_duration" : null, "tf_duration" : null, "src_name" : "16473635777", "time_start" : "2025-04-18T07:47:44.326742", "sub_customer_trm_amount" : null, "term_call_id" : "21-21-4F754B3D-680203A0000515F7-FE5EC6C0", "early_media_present" : false, "did_number" : "18312630056", "tf_initial_interval" : null, "trm_rate" : 0, "tf_next_interval" : null, "time_end" : "2025-04-18T07:47:54.815287", "legb_disconnect_reason" : "Bye", "sub_customer_tf_next_interval" : null, "sub_customer_id" : null, "internal_disconnect_code" : 200, "trm_amount_no_vat" : null, "sub_customer_tf_initial_interval" : null, "trunk_destination" : "sip:echotest@46.19.209.12", "sub_customer_trm_rate" : 0, "legb_disconnect_code" : 200, "sub_customer_tf_rate" : 0, "sub_customer_tf_amount" : null, "sub_customer_trm_initial_interval" : null, "tf_amount" : null, "routing_attempt" : 1, "transport_protocol_id" : 1, "is_redirected" : false, "out_pop_id" : 1, "user_agent" : "sems callgen", "trm_connection_fee" : 0, "tf_amount_no_vat" : null, "trm_next_interval" : null, "metered_channels_initial_interval" : 60, "src_number" : "16473635777", "metered_channels_amount" : 0.0121, "trm_amount" : null }, "id" : "847d3532-3592-441c-9305-035d31bb38d0" }
        { "type" : "inbound-cdr", "attributes" : { "sub_customer_tf_connection_fee" : 0, "trm_initial_interval" : null, "sub_customer_trm_duration" : null, "metered_channels_duration" : 60, "sub_customer_trm_next_interval" : null, "time_connect" : "2025-04-18T07:47:45.339513", "metered_channels_amount_no_vat" : 0.01, "local_tag" : "21-4B73AFD3-680203A10003DF75-7B9F96C0", "metered_channels_next_interval" : 60, "internal_disconnect_reason" : "Bye", "tf_rate" : 0, "duration" : 11, "metered_channels_connection_fee" : 0, "tf_connection_fee" : 0, "is_last_cdr" : true, "sub_customer_tf_duration" : null, "customer_vat" : 21, "success" : true, "metered_channels_rate" : 0.01, "sub_customer_trm_connection_fee" : 0, "dst_number" : "echotest", "disconnect_initiator" : 3, "trm_duration" : null, "tf_duration" : null, "src_name" : "16473635777", "time_start" : "2025-04-18T07:47:45.253978", "sub_customer_trm_amount" : null, "term_call_id" : "21-21-26FD31F5-680203A10003F6FB-FE3EA6C0", "early_media_present" : false, "did_number" : "18312630056", "tf_initial_interval" : null, "trm_rate" : 0, "tf_next_interval" : null, "time_end" : "2025-04-18T07:47:55.576196", "legb_disconnect_reason" : "Bye", "sub_customer_tf_next_interval" : null, "sub_customer_id" : null, "internal_disconnect_code" : 200, "trm_amount_no_vat" : null, "sub_customer_tf_initial_interval" : null, "trunk_destination" : "sip:echotest@46.19.209.12", "sub_customer_trm_rate" : 0, "legb_disconnect_code" : 200, "sub_customer_tf_rate" : 0, "sub_customer_tf_amount" : null, "sub_customer_trm_initial_interval" : null, "tf_amount" : null, "routing_attempt" : 1, "transport_protocol_id" : 1, "is_redirected" : false, "out_pop_id" : 1, "user_agent" : "sems callgen", "trm_connection_fee" : 0, "tf_amount_no_vat" : null, "trm_next_interval" : null, "metered_channels_initial_interval" : 60, "src_number" : "16473635777", "metered_channels_amount" : 0.0121, "trm_amount" : null }, "id" : "79479a72-1d19-41cf-83e5-515273915489" }
        { "type" : "inbound-cdr", "attributes" : { "sub_customer_tf_connection_fee" : 0, "trm_initial_interval" : null, "sub_customer_trm_duration" : null, "metered_channels_duration" : 60, "sub_customer_trm_next_interval" : null, "time_connect" : "2025-04-18T07:47:45.146977", "metered_channels_amount_no_vat" : 0.01, "local_tag" : "21-21E66A31-680203A10000E80F-7B9F96C0", "metered_channels_next_interval" : 60, "internal_disconnect_reason" : "Bye", "tf_rate" : 0, "duration" : 11, "metered_channels_connection_fee" : 0, "tf_connection_fee" : 0, "is_last_cdr" : true, "sub_customer_tf_duration" : null, "customer_vat" : 21, "success" : true, "metered_channels_rate" : 0.01, "sub_customer_trm_connection_fee" : 0, "dst_number" : "echotest", "disconnect_initiator" : 3, "trm_duration" : null, "tf_duration" : null, "src_name" : "16473635777", "time_start" : "2025-04-18T07:47:45.059612", "sub_customer_trm_amount" : null, "term_call_id" : "21-21-46EABA05-680203A100010655-FE4EB6C0", "early_media_present" : false, "did_number" : "18312630056", "tf_initial_interval" : null, "trm_rate" : 0, "tf_next_interval" : null, "time_end" : "2025-04-18T07:47:55.691302", "legb_disconnect_reason" : "Bye", "sub_customer_tf_next_interval" : null, "sub_customer_id" : null, "internal_disconnect_code" : 200, "trm_amount_no_vat" : null, "sub_customer_tf_initial_interval" : null, "trunk_destination" : "sip:echotest@46.19.209.12", "sub_customer_trm_rate" : 0, "legb_disconnect_code" : 200, "sub_customer_tf_rate" : 0, "sub_customer_tf_amount" : null, "sub_customer_trm_initial_interval" : null, "tf_amount" : null, "routing_attempt" : 1, "transport_protocol_id" : 1, "is_redirected" : false, "out_pop_id" : 1, "user_agent" : "sems callgen", "trm_connection_fee" : 0, "tf_amount_no_vat" : null, "trm_next_interval" : null, "metered_channels_initial_interval" : 60, "src_number" : "16473635777", "metered_channels_amount" : 0.0121, "trm_amount" : null }, "id" : "f0270ad1-2b52-4001-a5fc-f44bd456f60c" }
        { "type" : "inbound-cdr", "attributes" : { "sub_customer_tf_connection_fee" : 0, "trm_initial_interval" : null, "sub_customer_trm_duration" : null, "metered_channels_duration" : null, "sub_customer_trm_next_interval" : null, "time_connect" : "2025-04-18T07:47:45.793212", "metered_channels_amount_no_vat" : null, "local_tag" : "21-5A25EFB7-680203A1000A80FF-7B9F96C0", "metered_channels_next_interval" : null, "internal_disconnect_reason" : "Bye", "tf_rate" : 0, "duration" : 11, "metered_channels_connection_fee" : null, "tf_connection_fee" : 0, "is_last_cdr" : true, "sub_customer_tf_duration" : null, "customer_vat" : 21, "success" : true, "metered_channels_rate" : null, "sub_customer_trm_connection_fee" : 0, "dst_number" : "echotest", "disconnect_initiator" : 3, "trm_duration" : null, "tf_duration" : null, "src_name" : "16473635777", "time_start" : "2025-04-18T07:47:45.688656", "sub_customer_trm_amount" : null, "term_call_id" : "21-21-5C69BF48-680203A1000AE3C0-FE2E96C0", "early_media_present" : false, "did_number" : "18312630056", "tf_initial_interval" : null, "trm_rate" : 0, "tf_next_interval" : null, "time_end" : "2025-04-18T07:47:56.234491", "legb_disconnect_reason" : "Bye", "sub_customer_tf_next_interval" : null, "sub_customer_id" : null, "internal_disconnect_code" : 200, "trm_amount_no_vat" : null, "sub_customer_tf_initial_interval" : null, "trunk_destination" : "sip:echotest@46.19.209.12", "sub_customer_trm_rate" : 0, "legb_disconnect_code" : 200, "sub_customer_tf_rate" : 0, "sub_customer_tf_amount" : null, "sub_customer_trm_initial_interval" : null, "tf_amount" : null, "routing_attempt" : 1, "transport_protocol_id" : 1, "is_redirected" : false, "out_pop_id" : 1, "user_agent" : "sems callgen", "trm_connection_fee" : 0, "tf_amount_no_vat" : null, "trm_next_interval" : null, "metered_channels_initial_interval" : null, "src_number" : "16473635777", "metered_channels_amount" : null, "trm_amount" : null }, "id" : "9b19db91-ba19-43b8-b6e2-dba40fb7ed1b" }
        { "type" : "inbound-cdr", "attributes" : { "sub_customer_tf_connection_fee" : 0, "trm_initial_interval" : null, "sub_customer_trm_duration" : null, "metered_channels_duration" : null, "sub_customer_trm_next_interval" : null, "time_connect" : "2025-04-18T07:47:46.117589", "metered_channels_amount_no_vat" : null, "local_tag" : "22-3B7592C2-680203A200004394-2CBF86C0", "metered_channels_next_interval" : null, "internal_disconnect_reason" : "Bye", "tf_rate" : 0, "duration" : 11, "metered_channels_connection_fee" : null, "tf_connection_fee" : 0, "is_last_cdr" : true, "sub_customer_tf_duration" : null, "customer_vat" : 21, "success" : true, "metered_channels_rate" : null, "sub_customer_trm_connection_fee" : 0, "dst_number" : "echotest", "disconnect_initiator" : 3, "trm_duration" : null, "tf_duration" : null, "src_name" : "16473635777", "time_start" : "2025-04-18T07:47:46.017443", "sub_customer_trm_amount" : null, "term_call_id" : "22-22-1A8BCA30-680203A200009664-AB1EB6C0", "early_media_present" : false, "did_number" : "18312630056", "tf_initial_interval" : null, "trm_rate" : 0, "tf_next_interval" : null, "time_end" : "2025-04-18T07:47:56.429066", "legb_disconnect_reason" : "Bye", "sub_customer_tf_next_interval" : null, "sub_customer_id" : null, "internal_disconnect_code" : 200, "trm_amount_no_vat" : null, "sub_customer_tf_initial_interval" : null, "trunk_destination" : "sip:echotest@46.19.209.12", "sub_customer_trm_rate" : 0, "legb_disconnect_code" : 200, "sub_customer_tf_rate" : 0, "sub_customer_tf_amount" : null, "sub_customer_trm_initial_interval" : null, "tf_amount" : null, "routing_attempt" : 1, "transport_protocol_id" : 1, "is_redirected" : false, "out_pop_id" : 1, "user_agent" : "sems callgen", "trm_connection_fee" : 0, "tf_amount_no_vat" : null, "trm_next_interval" : null, "metered_channels_initial_interval" : null, "src_number" : "16473635777", "metered_channels_amount" : null, "trm_amount" : null }, "id" : "25166fb8-3e2b-4905-bdd0-48152c27a4b5" }

    .. note::

       - Ensure that your system is capable of parsing multiple new line separated **JSON objects**.
       - Each CDR object is not enclosed in a larger array or object.

.. raw:: html

   <br>

----

Error Handling
==============

The **CDR Streaming Interface** determines whether a batch of CDRs has been successfully processed based on the HTTP response from the destination API.

Success Criteria:
    - If the API responds with a **2xx HTTP status code**, all CDRs in that request are marked as **processed** and automatically removed from the queue.

Failure & Retry Mechanism:
    - If the API returns a **non-2xx response** (e.g., `4xx` or `5xx`) or the request **times out**, the CDRs **remain in the queue**.
    - A **retry attempt** will occur **after 3 seconds** to ensure delivery.

.. warning::

   1. **Queue Size Limit:**
          - The **CDR queue is limited to 10,000 records per customer**.
          - Extended downtime or delayed processing may result in **CDR loss** at the customer’s endpoint.
          - The **CDR Streaming mechanism should not be relied upon as the sole method** for CDR retrieval.
          - Refer to the :ref:`API documentation <export_v33>` for additional CDR retrieval methods.

   2. **Timeout Handling:**
          - If the **HTTP endpoint does not respond within 10 seconds**, the request **will time out**, triggering an **automatic retry**.
          - Ensure the destination API can handle incoming requests efficiently to prevent unnecessary retries.



.. _termination_call_events:

.. |br| raw:: html

   <br />

=====================
Voice OUT Call Events
=====================

Voice OUT Call Events allow you to receive real-time call event notifications for outbound calls using the HTTP protocol.
Events are delivered individually with no batching delays. Each request contains a single event and is sent via an HTTP **POST** request.
The request content can optionally be **gzipped** to reduce data size.

Available event types:
    - **Call Start Event** – Triggered when an outbound call attempt is initiated.
    - **Call Connect Event** – Triggered when the call is successfully answered (**200 OK/Connect** response).
    - **Call End Event** – Triggered when the call is terminated.

.. raw:: html

   <br>

----

Request Header Example
=======================

The following is an example of an HTTP **POST** request header used to send Voice OUT Call Events. It includes details such as the destination server, content type, encoding, and request size.

    .. code-block:: http

        POST /call-events HTTP/1.1
        Host: 192.0.2.5
        User-Agent: CDR-streamer
        Accept: */*
        Content-Type: application/vnd.api+json
        Content-Encoding: gzip
        Content-Length: 2358

.. raw:: html

   <br>

----

Call Start Event
================

A **Call Start Event** is triggered when an outbound call attempt is initiated. This event is sent to the customer via the HTTP protocol after the call routing process is completed by DIDWW (destination determination process).
At this stage, a **SIP INVITE** is sent from DIDWW to the call destination.

When is this event triggered?
    - After DIDWW completes the call routing process.
    - When a **SIP INVITE** is sent to initiate the outbound call.
    - Before the call is answered or connected.

HTTP request payload example
------------------------------

The following JSON payload represents a **Call Start Event**, providing details such as event type, call identifiers, timestamps, and call routing details.

    .. code-block:: json

        {
            "type": "outbound-call-start-event",
            "id": "10-10282FC6-5F632C460006A397-AC8C7700",
            "attributes": {
                "source_ip" : "192.0.2.1",
                "source_port": 5060,
                "call_id" : "3eab288b2e0eb547122434ce0e648bb5",
                "time_start": "2020-03-05T11:05:33.879559+00:00",
                "pop": "NYC",
                "original_src_number": "02089643990",
                "src_number": "123439643990",
                "dst_number": "441158720600",
                "trunk_name": "Trunk 1",
                "rate": "0.004",
                "initial_billing_interval": 1,
                "next_billing_interval": 1,
                "p_charge_info": "<sip:02089643990@customer.example.com;billing-account-id=212>",
                "diversion" : [ "<sip:+123456789@sip.didww.com>;reason=unconditional" ]
            }
        }

.. raw:: html

   <br>

----

Call Connect Event
==================

A **Call Connect Event** is triggered when the call is successfully answered, and a **200 OK/Connect** response is received from the destination (**call leg B**).

When is this event triggered?
    - When the call destination (**call leg B**) responds with **200 OK**.
    - When the call moves from the ringing state to an active conversation.

    .. note::
       If the call is terminated before a successful handshake (**200 OK**), the **Call Connect Event** will not be sent to the customer's endpoint.

HTTP request payload example
------------------------------

The following JSON payload represents a **Call Connect Event**, providing details such as event type, call identifiers, timestamps, and call routing details.

    .. code-block:: json

        {
            "type": "outbound-call-connect-event",
            "id": "10-10282FC6-5F632C460006A397-AC8C7700",
            "attributes": {
                "source_ip" : "192.0.2.1",
                "source_port": 5060,
                "call_id" : "3eab288b2e0eb547122434ce0e648bb5",
                "time_start": "2020-03-05T11:05:33.879559+00:00",
                "time_connect": "2020-03-05T11:05:38.879559+00:00",
                "pop": "NYC",
                "original_src_number": "02089643990",
                "src_number": "123439643990",
                "dst_number": "441158720600",
                "trunk_name": "Trunk 1",
                "rate": "0.004",
                "initial_billing_interval": 1,
                "next_billing_interval": 1,
                "p_charge_info": "<sip:02089643990@customer.example.com;billing-account-id=212>",
                "diversion" : [ "<sip:+123456789@sip.didww.com>;reason=unconditional" ]
            }
        }

.. raw:: html

   <br>

----

Call End Event
==============

A Call End Event is sent to the customer via HTTP protocol when the call is terminated in any way.

When is this event triggered?
    - When the call is **disconnected** by either party.
    - Whether the call was **answered** (**connected**) or not.

    .. note::
       If the call was never connected, the **time_connect** attribute will be `null`, and the **duration** will be `0`.

HTTP request payload example
-----------------------------

The following JSON payload represents a **Call End Event**, including timestamps, call duration, and routing details.

    .. code-block:: json

        {
            "type": "outbound-call-end-event",
            "id": "10-10282FC6-5F632C460006A397-AC8C7700",
            "attributes": {
                "source_ip" : "192.0.2.1",
                "source_port": 5060,
                "call_id" : "3eab288b2e0eb547122434ce0e648bb5",
                "time_start": "2020-03-05T11:05:33.879559+00:00",
                "time_connect": "2020-03-05T11:05:38.879559+00:00",
                "time_end": "2020-03-05T11:05:58.879559+00:00",
                "duration": 10,
                "pop": "NYC",
                "original_src_number": "02089643990",
                "src_number": "123439643990",
                "dst_number": "441158720600",
                "trunk_name": "Trunk 1",
                "rate": "0.004",
                "initial_billing_interval": 1,
                "next_billing_interval": 1,
                "p_charge_info": "<sip:02089643990@customer.example.com;billing-account-id=212>",
                "diversion" : [ "<sip:+123456789@sip.didww.com>;reason=unconditional" ]
            }
        }

.. raw:: html

   <br>

----

.. _termination_cdr_streaming_p_charge_info:

Call Event Attributes
=====================

.. list-table:: Voice OUT (outbound) Call Event Descriptions and Examples
   :header-rows: 1
   :widths: 10 10 40 30

   * - **Attribute**
     - **Type**
     - **Description**
     - **Example**
   * - **type**
     - String
     - Event type. Possible values:

       - `outbound-call-start-event`
       - `outbound-call-connect-event`
       - `outbound-call-end-event`
     - `"outbound-call-start-event"`
   * - **id**
     - String
     - Unique call identifier.

       All events related to the same call will contain the same **id** value.
     - `"10-10282FC6-5F632C460006A397-AC8C7700"`
   * - **attributes**
     - Hash
     - Structure containing all CDR attributes.
     - *See below for attribute details.*
   * - **source_ip**
     - String
     - IP address of the call originator.
     - `"192.0.2.1"`
   * - **source_port**
     - Integer
     - Port of the call originator.
     - `5060`
   * - **call_id**
     - String
     - SIP Call-ID of the call leg between the customer's equipment and DIDWW.

       All events related to the same call will contain the same **call_id** value.
     - `"3eab288b2e0eb547122434ce0e648bb5"`
   * - **time_start**
     - Timestamp
     - Start time when the initial SIP INVITE is received.
     - `"2024-03-05T11:05:33.879559+00:00"`
   * - **time_connect**
     - Timestamp
     - Time of the successful handshake (**200 OK SIP** response).

       If the call was never connected, this value is `null` in the **Call End Event**.
     - `"2024-03-05T11:05:38.879559+00:00"`
   * - **time_end**
     - Timestamp
     - Call disconnection time.
     - `"2024-03-05T11:05:58.879559+00:00"`
   * - **duration**
     - Integer
     - Call duration in seconds.

       For non-connected calls, the duration is `0`.
     - `10`
   * - **pop**
     - String
     - Location of the DIDWW equipment that processed the call.

       See :ref:`DIDWW Point of Presence <presence>`. Possible values:

       - NYC - USA, New York
       - LAC - USA, Los Angeles
       - MIA - USA, Miami
       - FRA - Germany, Frankfurt
       - AMS - Netherlands, Amsterdam
       - SG - Singapore
       - HG - Hong Kong
     - `"NYC"`
   * - **original_src_number**
     - String
     - Incoming Caller ID before any modifications.
     - `"02089643990"`
   * - **src_number**
     - String
     - Incoming Caller ID after applying rewrites.
     - `"123439643990"`
   * - **dst_number**
     - String
     - Call destination number.
     - `"441158720600"`
   * - **trunk_name**
     - String
     - Outbound trunk friendly name.
     - `"Trunk 1"`
   * - **rate**
     - Numeric
     - Customer's outbound call termination rate.
     - `"0.004"`
   * - **initial_billing_interval**
     - Integer
     - Initial billing interval for the outbound call termination.
     - `1`
   * - **next_billing_interval**
     - Integer
     - Next billing interval for the outbound call termination.
     - `1`
   * - **p_charge_info**
     - String
     - `P-Charge-Info` header value received from the call originator.

       This allows customers to add custom information to DIDWW CDR for technical and/or billing purposes.

       See :ref:`Service description <service_termination_sip_details_p_charge_info>` for more details.
     - `"<sip:02089643990@customer.example.com;billing-account-id=212>"`
   * - **diversion**
     - Array of Strings
     - `Diversion` header values received from the call originator.

       The order of headers in the **INVITE** request is preserved.
     - `[ "<sip:+123456789@sip.didww.com>;reason=unconditional" ]`

.. This CSS modifies the appearance of code blocks and admonitions in Sphinx documentation.
.. Removes default borders for a cleaner look.
.. Changes background color to a soft blue (`#F3F7FC`) for better readability.
.. Ensures code blocks have a max width (`60rem`) for layout consistency.
.. Uses monospaced fonts for preformatted text.
.. Adjusts line height for better text clarity.
.. Adds rounded corners (`border-radius: 10px`) for a modern UI.
.. Customizes string color (`.s2` class) for syntax highlighting.
.. Limits the width of admonition boxes (e.g., notes) to align with the layout.

.. raw:: html

    <style>
    .rst-content div[class^=highlight],
    .rst-content pre.literal-block {
        border: 0;
        background: 0;
        background-color: #F3F7FC !important;
        overflow-x: auto;
        color: #2c2c2c;
        margin: 1px 0 24px;
        max-width: 65rem !important;
        box-sizing: content-box;
        border-radius: 10px;
    }

        pre {
            line-height: 125%;
        }

        .rst-content div[class^="highlight"] pre {
            font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", Courier, monospace;
            font-size: 14px;
            background-color: #F3F7FC !important;
            border-radius: 10px;
            color: rgb(44, 44, 44);
            line-height: 1.4;
            border: 0px;
        }

        .rst-content div[class^="highlight"] pre {
            background-color: #F3F7FC !important;
        }

        .highlight .s2 {
            color: rgb(64, 112, 160);
        }

    .admonition.note {
        max-width: 65rem !important;
        }

    </style>

.. _termination_cdr_streaming:

.. |br| raw:: html

   <br />

===============================
Voice OUT Service CDR Streaming
===============================

The **Voice OUT CDR Streamer** enables customers to receive near real-time **Call Detail Records (CDRs)** for outbound calls.

.. important:: CDRs are **delivered within 3 seconds** after call completion to the customer's designated **HTTP endpoint**.

.. raw:: html

   <br>

----

HTTP request payload examples
=============================

The following is an example of an HTTP **POST** request header used for Voice OUT CDR Streaming. It provides key details such as the destination server, content type, encoding, and request size.

    .. code-block:: http

        POST /cdr HTTP/1.1
        Host: 192.0.2.5
        User-Agent: CDR-streamer
        Accept: */*
        Content-Type: text/plain
        Content-Encoding: gzip
        Content-Length: 2358
        Expect: 100-continue

    .. warning::
       The request payload is **gzip-encoded**. Ensure that your API supports **gzip decompression**
       for proper processing of incoming CDRs.

       See `gzip compression <https://en.wikipedia.org/wiki/HTTP_compression>`_ for more details.

.. raw:: html

   <br>

**Example 1: Call Disconnected Before Connection**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example represents a **failed outbound call attempt** where the call was disconnected before establishing a connection:
    - **Call duration is `0` seconds**, meaning the call did not complete successfully.
    - **No `time_connect` value**, indicating the call never reached the destination.
    - **Disconnect reason:** `"Request terminated (Cancel)"`, meaning the call was canceled before completion.
    - **Disconnect code:** `487` (Request Terminated).
    - **Point of Presence (POP):** `"NYC"` (New York data center).

    .. code-block:: json

        {
            "type": "outbound-cdr",
            "id": "3d6af8ac-5ed1-11ea-bc9d-005056845b1e",
            "attributes": {
                "source_ip": "192.0.2.1",
                "call_id": "3eab288b2e0eb547122434ce0e648bb5",
                "call_type": "INTERNATIONAL",
                "time_end": "2025-02-14T14:51:41.894121+00:00",
                "pop": "NYC",
                "disconnect_reason": "Request terminated (Cancel)",
                "price": 0,
                "duration": 0,
                "rate": 0.005,
                "dst_number": "441158720600",
                "time_start": "2025-02-14T14:51:41.894121+00:00",
                "original_src_number": "02089643990",
                "time_connect": null,
                "billing_duration": null,
                "disconnect_code": 487,
                "source_port": 5060,
                "source_protocol": "UDP",
                "success": false,
                "initial_billing_interval": 1,
                "src_number": "123439643990",
                "next_billing_interval": 1,
                "user_agent": "Asterisk PBX 1.8.32.3",
                "trunk_name": "Trunk 1",
                "p_charge_info": "<sip:02089643990@customer.example.com;billing-account-id=212>"
            }
        }

.. raw:: html

   <br>

**Example 2: Call Failed Due to "Not Found" Response**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example represents a **failed outbound call attempt** where the destination number was not found:
    - **Call duration is `0` seconds**, meaning the call did not complete successfully.
    - **No `time_connect` value**, indicating that the call never reached the destination.
    - **Disconnect reason:** `"Not Found"`, meaning the destination number was unavailable.
    - **Disconnect code:** `404` (Not Found).
    - **Point of Presence (POP):** `"FRA"` (Frankfurt data center).

    .. code-block:: json

        {
            "type": "outbound-cdr",
            "id": "1c3f702a-5ed0-11ea-bc9c-005056845b1e",
            "attributes": {
                "source_ip": "192.0.2.2",
                "call_id": "60de10410b36681c5dcb8e7804e72540",
                "call_type": "INTERNATIONAL",
                "time_end": "2025-02-14T14:41:04.894121+00:00",
                "pop": "FRA",
                "disconnect_reason": "Not Found",
                "price": 0,
                "duration": 0,
                "rate": 0.005,
                "dst_number": "448009778097",
                "time_start": "2025-02-14T14:41:04.894121+00:00",
                "original_src_number": "07795622299",
                "time_connect": null,
                "billing_duration": null,
                "disconnect_code": 404,
                "source_port": 5060,
                "source_protocol": "UDP",
                "success": false,
                "initial_billing_interval": 1,
                "src_number": "1345322299",
                "next_billing_interval": 1,
                "user_agent": "Asterisk PBX 1.8.32.3",
                "trunk_name": "Trunk 1",
                "p_charge_info": "<sip:1345322299@customer.example.com;billing-account-id=11232>"
            }
        }

.. raw:: html

   <br>

----

Voice OUT CDR Streaming Attributes
==================================

.. list-table:: Voice OUT (outgoing) service CDR Streaming Descriptions and Examples
   :header-rows: 1
   :widths: 10 7 30 20

   * - **Attribute**
     - **Type**
     - **Description**
     - **Example**
   * - **type**
     - String
     - CDR type. Voice OUT CDRs will be marked as **outbound-cdr**.
     - `"outbound-cdr"`
   * - **id**
     - String
     - Unique CDR identifier in UUID format.
     - `"3d6af8ac-5ed1-11ea-bc9d-005056845b1e"`
   * - **attributes**
     - Hash
     - Structure containing all CDR attributes.
     - *See below for attribute details.*
   * - **time_start**
     - Timestamp
     - Start time when the initial SIP INVITE is received.
     - `"2025-02-14T14:41:04.894121+00:00"`
   * - **time_connect**
     - Timestamp
     - Time after the successful handshake (**200 OK SIP** response).

       If the call was never connected, this value is `null` in the **Call End Event**.
     - `"2025-02-14T14:42:04.894121+00:00"`
   * - **time_end**
     - Timestamp
     - Time when the call was disconnected.
     - `"2025-02-14T14:41:04.894121+00:00"`
   * - **duration**
     - Integer
     - Call duration in seconds. For non-connected calls, the duration is `0`.
     - `10`
   * - **success**
     - Boolean
     - Indicates whether the call was successful (`true`) or not (`false`).
     - `true`
   * - **disconnect_code**
     - Integer
     - DIDWW internal disconnect code.
     - `487`
   * - **disconnect_reason**
     - String
     - DIDWW internal disconnect reason.
     - `"Request terminated (Cancel)"`
   * - **call_id**
     - String
     - SIP Call-ID of the call leg between the customer's equipment and DIDWW.
     - `"3eab288b2e0eb547122434ce0e648bb5"`
   * - **source_ip**
     - String
     - IP address of the call originator.
     - `"192.0.2.1"`
   * - **source_port**
     - Integer
     - Port of the call originator.
     - `5060`
   * - **source_protocol**
     - String
     - SIP transport protocol used between the customer and DIDWW platform.

       Possible values:

           - `UDP`
           - `TCP`
           - `TLS`
     - `"UDP"`
   * - **trunk_name**
     - String
     - Outbound trunk friendly name defined by the customer during trunk creation.
     - `"Trunk 1"`
   * - **call_type**
     - String
     - Call type.

       Possible values:

           - `INTERNATIONAL`
           - `ORIGIN`
           - `LOCAL`
     - `"INTERNATIONAL"`
   * - **src_name**
     - String
     - Incoming caller name.
     - `"Customer Caller"`
   * - **original_src_number**
     - String
     - Incoming Caller-ID before any modifications.
     - `"02089643990"`
   * - **src_number**
     - String
     - Caller-ID after applying number rewrites.
     - `"123439643990"`
   * - **dst_number**
     - String
     - Called destination number.
     - `"441158720600"`
   * - **customer_vat**
     - Numeric
     - Charged VAT amount for the call.
     - `0.00`
   * - **rate**
     - Numeric
     - Customer outbound call termination rate.
     - `0.005`
   * - **initial_billing_interval**
     - Integer
     - Initial billing interval for the outbound call termination.
     - `1`
   * - **next_billing_interval**
     - Integer
     - Next billing interval for the outbound call termination.
     - `1`
   * - **billing_duration**
     - Integer
     - Call duration rounded to the configured billing interval for the outbound call termination.
     - `10`
   * - **price**
     - Numeric
     - Customer accumulated amount for the outbound call termination.
     - `0.004`
   * - **pop**
     - String
     - Location of DIDWW equipment that processed the call.

       See :ref:`DIDWW Point of Presence <presence>`.

       Possible values:

           - `NYC` - USA, New York
           - `LAC` - USA, Los Angeles
           - `MIA` - USA, Miami
           - `FRA` - Germany, Frankfurt
           - `AMS` - Netherlands, Amsterdam
           - `SG` - Singapore
           - `HG` - Hong Kong
     - `"NYC"`
   * - **user_agent**
     - String
     - `User-Agent` and `Server` header values from the customer's gateway.
     - `"Asterisk PBX 1.8.32.3"`
   * - **p_charge_info**
     - String
     - `P-Charge-Info` header value received from the call originator.

       Using this header, customers can add custom information to the DIDWW CDR for technical and billing purposes.

       See :ref:`Service description <service_termination_sip_details_p_charge_info>` for more details.
     - `"<sip:02089643990@customer.example.com;billing-account-id=212>"`

.. raw:: html

   <br>

----

Batching
========

The **CDR Streaming Interface** delivers Call Detail Records (**CDRs**) in batches to optimize data transmission. A single HTTP **POST** request can contain multiple CDRs.

Key Details:
    - The CDRs are separated by new lines.
    - The maximum batch size is 1,000 CDRs per request.
    - The destination API must be capable of processing multiple CDRs within the same request.

Example: CDRs in a Batch
^^^^^^^^^^^^^^^^^^^^^^^^

Below is an example of a payload containing four CDRs.

    .. code-block:: json

        { "type" : "outbound-cdr", "attributes" : { "source_ip" : "1.1.1.1", "call_id" : "J8H0Ngr2KqDI2VHvnM_cug..", "call_type" : "INTERNATIONAL", "time_end" : "2025-05-06T11:31:21.445275+00:00", "pop" : "FRA", "disconnect_reason" : "Bye", "source_protocol" : "UDP", "trunk_name" : "Testing", "time_start" : "2025-05-06T11:31:10.153975+00:00", "p_charge_info" : null, "duration" : 10, "rate" : 0.004, "dst_number" : "18312630056", "price" : 0.0009, "original_src_number" : "1234567890", "time_connect" : "2025-05-06T11:31:11.689451+00:00", "billing_duration" : 10, "disconnect_code" : 200, "source_port" : 55407, "success" : true, "initial_billing_interval" : 1, "src_number" : "1234567890", "next_billing_interval" : 1, "user_agent" : "Z 3.15.40006 rv2.8.20" }, "id" : "a4129ecc-2a6d-11f0-acf8-005056845b1e" }
        { "type" : "outbound-cdr", "attributes" : { "source_ip" : "1.1.1.1", "call_id" : "9RxsZ9Cg49eQyL_4pLMozw..", "call_type" : "INTERNATIONAL", "time_end" : "2025-05-06T11:31:22.004348+00:00", "pop" : "FRA", "disconnect_reason" : "Bye", "source_protocol" : "UDP", "trunk_name" : "Testing", "time_start" : "2025-05-06T11:31:11.095435+00:00", "p_charge_info" : null, "duration" : 10, "rate" : 0.004, "dst_number" : "18312630056", "price" : 0.0009, "original_src_number" : "1234567890", "time_connect" : "2025-05-06T11:31:12.093368+00:00", "billing_duration" : 10, "disconnect_code" : 200, "source_port" : 55407, "success" : true, "initial_billing_interval" : 1, "src_number" : "1234567890", "next_billing_interval" : 1, "user_agent" : "Z 3.15.40006 rv2.8.20" }, "id" : "a4129edb-2a6d-11f0-acf8-005056845b1e" }
        { "type" : "outbound-cdr", "attributes" : { "source_ip" : "1.1.1.1", "call_id" : "tK8RP-FKOat-PQ6w9AGZWg..", "call_type" : "INTERNATIONAL", "time_end" : "2025-05-06T11:31:22.313018+00:00", "pop" : "FRA", "disconnect_reason" : "Bye", "source_protocol" : "UDP", "trunk_name" : "Testing", "time_start" : "2025-05-06T11:31:11.674592+00:00", "p_charge_info" : null, "duration" : 10, "rate" : 0.004, "dst_number" : "18312630056", "price" : 0.0009, "original_src_number" : "1234567890", "time_connect" : "2025-05-06T11:31:13.265197+00:00", "billing_duration" : 10, "disconnect_code" : 200, "source_port" : 55407, "success" : true, "initial_billing_interval" : 1, "src_number" : "1234567890", "next_billing_interval" : 1, "user_agent" : "Z 3.15.40006 rv2.8.20" }, "id" : "a4129ee0-2a6d-11f0-acf8-005056845b1e" }
        { "type" : "outbound-cdr", "attributes" : { "source_ip" : "1.1.1.1", "call_id" : "xhPdn64_8rL6saZuVo0Ehg..", "call_type" : "INTERNATIONAL", "time_end" : "2025-05-06T11:31:23.005127+00:00", "pop" : "FRA", "disconnect_reason" : "Bye", "source_protocol" : "UDP", "trunk_name" : "Testing", "time_start" : "2025-05-06T11:31:12.687149+00:00", "p_charge_info" : null, "duration" : 10, "rate" : 0.004, "dst_number" : "18312630056", "price" : 0.0009, "original_src_number" : "1234567890", "time_connect" : "2025-05-06T11:31:13.816983+00:00", "billing_duration" : 10, "disconnect_code" : 200, "source_port" : 55407, "success" : true, "initial_billing_interval" : 1, "src_number" : "1234567890", "next_billing_interval" : 1, "user_agent" : "Z 3.15.40006 rv2.8.20" }, "id" : "a4129ee9-2a6d-11f0-acf8-005056845b1e" }

    .. note::

       - Ensure that your system is capable of parsing multiple new line separated **JSON objects**.
       - Each CDR object is not enclosed in a larger array or object.

.. raw:: html

   <br>

----

Error Handling
==============

The **CDR Streaming Interface** determines whether a batch of CDRs has been successfully processed based on the HTTP response from the destination API.

Success Criteria:
    - If the API responds with a **2xx HTTP status code**, all CDRs in that request are marked as **processed** and automatically removed from the queue.

Failure & Retry Mechanism:
    - If the API returns a **non-2xx response** (e.g., `4xx` or `5xx`) or the request **times out**, the CDRs **remain in the queue**.
    - A **retry attempt** will occur **after 3 seconds** to ensure delivery.

.. warning::

   1. **Queue Size Limit**
          - The **CDR queue is limited to 10,000 records per customer**.
          - Extended downtime or delays in processing requests may result in **CDR loss** at the customer’s endpoint.
          - The **CDR Streaming mechanism should not be the sole method** for retrieving CDRs.
          - For alternative retrieval methods, refer to the :ref:`API documentation <export_v33>`.

   2. **Timeout Handling**
          - If the **HTTP endpoint does not respond within 10 seconds**, the request **will time out**, triggering an **automatic retry**.
          - Ensure the destination API can handle incoming requests efficiently to prevent unnecessary retries.

   3. **Idempotency**
          - Be aware of possible retries for successfully processed batches due to network issues (sender not received your *2xx HTTP status code*)
          - CDRs `id` is guaranteed to be unique so can be used to ensure exactly once processing by API


:html_theme.sidebar_secondary.remove: true

.. _otp_verification:

================
OTP Verification
================

OTP Verification helps you confirm that a user controls a phone number. DIDWW delivers a
one-time challenge by SMS or phone call, and your application reports the result through the
Verification API.

Use OTP Verification to confirm phone ownership during sign-up, login, account recovery,
two-factor authentication, service provisioning, and other flows that require a verified
number.

Get Started
===========

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`info` **Overview**
      :link: overview
      :link-type: doc
      :text-align: left

      Learn what OTP Verification does, when to use it, and how the main verification
      flow works.

   .. grid-item-card:: :octicon:`rocket` **Getting Started**
      :link: getting-started
      :link-type: doc
      :text-align: left

      Create an OTP application, copy your credentials, and run your first verification.

   .. grid-item-card:: :octicon:`key` **Authentication**
      :link: authentication
      :link-type: doc
      :text-align: left

      Understand supported authentication modes and choose the right mode for your
      integration.

   .. grid-item-card:: :octicon:`broadcast` **Verification Methods**
      :link: verification-methods/index
      :link-type: doc
      :text-align: left

      Compare SMS and phone call verification methods.

   .. grid-item-card:: :octicon:`webhook` **Callbacks**
      :link: callbacks
      :link-type: doc
      :text-align: left

      Approve or reject verification requests from your own backend before delivery.

   .. grid-item-card:: :iconify:`mingcute:ai-fill width=1em height=1em` **AI Best Practices**
      :link: ai-best-practices
      :link-type: doc
      :text-align: left

      Use the documentation, Markdown pages, and OpenAPI spec effectively with AI tools.

API Reference
=============

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`book` **API Overview**
      :link: api-reference/index
      :link-type: doc
      :text-align: left

      Review base URLs, content types, endpoints, and the verification object.

   .. grid-item-card:: :octicon:`play` **Start a Verification**
      :link: api-reference/start-verification
      :link-type: doc
      :text-align: left

      Start a phone-number verification with a selected delivery method.

   .. grid-item-card:: :octicon:`check-circle` **Report a Verification**
      :link: api-reference/report-verification
      :link-type: doc
      :text-align: left

      Submit the OTP code received by the user.

   .. grid-item-card:: :octicon:`search` **Get Verification Status**
      :link: api-reference/get-verification-status
      :link-type: doc
      :text-align: left

      Retrieve the current status of a verification by its identifier.

   .. grid-item-card:: :octicon:`device-mobile` **Use Phone Number Lookup**
      :link: api-reference/get-verification-status-by-number
      :link-type: doc
      :text-align: left

      Get or report the latest verification for a phone number when you do not have the
      verification ID.

   .. grid-item-card:: :octicon:`alert` **Errors and Status Codes**
      :link: api-reference/errors
      :link-type: doc
      :text-align: left

      Look up HTTP statuses, verification statuses, and machine-readable error codes.

SDKs
====

.. grid:: 1 2 2 3
   :gutter: 4
   :padding: 0

   .. grid-item-card:: :octicon:`package` **SDK Overview**
      :link: sdks/index
      :link-type: doc
      :text-align: left

      Compare available and planned SDKs for server-side and mobile integrations.

   .. grid-item-card:: :octicon:`ruby` **Ruby**
      :link: sdks/ruby
      :link-type: doc
      :text-align: left

      Use the Ruby SDK for server-side verification flows and callback signature checks.

   .. grid-item-card:: :octicon:`code` **Python**
      :link: sdks/python
      :link-type: doc
      :text-align: left

      Coming soon.

   .. grid-item-card:: :octicon:`code-square` **Node.js**
      :link: sdks/node
      :link-type: doc
      :text-align: left

      Use the Node.js SDK for server-side verification flows and inbound callback endpoints.

   .. grid-item-card:: :octicon:`device-mobile` **Android**
      :link: sdks/android
      :link-type: doc
      :text-align: left

      Use the Kotlin SDK to integrate OTP Verification into Android applications.

   .. grid-item-card:: :octicon:`device-mobile` **iOS**
      :link: sdks/ios
      :link-type: doc
      :text-align: left

      Use the Swift SDK to integrate OTP Verification into iOS applications.

   .. grid-item-card:: :octicon:`device-mobile` **React Native**
      :link: sdks/react-native
      :link-type: doc
      :text-align: left

      Drive a whole verification from one hook in a React Native application.

   .. grid-item-card:: :octicon:`device-mobile` **Dart and Flutter**
      :link: sdks/dart
      :link-type: doc
      :text-align: left

      Use the Dart SDK to integrate OTP Verification into Flutter applications.

.. toctree::
  :maxdepth: 1
  :hidden:
  :caption: Get Started

   Overview <overview.rst>
   Getting started <getting-started.rst>
   Authentication <authentication.rst>
   Verification methods <verification-methods/index.rst>
   Callbacks <callbacks.rst>
   AI best practices <ai-best-practices>

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: API Reference

   Overview <api-reference/index>
   Start a verification <api-reference/start-verification.rst>
   Report a verification <api-reference/report-verification.rst>
   Get verification status <api-reference/get-verification-status.rst>
   Report a verification by number <api-reference/report-verification-by-number>
   Get verification status by number <api-reference/get-verification-status-by-number>
   Errors and status codes <api-reference/errors.rst>

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: SDKs

   Overview <sdks/index>
   Ruby <sdks/ruby>
   Python <sdks/python>
   Node.js <sdks/node>
   Android <sdks/android>
   iOS <sdks/ios>
   React Native <sdks/react-native>
   Dart and Flutter <sdks/dart>


.. _otp_verification_overview:

========
Overview
========

**OTP Verification** confirms that a user actually controls a phone number. DIDWW delivers a
one-time code by SMS or voice. Your application confirms the user by reporting the code.

The service combines a hosted REST API with client :ref:`SDKs <otp_verification_sdks>`, so
you can drive verifications from your backend, your mobile app, or both. Use it wherever a
real, reachable phone number matters: securing sign-ups and logins, adding a second factor
to sensitive actions, confirming a number before you provision a service, or reducing fraud
and fake accounts.

----

What OTP verification does
==========================

OTP Verification manages the verification attempt from start to finish. After you create an
OTP application and authenticate your request, your application starts a verification for a
destination number and chooses a supported delivery method. DIDWW delivers the challenge,
tracks the attempt, and lets your application report the result or retrieve the latest
status.

A verification has three main parts:

- **Destination**: the phone number you want to verify.
- **Delivery method**: the channel used to send the challenge.
- **Report**: the code that your application sends back to confirm the user.

The API keeps the verification state, returns the current status, and provides
machine-readable error information when the verification cannot be completed.

Supported verification methods
==============================

Every verification delivers a challenge over one channel, chosen per request with the
``delivery_method`` field. SMS and phone call both deliver a numeric **code** for the user to
report.

.. list-table::
   :header-rows: 1
   :widths: 18 16 20 46

   * - Method
     - API value
     - User reports
     - How the user is challenged
   * - :ref:`SMS <otp_verification_method_sms>`
     - ``sms``
     - ``code``
     - A text message carrying the one-time code is sent to the number. The most familiar
       channel for end users.
   * - :ref:`Phone Call <otp_verification_method_phone_call>`
     - ``callout``
     - ``code``
     - A call is placed and reads the one-time code aloud. Useful where SMS is unreliable or
       for landline numbers.

.. note::

   Supported mobile :ref:`SDKs <otp_verification_sdks>` can streamline these flows on the
   device, for example by automatically capturing SMS codes where supported. Over the REST
   API, your application collects the code from the user and reports it.

How a verification works
========================

Every verification follows the same three-step lifecycle regardless of delivery method:

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "signalColor": "#1f2d3d",
       "signalTextColor": "#1f2d3d",
       "activationBkgColor": "#fef3c7",
       "activationBorderColor": "#facc15",
       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d"
     }
   }}%%

   sequenceDiagram
       participant App as Your application
       participant API as Verification API
       participant User as End user

       App->>API: POST /api/v1/verifications (start)
       API->>User: Deliver code / place call
       API-->>App: 201 Created - verification id, status: pending
       User->>App: Enters code
       App->>API: PATCH /api/v1/verifications/{id} (report)
       API-->>App: 200 OK - status: verified / failed
       App->>API: GET /api/v1/verifications/{id} (status, optional)
       API-->>App: 200 OK - current status

1. **Start**: call :ref:`POST /api/v1/verifications <otp_verification_api_start>` with the
   destination number and delivery method. DIDWW routes the request, delivers the challenge,
   and returns a verification ``id`` with status ``pending``.
2. **Report**: when the user submits the code, call
   :ref:`PATCH /api/v1/verifications/{id} <otp_verification_api_report>` with the ``code``.
   The response carries the resulting status.
3. **Status**: at any time, call
   :ref:`GET /api/v1/verifications/{id} <otp_verification_api_status>` to read the current
   status.

Each verification is short-lived: it expires two minutes after it is created, and the value
may be reported at most three times before the verification fails.

Using the SDKs and the REST API
===============================

You can integrate at whichever layer fits your architecture:

- **Backend, server-to-server**: start and report verifications directly from your server
  with the REST API or a server :ref:`SDK <otp_verification_sdks>`, keeping your application
  secret private. This is the simplest setup.
- **Untrusted clients with a gate**: when a verification originates from a device or browser
  that only holds a public key, add a :ref:`request callback <otp_verification_callbacks>`.
  DIDWW calls your backend before delivering anything, and your server approves or rejects
  the attempt in real time.

Whichever layer you choose, authenticate with the right
:ref:`auth mode <otp_verification_authentication>` for the trust level of the caller, and
consider a request callback to keep control on your own server.

Verification status
===================

The ``status`` field on a verification is one of:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Status
     - Meaning
   * - ``pending``
     - The verification has been started and is awaiting the user's report.
   * - ``verified``
     - The reported code matched, and the number is confirmed.
   * - ``failed``
     - The verification could not be completed because of a wrong code, too many attempts,
       delivery failure, or expiry before a correct report.
   * - ``expired``
     - The verification lifetime elapsed without a successful report.
   * - ``denied``
     - The verification was rejected before delivery, typically by your
       :ref:`request callback <otp_verification_callbacks>`.

When a verification is not successful, the ``error_code`` field carries a machine-readable
explanation and ``error_detail`` carries the matching human-readable text. See
:ref:`Errors and Status Codes <otp_verification_api_errors>` for the full list of error codes
and HTTP status codes.

Next steps
==========

Start with :ref:`Getting Started <otp_verification_getting_started>` to create an OTP
application and prepare your credentials. Then review :ref:`Authentication
<otp_verification_authentication>`, choose the :ref:`Verification Methods
<otp_verification_methods>` that fit your product flow, or pick an
:ref:`SDK <otp_verification_sdks>` for your language.

If you use AI coding tools to build an integration, see :ref:`AI Best Practices
<otp_verification_ai>`.


.. _otp_verification_ai:

=================
AI Best Practices
=================

AI coding assistants can help you integrate the DIDWW OTP Verification API by scaffolding
requests, wiring up callbacks, or explaining fields. This page explains how to provide the
current documentation and relevant integration context, then validate the generated output.

.. warning::

   Always review code produced by an AI assistant before you ship it. Confirm it matches the
   current :ref:`API Reference <otp_verification_api_reference>`, handles errors, and keeps
   your application secret out of client-side code. Treat generated code as a draft, not a
   finished integration.

   Never include application secrets, real OTP codes, customer phone numbers, or callback
   payloads containing personal data in prompts. Use placeholders or sanitized examples.

----

Point your assistant at ``llms.txt``
====================================

The documentation site publishes an ``llms.txt`` index, which is a plain-text map of the
documentation designed for language models. If your AI tool can open links, provide this URL
so it can find the relevant documentation pages:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - File
     - URL
   * - Index
     - `https://doc.didww.com/llms.txt <https://doc.didww.com/llms.txt>`_
   * - Full text
     - `https://doc.didww.com/llms-full.txt <https://doc.didww.com/llms-full.txt>`_

Use ``llms.txt`` with tools that can retrieve the linked pages. Use ``llms-full.txt`` when the
tool accepts a single documentation file and has enough context capacity to process it. If the
tool cannot access URLs, provide the relevant file contents directly.

Read any page as Markdown
=========================

Current documentation pages are also available as Markdown. Replace the page's ``.html``
extension with ``.md``:

.. list-table::
   :header-rows: 1
   :widths: 50 50

   * - HTML page
     - Markdown version
   * - ``.../otp-verification/index.html``
     - ``.../otp-verification/index.md``
   * - ``.../otp-verification/api-reference/start-verification.html``
     - ``.../otp-verification/api-reference/start-verification.md``

The Markdown version contains the page content and examples without the website navigation or
page layout.

.. tip::

   When you ask an assistant to write against the API, provide the specific Markdown pages
   relevant to the task, such as the :ref:`Start <otp_verification_api_start>`,
   :ref:`Report <otp_verification_api_report>`, and :ref:`Errors
   <otp_verification_api_errors>` references. This helps it use documented field names and
   status codes.

Use the OpenAPI specification
=============================

A machine-readable OpenAPI 3.0 description of the Verification API is available as a JSON
file:

.. button-link:: ../openapi/verification_api.json
   :class: didww-download-button

   :octicon:`file-code` OpenAPI specification

It defines the supported endpoints, request bodies, and response schemas. Provide it to tools
that consume OpenAPI, such as code generators, tools that generate requests, or assistants
that can read the specification.

Use the OpenAPI specification for endpoint paths, fields, data types, and response schemas.
Use the documentation pages for authentication requirements, callback behavior, verification
lifecycles, and integration guidance.

Provide integration context
===========================

Tell the assistant which environment, authentication mode, delivery method, programming
language, and SDK you are using. Also state whether the OTP application has a callback URL.

Ask the assistant to use only fields and values documented in the API Reference page or OpenAPI
specification and to identify any assumptions it makes.

Validate generated integrations
===============================

Test generated requests in the sandbox before using them in production. Confirm that the
integration handles unsuccessful HTTP responses, denied verifications, expiration, delivery
failures, and incorrect user input.

Use credentials created in the same environment as the selected API base URL. See
:ref:`Choose an environment <otp_verification_environments>`.

Use the :ref:`API Reference <otp_verification_api_reference>` to find the relevant endpoint
documentation. Validate generated request fields against the
`OpenAPI specification <../openapi/verification_api.json>`_ and compare
error handling with
:ref:`Errors and Status Codes <otp_verification_api_errors>`.


.. _otp_verification_api_errors:

=======================
Errors and status codes
=======================

The Verification API reports request failures with a non-successful HTTP status and an
``errors`` array. A successfully created or retrieved verification can also contain an
unsuccessful outcome through its ``status``, ``error_code``, and ``error_detail`` fields.

Use the HTTP status to identify the error category and ``errors[].code`` to handle a specific
request failure. For a verification returned under ``data``, inspect ``status`` first and use
``error_code`` to determine why the verification failed, expired, or was denied.

HTTP error status codes
=======================

.. list-table::
   :header-rows: 1
   :widths: 22 23 55

   * - Status
     - Applies to
     - When it occurs
   * - ``400 Bad Request``
     - Requests with a JSON body
     - The top-level ``data`` object is missing or invalid, or the request body cannot be
       parsed.
   * - ``401 Unauthorized``
     - All endpoints
     - Credentials are missing or invalid, or the authentication mode is below the minimum
       configured for the OTP application. See
       :ref:`Authentication <otp_verification_authentication>`.
   * - ``402 Payment Required``
     - Start a verification
     - The account balance is insufficient to start a verification.
   * - ``404 Not Found``
     - Status and report endpoints
     - No matching verification exists for the supplied identifier or number. A by-number
       report can also return this status when no verification can receive the report.
   * - ``422 Unprocessable Content``
     - Start and report endpoints
     - The JSON structure is valid, but one or more values fail validation or the submitted
       code cannot be accepted.
   * - ``5xx Server Error``
     - Any endpoint
     - The API or an intermediary encountered an unexpected failure. An API-generated
       response may contain ``internal_error``; a gateway or proxy response may not use the
       standard error format.

Error response object
=====================

Every error response generated by the Verification API contains a top-level ``errors`` array.
A response can contain more than one error object, for example when several request fields
fail validation.

.. list-table::
   :header-rows: 1
   :widths: 24 18 58

   * - Field
     - Type
     - Description
   * - ``errors``
     - Array of objects
     - The request errors returned by the API.
   * - ``errors[].code``
     - ``string``
     - Stable, machine-readable error code. Use this value in application logic.
   * - ``errors[].detail``
     - ``string``
     - Fixed human-readable text associated with ``code``. Display or log it when useful,
       but do not parse it or use it for branching.

The following response contains one request validation error:

.. code-block:: json

   {
     "errors": [
       {
         "code": "delivery_method_invalid",
         "detail": "delivery method is invalid"
       }
     ]
   }

.. note::

   A network failure, timeout, or response generated by a proxy can occur before the
   Verification API returns JSON. Handle these failures separately instead of assuming that
   an ``errors`` array is available.

HTTP error codes
================

The following tables list the error codes published for the Verification API. New codes may
be added over time. Preserve an unknown raw code and handle it using the HTTP status instead
of rejecting or failing to decode the response.

Request validation codes
------------------------

.. list-table::
   :header-rows: 1
   :widths: 29 12 34 25

   * - Code
     - Status
     - Meaning
     - Handling
   * - ``destination_blank``
     - ``422``
     - ``destination`` is empty or missing.
     - Supply a destination number.
   * - ``destination_invalid``
     - ``422``
     - ``destination`` is not a valid phone number.
     - Correct the number before retrying.
   * - ``delivery_method_blank``
     - ``422``
     - ``delivery_method`` is empty or missing.
     - Supply a delivery method.
   * - ``delivery_method_inclusion``
     - ``422``
     - ``delivery_method`` is outside the supported list.
     - Use ``sms`` or ``callout``.
   * - ``delivery_method_invalid``
     - ``422``
     - The delivery method is invalid for the operation. On a report request, it can mean
       that the method does not match the verification.
     - Use the method selected when the verification was started.
   * - ``languages_invalid``
     - ``422``
     - ``sms.languages`` or ``callout.languages`` contains an invalid language tag or value.
       A well-formed tag with no template or recording is **not** an error: it falls back to
       ``en-US``.
     - Supply valid BCP 47 language tags. See
       :ref:`SMS languages <otp_verification_sms_languages>` and
       :ref:`phone call languages <otp_verification_callout_languages>`.
   * - ``app_hash_invalid``
     - ``422``
     - ``sms.app_hash`` is not exactly 11 characters from ``A-Z``, ``a-z``, ``0-9``, ``+``,
       and ``/``.
     - Correct the Android SMS Retriever application hash or omit it.
   * - ``code_blank``
     - ``422``
     - ``code`` is empty or missing for an SMS or phone-call report.
     - Supply the code received by the user.
   * - ``destination_not_supported_for_channel``
     - ``422``
     - The destination cannot be verified with the selected delivery method.
     - Choose another supported method or destination.

Report submission codes
-----------------------

.. list-table::
   :header-rows: 1
   :widths: 25 12 38 25

   * - Code
     - Status
     - Meaning
     - Handling
   * - ``code_invalid``
     - ``422``
     - The submitted SMS or phone-call code is incorrect.
     - Accept another value only if the verification remains active. The report counts
       toward the attempt limit.
   * - ``already_verified``
     - ``422``
     - The verification succeeded previously, but the value submitted in this request is
       invalid.
     - Do not treat this response as confirmation of the current submission.
   * - ``not_ready_to_report``
     - ``422``
     - Challenge delivery has not reached a state in which the value can be reported.
     - Wait for dispatch to complete, then submit the value again.
   * - ``validation_failed``
     - ``422``
     - The request failed a validation without a more specific code.
     - Inspect the other error objects and correct the request.

.. warning::

   ``already_verified`` does not verify the value supplied in the current request. Do not use
   it to grant access or confirm the current user.

Authentication, account, and lookup codes
-----------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 27 17 56

   * - Code
     - Status
     - Meaning
   * - ``parameter_missing``
     - ``400``
     - The request body does not contain a valid top-level ``data`` object.
   * - ``unauthorized``
     - ``401``
     - Authentication failed. The response is intentionally generic and does not identify
       which credential or account condition caused the failure.
   * - ``balance_insufficient``
     - ``402``
     - The account balance is insufficient to start a verification.
   * - ``not_found``
     - ``404``
     - No matching verification was found for the authenticated OTP application.
   * - ``internal_error``
     - ``422`` or ``5xx``
     - The request could not be completed because of an internal API error.

Verification outcome codes
==========================

When the API returns a verification object, ``status`` describes its current state. For a
``failed``, ``expired``, or ``denied`` verification, ``error_code`` contains the
machine-readable reason and ``error_detail`` contains the corresponding human-readable text.
Both fields are ``null`` while the verification is ``pending`` and after it becomes
``verified``.

.. list-table::
   :header-rows: 1
   :widths: 25 20 12 25 18

   * - ``error_code``
     - ``error_detail``
     - Status
     - Meaning
     - Handling
   * - ``dispatch_failed``
     - ``failed to deliver``
     - ``failed``
     - The challenge could not be delivered to the destination.
     - Start a new verification or choose another delivery method.
   * - ``expired``
     - ``expired``
     - ``expired``
     - The verification lifetime elapsed before successful reporting.
     - Start a new verification.
   * - ``too_many_attempts``
     - ``too many attempts``
     - ``failed``
     - An incorrect code was reported too many times.
     - Start a new verification. Do not submit another value to this verification.
   * - ``stale_dispatch``
     - ``number unreachable``
     - ``failed``
     - The destination could not be reached during challenge delivery.
     - Check the number or choose another delivery method.
   * - ``application_deleted``
     - ``application deleted``
     - ``failed``
     - The OTP application was deleted while the verification was in progress.
     - Use an active OTP application and start a new verification.
   * - ``superseded``
     - ``superseded``
     - ``failed``
     - A newer verification for the same application and number replaced this one.
     - Continue with the newer verification.
   * - ``denied_missing_callback_url``
     - ``application has no callback_url``
     - ``denied``
     - The start request used ``public`` authentication, but the OTP application has no
       callback URL configured.
     - Configure a callback URL before starting another verification.
   * - ``denied_by_callback``
     - ``your callback denied the request``
     - ``denied``
     - The :ref:`request callback <otp_verification_callbacks>` returned ``deny``.
     - Review the authorization decision made by your backend.
   * - ``denied_invalid_callback_response``
     - ``callback response was invalid``
     - ``denied``
     - The callback timed out or returned an unusable response, such as a non-``2xx`` status,
       invalid JSON, unsupported action, or body larger than 8 KB.
     - Correct the callback endpoint before starting another verification.

``too_many_attempts`` can first appear as ``errors[].code`` when a report is rejected. A
later status request returns the completed verification with ``status`` ``failed`` and
``error_code`` ``too_many_attempts``.

Handling errors safely
======================

1. Check the HTTP status to determine whether the API returned a successful response or an
   error response.
2. For a non-successful response, inspect every object in ``errors`` and branch on ``code``.
3. For a verification returned under ``data``, inspect ``status`` and then ``error_code``.
4. Preserve unknown codes and handle them using the HTTP status or verification status. Do
   not fail response decoding only because a new code is introduced.
5. Use ``detail`` and ``error_detail`` for display or logging only. Do not parse them or use
   them as application logic.

.. warning::

   A report request can consume one of the allowed attempts. If a timeout or connection
   failure makes the result uncertain, retrieve the verification status before submitting
   the code again.


.. _otp_verification_api_status:

=======================
Get verification status
=======================

Retrieve the current state of a verification by using the ``id`` returned when the
verification was started. Use this endpoint to determine whether the verification is still
pending or has reached a final outcome.

The request only reads the verification. It does not change its state or consume a report
attempt. To retrieve a verification without storing its ``id``, use
:ref:`Get verification status by number <otp_verification_api_status_by_number>`.

Request
=======

HTTP method: ``GET``

Path: ``/api/v1/verifications/{id}``

Path parameters
---------------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Name
     - Type
     - Description
   * - ``id``
     - ``string``
     - Verification identifier (UUID) returned by
       :ref:`Start a verification <otp_verification_api_start>`.

Response
========

When the verification is found, the endpoint returns ``200 OK`` with the
:ref:`verification object <otp_verification_object_reference>` under a top-level ``data``
key. Authentication and lookup errors return an ``errors`` array.

The following table lists the HTTP status codes returned by this endpoint:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Status
     - Meaning
   * - ``200 OK``
     - The verification was found. Inspect ``status``, ``error_code``, and ``error_detail``
       to determine its current state and outcome.
   * - ``401 Unauthorized``
     - Authentication failed, credentials are missing or invalid, or the authentication mode
       is below the minimum configured for the OTP application.
   * - ``404 Not Found``
     - No verification with the specified ``id`` exists for the OTP application, or it passed
       the :ref:`retention period <otp_verification_retention>`.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the error response
structure and available error codes.

Interpreting the status
-----------------------

The ``status`` field describes the verification state when the request is processed:

.. list-table::
   :header-rows: 1
   :widths: 22 78

   * - Status
     - Meaning
   * - ``pending``
     - The verification is active and has not reached a final outcome. The API may still be
       delivering the challenge or waiting for the user to submit a code.
   * - ``verified``
     - The submitted code was accepted, and the phone number was verified.
   * - ``failed``
     - The verification could not be completed. Inspect ``error_code`` for the reason.
   * - ``expired``
     - The verification expired before a correct value was accepted.
   * - ``denied``
     - The verification was rejected before challenge delivery. Inspect ``error_code`` for
       the reason.

Only ``pending`` can transition to another status. Stop checking the verification after it
becomes ``verified``, ``failed``, ``expired``, or ``denied``.

A ``pending`` response is a snapshot of the verification at the time of the request. Send
another status request later when your application needs the latest state.

.. _otp_verification_retention:

Retention
---------

A verification stays readable for at least 24 hours after it reaches a final status. Once that
period passes, the verification is removed, and both this endpoint and
:ref:`Get verification status by number <otp_verification_api_status_by_number>` answer
``404 Not Found``. Store the outcome in your own system if your application needs it later.

Examples
========

The REST API example uses HTTP Basic authentication. See
:ref:`REST API authentication <otp_verification_authentication>` for credential and header
requirements.

The SDK examples assume that the corresponding SDK is installed and initialized, and that
the verification returned by the start operation is available. See the
:ref:`Ruby SDK <otp_verification_sdk_ruby>`,
:ref:`iOS SDK <otp_verification_sdk_ios>`, and
:ref:`Android SDK <otp_verification_sdk_android>`.

The identifier, expiration time, and fee shown in the examples are illustrative.

REST API
--------

Send a ``GET`` request containing the verification ``id`` in the path. The following
example returns an active SMS verification with ``status`` ``pending``:

.. http:example:: curl

   GET /api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 HTTP/1.1
   Host: verification.didww.com
   Accept: application/json
   Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "data": {
       "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
       "destination": "4915112345678",
       "delivery_method": "sms",
       "fee": "0.06",
       "status": "pending",
       "error_code": null,
       "error_detail": null,
       "expires_at": "2026-07-15T10:02:00.000Z",
       "sms": {
         "template": "Your code is {{CODE}}",
         "language": "en-US",
         "interception_timeout": 120
       }
     }
   }

The request is the same for every delivery method. Phone call responses do not include an
``sms`` object.

Ruby SDK
--------

The Ruby SDK sends a ``GET`` request when ``get_verification(...)`` is called and returns a
verification object containing the current state.

.. code-block:: ruby

   verification = client.get_verification(
     "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
   )

   verification.status    # => "pending"
   verification.pending?  # => true
   verification.finished? # => false

Use ``finished?`` to stop checking after the verification reaches a final status.

iOS SDK
-------

The iOS SDK sends a ``GET`` request when ``status(...)`` is called and returns a
``VerificationResult`` containing the current state.

.. code-block:: swift

   let current = try await client.status(verification)

   current.status            // .pending
   current.status.isTerminal // false

Use ``status.isTerminal`` to stop checking after the verification reaches a final status.

Android SDK
-----------

The Android SDK does not provide a separate ``status()`` method and does not poll this
endpoint. For a verification started through the SDK, continue using the single
``handle.states`` collection created for that verification. The flow reports the states
produced by the active SDK verification process:

.. code-block:: kotlin

   viewModelScope.launch {
       handle.states.collect { state ->
           when (state) {
               is VerificationState.AwaitingInput ->
                   println("pending")
               is VerificationState.Verified ->
                   println("verified")
               is VerificationState.Failed ->
                   println("failed: ${state.reason}")
               VerificationState.Expired ->
                   println("expired")
               is VerificationState.Denied ->
                   println("denied")
               is VerificationState.SetupError ->
                   println("denied: ${state.code}")
               else -> Unit
           }
       }
   }

``VerificationState.AwaitingInput`` corresponds to API status ``pending``. ``Verified``,
``Expired``, and ``Denied`` correspond to the matching final API statuses. ``Failed`` can
represent either API status ``failed`` or an SDK-side failure; inspect ``state.reason`` to
distinguish them. ``SetupError`` identifies an OTP application configuration problem.

When an Android application needs an explicit status refresh outside the active handle, call
this REST endpoint from your backend.


.. _otp_verification_api_status_by_number:

=================================
Get verification status by number
=================================

Retrieve the latest verification associated with a phone number. Use this endpoint when your
application has the destination number but did not store the verification ``id`` returned by
the start request.

The lookup only reads the verification. It does not create a new verification, change its
state, or consume a report attempt. To retrieve a specific verification by its ``id``, use
:ref:`Get verification status <otp_verification_api_status>`.

Request
=======

HTTP method: ``GET``

Path: ``/api/v1/verifications/by_number/{number}``

Path parameters
---------------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Name
     - Type
     - Description
   * - ``number``
     - ``string``
     - Destination phone number in E.164 format. The leading ``+`` is optional. When the
       leading ``+`` is included in the URL path, percent-encode it as ``%2B``.

Response
========

When a verification is found, the endpoint returns ``200 OK`` with the
:ref:`verification object <otp_verification_object_reference>` under a top-level ``data``
key. Authentication and lookup errors return an ``errors`` array.

The following table lists the HTTP status codes returned by this endpoint:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Status
     - Meaning
   * - ``200 OK``
     - A verification was found for the specified number. Inspect ``status``, ``error_code``,
       and ``error_detail`` to determine its current state and outcome.
   * - ``401 Unauthorized``
     - Authentication failed, credentials are missing or invalid, or the authentication mode
       is below the minimum configured for the OTP application.
   * - ``404 Not Found``
     - No verification exists for the specified number under the OTP application, either
       because none was started or because the records passed the
       :ref:`retention period <otp_verification_retention>`.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the error response
structure and available error codes. See
:ref:`Get verification status <otp_verification_api_status>` for status meanings and
terminal-state guidance.

Which verification is returned
------------------------------

The lookup is scoped to the authenticated OTP application and returns the **most recently
created** verification for the number, whatever its status. It resolves by recency alone and
does not search for an active verification.

A finished verification is therefore returned whenever it is the newest record for the
number, and remains available for the :ref:`retention period <otp_verification_retention>`.
Starting another verification for the same number makes later by-number lookups resolve to
the newer record.

A newer record can also be a verification that was denied at start. A denied start does not
supersede anything, so it becomes the newest record while an earlier verification for the
same number is still ``pending``, and the by-number lookup returns the denied one. Read
``status`` and ``id`` from the response rather than assuming the returned verification is the
live one.

.. note::

   Use the by-id endpoint when you must retrieve one specific verification. A by-number
   lookup can resolve to a different record after another verification is started for the
   same application and phone number.

Examples
========

The REST API example uses HTTP Basic authentication. See
:ref:`REST API authentication <otp_verification_authentication>` for credential and header
requirements.

The SDK examples assume that the corresponding SDK is installed and initialized. See the
:ref:`Ruby SDK <otp_verification_sdk_ruby>`,
:ref:`iOS SDK <otp_verification_sdk_ios>`, and
:ref:`Android SDK <otp_verification_sdk_android>`.

The identifier, expiration time, and fee shown in the examples are illustrative.

REST API
--------

Send a ``GET`` request with the destination number in the path. The following example omits
the leading ``+`` so no path encoding is required:

.. http:example:: curl

   GET /api/v1/verifications/by_number/4915112345678 HTTP/1.1
   Host: verification.didww.com
   Accept: application/json
   Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "data": {
       "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
       "destination": "4915112345678",
       "delivery_method": "sms",
       "fee": "0.06",
       "status": "pending",
       "error_code": null,
       "error_detail": null,
       "expires_at": "2026-07-15T10:02:00.000Z",
       "sms": {
         "template": "Your code is {{CODE}}",
         "language": "en-US",
         "interception_timeout": 120
       }
     }
   }

The request is the same for every delivery method. Phone call responses do not include an
``sms`` object.

Ruby SDK
--------

The Ruby SDK sends the by-number ``GET`` request when
``get_verification_by_number(...)`` is called. It handles path encoding and returns a
verification object containing the current state.

.. code-block:: ruby

   verification = client.get_verification_by_number(
     "+4915112345678"
   )

   verification.id        # => "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
   verification.status    # => "pending"
   verification.pending?  # => true
   verification.finished? # => false

Use ``finished?`` to determine whether the returned verification has reached a final status.

iOS SDK
-------

The iOS SDK sends the by-number ``GET`` request when ``status(number:)`` is called and
returns a ``VerificationResult``. It normalizes the supplied number to digits before building
the request path.

.. code-block:: swift

   let current = try await client.status(
       number: "+49 151 1234 5678"
   )

   current.id                // "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
   current.status            // .pending
   current.status.isTerminal // false

If the supplied value contains no digits, the SDK throws
``VerificationError.invalidNumber`` before sending a request.

Android SDK
-----------

Use ``resume(...)`` to look up the verification associated with a number and return a new
``VerificationHandle`` for it. Calling ``resume(...)`` does not send the request. The SDK
sends the by-number ``GET`` request when ``handle.states`` is first collected.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: kotlin

         val handle = didww.resume(
             destination = "+4915112345678",
             method = DeliveryMethod.SMS,
         )

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: kotlin

         val handle = didww.resume(
             destination = "+4915112345678",
             method = DeliveryMethod.CALLOUT,
         )

Collect the returned handle exactly once:

.. code-block:: kotlin

   viewModelScope.launch {
       handle.states.collect { state ->
           when (state) {
               is VerificationState.AwaitingInput ->
                   println("pending: ${state.verificationId}")
               is VerificationState.Verified ->
                   println("verified: ${state.verificationId}")
               is VerificationState.Failed ->
                   println("lookup or verification failed: ${state.reason}")
               VerificationState.Expired ->
                   println("expired")
               is VerificationState.Denied ->
                   println("denied")
               is VerificationState.SetupError ->
                   println("configuration error: ${state.code}")
               else -> Unit
           }
       }
   }

For an unfinished verification, the flow emits ``VerificationState.AwaitingInput`` and the
handle can continue accepting submitted values. If the resolved verification has already
finished, the flow emits its terminal state. If no verification exists for the number, it
emits ``VerificationState.Failed`` with ``ApiErrorCode.NOT_FOUND``.

The ``method`` argument selects the channel-specific client behavior, including automatic SMS
capture. The delivery method returned by the API remains authoritative and is exposed through
``VerificationState.AwaitingInput.deliveryMethod``.


.. _otp_verification_api_reference:

=============
API reference
=============

The Verification API is a JSON REST API for starting, reporting, and checking phone number
verifications. All endpoints use the ``/api/v1`` base path and require an
``Authorization`` header. See :ref:`Authentication <otp_verification_authentication>`.

Base URLs
=========

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Environment
     - Base URL
   * - Production
     - ``https://verification.didww.com``
   * - Sandbox
     - ``https://verification-sandbox.didww.com``

.. note::

   Use the sandbox environment to test your integration without charging your account or
   contacting real destinations. Use credentials created in the same environment as the
   selected base URL. Sandbox and production credentials are not interchangeable. See
   :ref:`Choose an environment <otp_verification_environments>`.

Endpoints
=========

.. list-table::
   :header-rows: 1
   :widths: 15 40 45

   * - Method
     - Path
     - Description
   * - ``POST``
     - :ref:`/api/v1/verifications <otp_verification_api_start>`
     - Start a verification.
   * - ``PATCH`` / ``PUT``
     - :ref:`/api/v1/verifications/{id} <otp_verification_api_report>`
     - Report the code the user submitted.
   * - ``GET``
     - :ref:`/api/v1/verifications/{id} <otp_verification_api_status>`
     - Get the current status of a verification.
   * - ``PATCH`` / ``PUT``
     - :ref:`/api/v1/verifications/by_number/{number} <otp_verification_api_report_by_number>`
     - Report the code for the latest verification associated with a phone number.
   * - ``GET``
     - :ref:`/api/v1/verifications/by_number/{number} <otp_verification_api_status_by_number>`
     - Get the status of the latest verification for a phone number.

Request and response format
===========================

Send request bodies with ``Content-Type: application/json`` and request JSON responses with
``Accept: application/json``.

Successful endpoint responses return the verification under a top-level ``data`` key.
Unsuccessful HTTP responses return an ``errors`` array. See
:ref:`Errors and status codes <otp_verification_api_errors>`.

OpenAPI specification
=====================

A machine-readable OpenAPI 3.0 description of the Verification API is available as a JSON
file:

.. button-link:: ../../openapi/verification_api.json
   :class: didww-download-button

   :octicon:`file-code` OpenAPI specification

Import it into Postman, Insomnia, or an OpenAPI code generator, or point an AI assistant at
it. See :ref:`AI best practices <otp_verification_ai>` for guidance on using the specification
with AI tools.

.. _otp_verification_object_reference:

The verification object
=======================

The start, report, and status endpoints all return the same verification object under a
top-level ``data`` key.

.. list-table::
   :header-rows: 1
   :widths: 20 15 20 45

   * - Field
     - Type
     - Availability
     - Description
   * - ``id``
     - ``string``
     - Always
     - Verification identifier (UUID).
   * - ``destination``
     - ``string``
     - Always
     - Destination number normalized to E.164 without a leading ``+``.
   * - ``delivery_method``
     - ``string``
     - Always
     - The method used to deliver the verification challenge. Supported values are ``sms``
       and ``callout``.
   * - ``fee``
     - ``string``
     - Always
     - Quoted verification fee including VAT, represented as a decimal string, for example
       ``"0.06"``. The fee is charged only when the verification becomes ``verified``.
       Delivery costs are billed separately.
   * - ``status``
     - ``string``
     - Always
     - The current state of the verification. Supported values are ``pending``, ``verified``,
       ``failed``, ``expired``, and ``denied``.
   * - ``error_code``
     - ``string``
     - Always (nullable)
     - Machine-readable reason for a failed, expired, or denied verification. The value is
       ``null`` when ``status`` is ``pending`` or ``verified``. See
       :ref:`Errors <otp_verification_api_errors>`.
   * - ``error_detail``
     - ``string``
     - Always (nullable)
     - Fixed human-readable text for ``error_code``. It is ``null`` whenever ``error_code``
       is ``null``. Display this text when needed, but use ``error_code`` in application
       logic.
   * - ``expires_at``
     - ``string``
     - Always
     - When the verification expires, in ISO 8601 format.
   * - ``sms``
     - ``object``
     - SMS only
     - Contains ``template``, ``language``, and ``interception_timeout``. Includes
       ``app_hash`` only when it was accepted and stored for the verification. See
       :ref:`SMS <otp_verification_method_sms>`.
   * - ``callout``
     - ``object``
     - Phone call only
     - Contains ``language``. See :ref:`Phone call <otp_verification_method_phone_call>`.

Each response includes at most one delivery-specific object, named after ``delivery_method``.

Both ``sms.language`` and ``callout.language`` report the language the API **selected**,
which is not necessarily the first one requested. Compare the returned tag with the list you
sent to detect a fallback to ``en-US``.


.. _otp_verification_api_report:

=====================
Report a verification
=====================

Submit the code the user received by SMS or phone call. The endpoint identifies the
verification by the ``id`` returned when it was started and checks the submitted code against
that verification.

A correct value changes a pending verification to ``verified``. An incorrect value can leave
the verification available for another attempt until the attempt limit is reached. Reporting
a verification that has already reached a terminal state does not reopen or change it.

To submit a value without storing the verification ``id``, use
:ref:`Report a verification by number <otp_verification_api_report_by_number>`.

Request
=======

HTTP method: ``PATCH`` (``PUT`` is accepted as an alias)

Path: ``/api/v1/verifications/{id}``

Path parameters
---------------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Name
     - Type
     - Description
   * - ``id``
     - ``string``
     - Verification identifier (UUID) returned by
       :ref:`Start a verification <otp_verification_api_start>`.

Request body
------------

The request body contains a top-level ``data`` object. Use ``code`` for both ``sms`` and
``callout``.

.. list-table::
   :header-rows: 1
   :widths: 22 18 16 44

   * - Field
     - Type
     - Required
     - Description
   * - ``delivery_method``
     - ``string``
     - Yes
     - Must match the method used to start the verification. Supported values are ``sms`` and
       ``callout``.
   * - ``code``
     - ``string``
     - Yes
     - The code the user received by SMS or phone call.

Response
========

When the API accepts the report request, it returns ``200 OK`` with the
:ref:`verification object <otp_verification_object_reference>` under a top-level ``data``
key. Authentication, lookup, and validation errors return an ``errors`` array.

The following table lists the HTTP status codes returned by this endpoint:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Status
     - Meaning
   * - ``200 OK``
     - The report was processed. Inspect the returned ``status`` and ``error_code`` to
       determine the current verification state.
   * - ``401 Unauthorized``
     - Authentication failed, credentials are missing or invalid, or the authentication mode
       is below the minimum configured for the OTP application.
   * - ``404 Not Found``
     - No verification with the specified ``id`` exists for the OTP application.
   * - ``422 Unprocessable Content``
     - The submitted report could not be accepted. This includes an incorrect code or a
       mismatched ``delivery_method``.

A correct code returns ``200 OK`` with ``status`` ``verified``. An incorrect code returns
``422 Unprocessable Content`` with ``code_invalid``. The verification remains available for
another report until the attempt limit is reached. After three unsuccessful reports, it
becomes ``failed`` with ``error_code`` ``too_many_attempts``.

If the challenge has not yet been dispatched, the API can return ``422 Unprocessable
Content`` with ``not_ready_to_report``. Submit the value again after the challenge has been
sent or the call has been placed.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the error response
structure and available error codes.

.. warning::

   Each report can consume one of the three allowed attempts. Do not automatically retry a
   report after a timeout or another ambiguous network failure. Check the verification status
   before deciding whether the user should submit the value again.

Examples
========

The REST API examples use HTTP Basic authentication. See
:ref:`REST API authentication <otp_verification_authentication>` for credential and header
requirements.

The SDK examples assume that the corresponding SDK is installed and initialized, and that
the verification returned by the start operation is available. See the
:ref:`Ruby SDK <otp_verification_sdk_ruby>`,
:ref:`iOS SDK <otp_verification_sdk_ios>`, and
:ref:`Android SDK <otp_verification_sdk_android>`.

The identifiers, expiration times, fees, and codes shown in the examples are illustrative.

REST API
--------

Send a ``PATCH`` request with the verification ``id`` and the value reported by the user. A
correct value returns the updated verification with ``status`` ``verified``.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. http:example:: curl

         PATCH /api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "delivery_method": "sms",
             "code": "123456"
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "data": {
             "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
             "destination": "4915112345678",
             "delivery_method": "sms",
             "fee": "0.06",
             "status": "verified",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "sms": {
               "template": "Your code is {{CODE}}",
               "language": "en-US",
               "interception_timeout": 120
             }
           }
         }

   .. tab-item:: Phone call
      :sync: phone-call

      .. http:example:: curl

         PATCH /api/v1/verifications/2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "delivery_method": "callout",
             "code": "123456"
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "data": {
             "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
             "destination": "4915112345678",
             "delivery_method": "callout",
             "fee": "0.08",
             "status": "verified",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "callout": {
               "language": "de-DE"
             }
           }
         }

Ruby SDK
--------

The Ruby SDK sends a ``PATCH`` request when ``report_verification(...)`` is called and returns
the updated verification object.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: ruby

         result = client.report_verification(
           verification.id,
           delivery_method: "sms",
           code:            "123456"
         )

         result.status    # => "verified"
         result.verified? # => true

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: ruby

         result = client.report_verification(
           verification.id,
           delivery_method: "callout",
           code:            "123456"
         )

         result.status    # => "verified"
         result.verified? # => true

iOS SDK
-------

The iOS SDK sends a ``PUT`` request when ``verify(...)`` is called and returns a
``VerificationResult`` containing the updated state. It selects the delivery method from the
``Verification`` returned by ``start(...)`` and rejects a code that does not match that method
before sending a request.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: swift

         let result = try await client.verify(
             verification,
             code: "123456"
         )

         result.status // .verified

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: swift

         let result = try await client.verify(
             verification,
             code: "123456"
         )

         result.status // .verified

Android SDK
-----------

The Android SDK reports through the ``VerificationHandle`` returned by ``start(...)``. The
following examples assume that ``handle.states`` is already being collected exactly once.

Call ``submit(...)`` with the code. The handle reports it for the selected delivery method.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: kotlin

         handle.submit("123456")

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: kotlin

         handle.submit("123456")

The existing ``states`` collection emits ``VerificationState.Submitting`` while the report is
in progress. A correct value then emits ``VerificationState.Verified``. If the API rejects the
value but allows another attempt, the flow returns to ``VerificationState.AwaitingInput`` with
``lastError`` set. A terminal outcome emits ``VerificationState.Failed`` or
``VerificationState.Expired``.


.. _otp_verification_api_report_by_number:

===============================
Report a verification by number
===============================

Submit the code the user received by SMS or phone call without supplying a verification
``id``. The endpoint identifies the verification associated with the destination number and
checks the submitted code against it.

Use this endpoint when your application kept the destination number but did not store the
verification ``id`` returned by the start request. To report against one specific
verification, use :ref:`Report a verification <otp_verification_api_report>`.

Request
=======

HTTP method: ``PATCH`` (``PUT`` is accepted as an alias)

Path: ``/api/v1/verifications/by_number/{number}``

Path parameters
---------------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Name
     - Type
     - Description
   * - ``number``
     - ``string``
     - Destination phone number in E.164 format. The leading ``+`` is optional. When the
       leading ``+`` is included in the URL path, percent-encode it as ``%2B``.

Request body
------------

The request body contains a top-level ``data`` object. Use ``code`` for both ``sms`` and
``callout``.

.. list-table::
   :header-rows: 1
   :widths: 22 18 16 44

   * - Field
     - Type
     - Required
     - Description
   * - ``delivery_method``
     - ``string``
     - Yes
     - Must match the method used to start the verification. Supported values are ``sms`` and
       ``callout``.
   * - ``code``
     - ``string``
     - Yes
     - The code the user received by SMS or phone call.

Which verification receives the report
--------------------------------------

The report is scoped to the authenticated OTP application and the supplied phone number, and
targets the **most recently created** verification for that number, whatever its status. It
is the same record that
:ref:`Get verification status by number <otp_verification_api_status_by_number>` returns.

If another verification is started for the same number before the report is submitted, that
newer verification becomes the target of a later by-number report. Use the by-id report
endpoint when the submission must be tied to the exact verification originally shown to the
user.

When the targeted verification has already finished, the report does not change its outcome.
Read ``status`` and ``id`` from the response to confirm which verification the report reached
and what state it is in.

If the API cannot resolve a verification that can receive the report, it returns ``404 Not
Found``. Use :ref:`Get verification status by number
<otp_verification_api_status_by_number>` when you need to retrieve the latest state without
submitting a code.

Response
========

When the API accepts the report request, it returns ``200 OK`` with the
:ref:`verification object <otp_verification_object_reference>` under a top-level ``data``
key. Authentication, lookup, and validation errors return an ``errors`` array.

The following table lists the HTTP status codes returned by this endpoint:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Status
     - Meaning
   * - ``200 OK``
     - The report was processed. Inspect the returned ``status`` and ``error_code`` to
       determine the current verification state.
   * - ``401 Unauthorized``
     - Authentication failed, credentials are missing or invalid, or the authentication mode
       is below the minimum configured for the OTP application.
   * - ``404 Not Found``
     - No verification that can receive the report exists for the specified number under the
       OTP application.
   * - ``422 Unprocessable Content``
     - The submitted report could not be accepted. This includes an incorrect code or a
       mismatched ``delivery_method``.

A correct code returns ``200 OK`` with ``status`` ``verified``. An incorrect code returns
``422 Unprocessable Content`` with ``code_invalid``. The verification remains available for
another report until the attempt limit is reached. After three unsuccessful reports, it
becomes ``failed`` with ``error_code`` ``too_many_attempts``.

If the challenge has not yet been dispatched, the API can return ``422 Unprocessable
Content`` with ``not_ready_to_report``. Submit the value again after the challenge has been
sent or the call has been placed.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the error response
structure and available error codes.

.. warning::

   Each report can consume one of the three allowed attempts. Do not automatically retry a
   report after a timeout or another ambiguous network failure. Check the verification status
   before deciding whether the user should submit the value again.

Examples
========

The REST API examples use HTTP Basic authentication. See
:ref:`REST API authentication <otp_verification_authentication>` for credential and header
requirements.

The SDK examples assume that the corresponding SDK is installed and initialized. See the
:ref:`Ruby SDK <otp_verification_sdk_ruby>`,
:ref:`iOS SDK <otp_verification_sdk_ios>`, and
:ref:`Android SDK <otp_verification_sdk_android>`.

The identifiers, expiration times, fees, and codes shown in the examples are illustrative.

REST API
--------

Send a ``PATCH`` request with the destination number in the path and the value reported by
the user. The examples omit the leading ``+`` so no path encoding is required.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. http:example:: curl

         PATCH /api/v1/verifications/by_number/4915112345678 HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "delivery_method": "sms",
             "code": "123456"
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "data": {
             "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
             "destination": "4915112345678",
             "delivery_method": "sms",
             "fee": "0.06",
             "status": "verified",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "sms": {
               "template": "Your code is {{CODE}}",
               "language": "en-US",
               "interception_timeout": 120
             }
           }
         }

   .. tab-item:: Phone call
      :sync: phone-call

      .. http:example:: curl

         PATCH /api/v1/verifications/by_number/4915112345678 HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "delivery_method": "callout",
             "code": "123456"
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "data": {
             "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
             "destination": "4915112345678",
             "delivery_method": "callout",
             "fee": "0.08",
             "status": "verified",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "callout": {
               "language": "de-DE"
             }
           }
         }

Ruby SDK
--------

The Ruby SDK sends a ``PATCH`` request when ``report_verification_by_number(...)`` is called.
It handles path encoding and returns the updated verification object.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: ruby

         result = client.report_verification_by_number(
           "+4915112345678",
           delivery_method: "sms",
           code:            "123456"
         )

         result.status    # => "verified"
         result.verified? # => true

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: ruby

         result = client.report_verification_by_number(
           "+4915112345678",
           delivery_method: "callout",
           code:            "123456"
         )

         result.status    # => "verified"
         result.verified? # => true

iOS SDK
-------

The iOS SDK sends a ``PUT`` request and returns a ``VerificationResult``. It normalizes the
supplied number to digits before building the request path. Code submissions require the
delivery method.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: swift

         let result = try await client.verify(
             number: "+49 151 1234 5678",
             code: "123456",
             method: .sms
         )

         result.status // .verified

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: swift

         let result = try await client.verify(
             number: "+49 151 1234 5678",
             code: "123456",
             method: .callout
         )

         result.status // .verified

If the number contains no digits, the SDK throws ``VerificationError.invalidNumber`` before
sending a request. A wrong ``.sms`` or ``.callout`` selection is detected by the API and
returned as a validation error.

Android SDK
-----------

The Android SDK reports by number through a handle returned by ``resume(...)``. The first
collection of ``handle.states`` looks up the verification by number. A later submission from
that handle is sent to the same by-number path.

The examples submit the value before collection. This is supported because the handle buffers
the value until the lookup completes and the verification can accept it.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: kotlin

         val handle = didww.resume(
             destination = "+4915112345678",
             method = DeliveryMethod.SMS,
         )

         handle.submit("123456")

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: kotlin

         val handle = didww.resume(
             destination = "+4915112345678",
             method = DeliveryMethod.CALLOUT,
         )

         handle.submit("123456")

Collect the returned handle exactly once:

.. code-block:: kotlin

   viewModelScope.launch {
       handle.states.collect { state ->
           when (state) {
               is VerificationState.AwaitingInput ->
                   state.lastError?.let { println("try again: ${it.detail}") }
               VerificationState.Submitting ->
                   println("checking")
               is VerificationState.Verified ->
                   println("verified")
               is VerificationState.Failed ->
                   println("failed: ${state.reason}")
               VerificationState.Expired ->
                   println("expired")
               else -> Unit
           }
       }
   }

For a correct value, the flow progresses through ``Starting``, ``AwaitingInput``,
``Submitting``, and ``Verified``. If the API rejects the value but allows another attempt,
the flow returns to ``AwaitingInput`` with ``lastError`` set. If the lookup finds a finished
verification, the flow emits that terminal state and does not send the buffered report.

The delivery method returned by the API remains authoritative. The ``method`` argument to
``resume(...)`` selects channel-specific client behavior, including automatic SMS capture.


.. _otp_verification_api_start:

====================
Start a verification
====================

Create a verification for a destination phone number and select how the verification
challenge is delivered. The response contains the verification identifier, initial status,
expiration time, and delivery-method details when applicable.

For an approved request, the Verification API attempts to deliver the challenge by SMS or
phone call.

Request
=======

HTTP method: ``POST``

Path: ``/api/v1/verifications``

Request body
------------

The request body contains a top-level ``data`` object. The following table lists the fields
accepted inside ``data`` and identifies which fields are required:

.. list-table::
   :header-rows: 1
   :widths: 22 18 12 48

   * - Field
     - Type
     - Required
     - Description
   * - ``destination``
     - ``string``
     - Yes
     - Phone number to verify in E.164 format. The leading ``+`` is optional.
   * - ``delivery_method``
     - ``string``
     - Yes
     - The method used to deliver the verification challenge. Supported values are ``sms``
       and ``callout``.
   * - ``sms``
     - ``object``
     - No
     - Options for the ``sms`` delivery method. Send this object only when
       ``delivery_method`` is ``sms``. The API ignores it when another delivery method is
       selected.
   * - ``sms.languages``
     - Array of ``string``
     - No
     - Preferred message-template languages as BCP 47 tags, ordered from most to least
       preferred. Tags are matched exactly, so ``pl`` does not match ``pl-PL``. If none of
       the requested languages has a template, the API uses ``en-US``. Invalid tags return
       ``languages_invalid``. See :ref:`Supported languages
       <otp_verification_sms_languages>`.
   * - ``sms.app_hash``
     - ``string``
     - No
     - Android SMS Retriever application hash. It must contain exactly 11 characters from
       ``A-Z``, ``a-z``, ``0-9``, ``+``, and ``/``. When supplied, the SMS message starts
       with ``<#>`` and ends with the application hash so a compatible Android application
       can capture the code automatically. Omit this field on other platforms.
   * - ``callout``
     - ``object``
     - No
     - Options for the ``callout`` delivery method. Send this object only when
       ``delivery_method`` is ``callout``. The API ignores it when another delivery method is
       selected.
   * - ``callout.languages``
     - Array of ``string``
     - No
     - Preferred announcement languages as BCP 47 tags, ordered from most to least
       preferred. These are the same tags with the same semantics as ``sms.languages``, so
       one language list works for both delivery methods. Tags are matched exactly, so
       ``pt`` does not match ``pt-PT``. If none of the requested languages has a recording,
       the announcement uses ``en-US``. Invalid tags return ``languages_invalid``. See
       :ref:`Supported languages <otp_verification_callout_languages>`.

Response
========

The endpoint returns JSON responses. When a verification is created, its
:ref:`verification object <otp_verification_object_reference>` appears under a top-level
``data`` key. Errors that prevent a verification from being created appear under a
top-level ``errors`` array.

The following table lists the HTTP status codes returned by this endpoint:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Status
     - Meaning
   * - ``201 Created``
     - The verification record was created. Inspect ``status`` and ``error_code`` to
       determine whether delivery was approved or denied.
   * - ``401 Unauthorized``
     - Authentication failed, credentials are missing or invalid, or the authentication mode
       is below the minimum configured for the OTP application.
   * - ``402 Payment Required``
     - The account balance is insufficient to start a verification.
   * - ``422 Unprocessable Content``
     - Request validation failed. This includes an invalid destination, unsupported delivery
       method, or invalid delivery-method options.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the error response
structure and available error codes.

.. note::

   A ``201 Created`` response confirms that the verification record was created. It does not
   confirm that the challenge was delivered. An approved start normally has ``status``
   ``pending``, and delivery can still fail later.

   A :ref:`request callback <otp_verification_callbacks>` can deny the start before delivery.
   A denied start can also return ``201 Created`` with ``status`` ``denied`` and a matching
   ``error_code``. Always inspect both fields.

Examples
========

The REST API examples use HTTP Basic authentication. See
:ref:`REST API authentication <otp_verification_authentication>` for credential and header
requirements.

The SDK examples assume that the corresponding SDK is installed and initialized. See the
:ref:`Ruby SDK <otp_verification_sdk_ruby>`,
:ref:`iOS SDK <otp_verification_sdk_ios>`, and
:ref:`Android SDK <otp_verification_sdk_android>`.

The identifiers, expiration times, and fees shown in the examples are illustrative.

REST API
--------

Send a ``POST`` request to create a verification. When the record is created, the response
returns a verification object containing its initial state under a top-level ``data`` key.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. http:example:: curl

         POST /api/v1/verifications HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "destination": "+4915112345678",
             "delivery_method": "sms",
             "sms": {
               "languages": ["en-US"]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/json

         {
           "data": {
             "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
             "destination": "4915112345678",
             "delivery_method": "sms",
             "fee": "0.06",
             "status": "pending",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "sms": {
               "template": "Your code is {{CODE}}",
               "language": "en-US",
               "interception_timeout": 120
             }
           }
         }

   .. tab-item:: Phone call
      :sync: phone-call

      .. http:example:: curl

         POST /api/v1/verifications HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "destination": "+4915112345678",
             "delivery_method": "callout",
             "callout": {
               "languages": ["de-DE"]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/json

         {
           "data": {
             "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
             "destination": "4915112345678",
             "delivery_method": "callout",
             "fee": "0.08",
             "status": "pending",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "callout": {
               "language": "de-DE"
             }
           }
         }

Ruby SDK
--------

The Ruby SDK sends the request when ``start_verification(...)`` is called and returns a
verification object containing the initial state.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: ruby

         verification = client.start_verification(
           destination:     "+4915112345678",
           delivery_method: "sms",
           sms:             {languages: ["en-US"]}
         )

         verification.id           # => "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
         verification.status       # => "pending"
         verification.pending?     # => true
         verification.sms_language # => "en-US"

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: ruby

         verification = client.start_verification(
           destination:     "+4915112345678",
           delivery_method: "callout",
           callout:         {languages: ["de-DE"]}
         )

         verification.id               # => "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e"
         verification.status           # => "pending"
         verification.callout_language # => "de-DE"

iOS SDK
-------

The iOS SDK sends the request when ``start(...)`` is called and returns a ``Verification``
containing the initial state.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: swift

         let verification = try await client.start(
             destination: "+4915112345678",
             method: .sms,
             sms: .init(languages: ["en-US"])
         )

         verification.id     // "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
         verification.status // .pending

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: swift

         let verification = try await client.start(
             destination: "+4915112345678",
             method: .callout,
             callout: .init(languages: ["de-DE"])
         )

         verification.id     // "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e"
         verification.status // .pending

Inspect ``verification.status`` before asking the user for a code. A denied start returns a
``Verification`` with status ``.denied`` instead of throwing an HTTP error.

Android SDK
-----------

The Android SDK returns a ``VerificationHandle``. Calling ``start(...)`` does not send the
request. Collect ``handle.states`` exactly once to send the request and receive verification
state changes. After ``VerificationState.Starting``, an approved start emits
``VerificationState.AwaitingInput``, which corresponds to the API status ``pending``.

.. tab-set::

   .. tab-item:: SMS
      :sync: sms

      .. code-block:: kotlin

         val handle = didww.start(
             destination = "+4915112345678",
             method = DeliveryMethod.SMS,
             sms = SmsOptions(languages = listOf("en-US")),
         )

   .. tab-item:: Phone call
      :sync: phone-call

      .. code-block:: kotlin

         val handle = didww.start(
             destination = "+4915112345678",
             method = DeliveryMethod.CALLOUT,
             callout = CalloutOptions(languages = listOf("de-DE")),
         )

Collect the returned handle from a ViewModel-scoped coroutine:

.. code-block:: kotlin

   viewModelScope.launch {
       handle.states.collect { state ->
           when (state) {
               is VerificationState.AwaitingInput ->
                   println("Verification ${state.verificationId} is pending")
               is VerificationState.Denied ->
                   println(state.error?.detail ?: "Verification denied")
               is VerificationState.SetupError ->
                   println("Configuration error: ${state.code}")
               is VerificationState.Failed ->
                   println("Start failed: ${state.reason}")
               else -> Unit
           }
       }
   }


.. _otp_verification_authentication:

==============
Authentication
==============

Every request to the Verification API is authenticated with an
:ref:`OTP application <otp_verification_getting_started>`. Each OTP application has a
**key** and a **secret**. The authentication mode determines which credentials are sent with
a request and how they are used.

The API supports three authentication modes of increasing strength. Each application declares
a **minimum** mode. Requests authenticated below that minimum are rejected.

----

Credentials
===========

.. important::

   Create the OTP application and credentials in the same environment as the API endpoint.
   Sandbox credentials work only with the sandbox API, and production credentials work only
   with the production API. See :ref:`Choose an environment
   <otp_verification_environments>`.

An OTP application has two credentials:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Credential
     - Description
   * - **key**
     - Public identifier of the OTP application. Sent by itself in ``public`` mode, used as
       the HTTP Basic username, and included in the signed ``application`` header.
   * - **secret**
     - Private shared secret. Used as the HTTP Basic password and as the HMAC signing key
       for the ``application`` scheme. Keep it confidential.

Every OTP application has both credentials, including applications whose minimum
authentication mode is ``public``. Public clients use only the key and must not receive or
store the secret.

Both credentials are available on the application's page in the User Panel.

Authentication modes
====================

The ``Authorization`` header determines which authentication mode a request uses. The
minimum mode configured on the OTP application sets the lowest mode that is allowed. Requests
using a lower mode are rejected with ``401``.

For example, an application set to ``public`` accepts ``public``, ``basic``, and
``application`` requests. An application set to ``basic`` accepts ``basic`` and
``application`` requests. An application set to ``application`` accepts only signed
``application`` requests.

.. list-table::
   :header-rows: 1
   :widths: 18 22 60

   * - Mode
     - Authorization header
     - When to use it
   * - ``public``
     - ``Application <key>``
     - Untrusted clients, such as mobile or web apps, where only the application key is
       sent with the request. Requires a :ref:`request callback <otp_verification_callbacks>`
       so your backend can approve each verification. Without a callback URL, public-mode
       requests are denied.
   * - ``basic``
     - ``Basic <base64(key:secret)>``
     - Server-to-server calls where the secret can be kept private. This is the default
       mode for server-side REST API examples.
   * - ``application``
     - ``Application <key>:<signature>``
     - Server-to-server calls that additionally sign each request with the secret,
       protecting against tampering and replay. The strongest mode.

.. note::

   The ``public`` and ``application`` modes share the ``Application`` scheme prefix. They
   are distinguished by whether a ``:<signature>`` is present.

SDK support
-----------

The REST API supports all three authentication modes. SDK support depends on whether the
integration runs on a trusted server or an untrusted mobile device:

.. list-table::
   :header-rows: 1
   :widths: 20 28 26 26

   * - Mode
     - Ruby SDK
     - iOS SDK
     - Android SDK
   * - ``public``
     - Supported with ``auth_mode: :public``.
     - Supported with ``.public(appKey:)``.
     - Supported with ``Auth.Public(applicationKey)``.
   * - ``basic``
     - Supported and used by default.
     - Supported for local development with ``.basic(appKey:secret:)``.
     - Supported for local development with ``Auth.Basic(key, secret)``.
   * - ``application``
     - Supported with ``auth_mode: :application``.
     - Not available. It requires a signing secret on the device.
     - Not available. It requires a signing secret on the device.

Authentication result
---------------------

A valid ``Authorization`` header allows the API to continue processing the request. It does
not guarantee that a verification will be started or delivered. For example, a start request
may still be denied by a :ref:`request callback <otp_verification_callbacks>`.

If authentication fails, the API returns ``401 Unauthorized`` with error code
``unauthorized``. This includes missing or invalid credentials, an authentication mode below
the application's configured minimum, an invalid signature, or a stale timestamp. No
verification is started. See :ref:`Errors and Status Codes <otp_verification_api_errors>`.

Public (``public`` mode)
========================

The ``public`` mode sends only the application key in the request. The OTP application still
has a secret, but public-mode clients do not send or store it. This mode is for untrusted
clients that must not embed the secret, such as SDKs running in mobile or web apps.

The application must have a :ref:`request callback <otp_verification_callbacks>` configured
so your backend can approve each verification. Without a callback URL, public-mode requests
are denied.

.. code-block:: text

   Authorization: Application <key>

The following examples start an SMS verification using ``public`` authentication:

.. tab-set::

   .. tab-item:: REST API
      :sync: rest-api

      .. http:example:: curl

         POST /api/v1/verifications HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Application your-app-key

         {
           "data": {
             "destination": "+4915112345678",
             "delivery_method": "sms"
           }
         }

   .. tab-item:: Ruby SDK
      :sync: ruby

      Set ``auth_mode: :public``. No secret is required in the SDK client.

      .. code-block:: ruby

         client = DIDWW::OTPVerification::Client.new(
           key:       "your-app-key",
           auth_mode: :public
         )

         client.start_verification(
           destination:     "+4915112345678",
           delivery_method: "sms"
         )

   .. tab-item:: iOS SDK
      :sync: ios

      Use ``.public(appKey:)`` in production mobile apps. The client sends only the
      application key.

      .. code-block:: swift

         let client = VerificationClient(
             environment: .production,
             auth: .public(appKey: "your-app-key")
         )

         let verification = try await client.start(
             destination: "+4915112345678",
             method: .sms
         )

   .. tab-item:: Android SDK
      :sync: android

      Use ``Auth.Public`` in production mobile apps. The request is sent when the returned
      handle's ``states`` flow is first collected.

      .. code-block:: kotlin

         val didww = DidwwVerification(
             context = application,
             auth = Auth.Public("your-app-key"),
             environment = Environment.Production,
         )

         val handle = didww.start(
             destination = "+4915112345678",
             method = DeliveryMethod.SMS,
         )

         viewModelScope.launch {
             handle.states.collect { state -> println(state) }
         }

After authenticating the key, the API sends a request to the application's callback URL.
The callback result determines whether the verification proceeds or is denied. Without a
configured callback URL, the request is denied with ``denied_missing_callback_url``.

HTTP Basic (``basic`` mode)
===========================

Use ``basic`` mode for server-side integrations where the OTP application secret can be kept
private. HTTP Basic uses the key as the username and the secret as the password:

.. code-block:: text

   Authorization: Basic <base64(key:secret)>

Where ``<base64(key:secret)>`` is the Base64 encoding of the key and secret joined by a
colon. Most HTTP clients construct this header automatically when you supply a username and
password.

.. warning::

   Use ``basic`` authentication in the iOS and Android SDKs only for local development. A
   secret included in a mobile app can be extracted from the app binary. Use ``public``
   authentication with a request callback in production mobile apps.

The following examples start an SMS verification using HTTP Basic authentication:

.. tab-set::

   .. tab-item:: REST API
      :sync: rest-api

      .. http:example:: curl

         POST /api/v1/verifications HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "destination": "+4915112345678",
             "delivery_method": "sms"
           }
         }

   .. tab-item:: Ruby SDK
      :sync: ruby

      The :ref:`Ruby SDK <otp_verification_sdk_ruby>` builds the ``Basic`` header for you.
      ``:basic`` is the default auth mode.

      .. code-block:: ruby

         client = DIDWW::OTPVerification::Client.new(
           key:    "your-app-key",
           secret: "your-app-secret"
         )

         client.start_verification(
           destination:     "+4915112345678",
           delivery_method: "sms"
         )

   .. tab-item:: iOS SDK
      :sync: ios

      Use ``.basic(appKey:secret:)`` for local development only. The SDK builds the
      ``Basic`` header from the supplied credentials.

      .. code-block:: swift

         let client = VerificationClient(
             environment: .sandbox,
             auth: .basic(
                 appKey: "your-app-key",
                 secret: "your-app-secret"
             )
         )

         let verification = try await client.start(
             destination: "+4915112345678",
             method: .sms
         )

   .. tab-item:: Android SDK
      :sync: android

      Use ``Auth.Basic`` for local development only. The SDK logs a warning when it is used
      in a build that is not marked debuggable.

      .. code-block:: kotlin

         val didww = DidwwVerification(
             context = application,
             auth = Auth.Basic("your-app-key", "your-app-secret"),
             environment = Environment.Sandbox,
         )

         val handle = didww.start(
             destination = "+4915112345678",
             method = DeliveryMethod.SMS,
         )

         viewModelScope.launch {
             handle.states.collect { state -> println(state) }
         }

If the credentials are valid, the request continues. When the OTP application has a callback
URL, the API waits for the callback decision before proceeding. Without a callback URL, the
verification proceeds without that approval step.

.. _otp_verification_signed_requests:

Signed requests (``application`` mode)
======================================

Use ``application`` mode for server-side integrations that need signed requests. This mode
uses HMAC-SHA256 to sign each request with the OTP application secret, so DIDWW can verify
the caller and reject requests that were altered or replayed.

Send two headers:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Header
     - Value
   * - ``Authorization``
     - ``Application <key>:<signature>``
   * - ``x-timestamp``
     - Unix time in seconds when the request is signed.

.. note::

    The ``x-timestamp`` value must be within **5 minutes** of the server's clock. Requests outside
    that window are rejected as stale.

The REST API and Ruby SDK examples start an SMS verification using a signed ``application``
request. The iOS and Android tabs explain the mobile SDK limitation.

.. tab-set::

   .. tab-item:: REST API
      :sync: rest-api

      .. http:example:: curl

         POST /api/v1/verifications HTTP/1.1
         Host: verification.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Application your-app-key:<signature>
         x-timestamp: <unix-timestamp>

         {
           "data": {
             "destination": "+4915112345678",
             "delivery_method": "sms"
           }
         }

   .. tab-item:: Ruby SDK
      :sync: ruby

      The :ref:`Ruby SDK <otp_verification_sdk_ruby>` computes the signature and sets both
      headers when ``auth_mode: :application`` is used.

      .. code-block:: ruby

         client = DIDWW::OTPVerification::Client.new(
           key:       "your-app-key",
           secret:    "your-app-secret",
           auth_mode: :application
         )

         client.start_verification(
           destination:     "+4915112345678",
           delivery_method: "sms"
         )

   .. tab-item:: iOS SDK
      :sync: ios

      The iOS SDK does not support signed ``application`` authentication. This mode requires
      the OTP application secret, which must not be included in a mobile app. Use
      ``.public(appKey:)`` with a :ref:`request callback <otp_verification_callbacks>` for
      production iOS integrations.

   .. tab-item:: Android SDK
      :sync: android

      The Android SDK does not support signed ``application`` authentication. This mode
      requires the OTP application secret, which must not be included in an APK. Use
      ``Auth.Public`` with a :ref:`request callback <otp_verification_callbacks>` for
      production Android integrations.

The API verifies the signature and timestamp before processing the request. Valid signed
requests do not trigger the request callback. An invalid signature or stale timestamp causes
the API to reject the request with ``401 Unauthorized``.

The rest of this section explains how to build the signature yourself when integrating
without an SDK.

Building the signature
----------------------

1. Build the **string to sign** by joining these five components with newline
   (``\n``) characters, in this order:

   .. code-block:: text

      <HTTP-METHOD>
      <CONTENT-MD5>
      <CONTENT-TYPE>
      x-timestamp:<TIMESTAMP>
      <PATH>

   .. list-table::
      :header-rows: 1
      :widths: 25 75

      * - Component
        - Value
      * - ``HTTP-METHOD``
        - Request method in uppercase, for example ``POST``.
      * - ``CONTENT-MD5``
        - Base64-encoded MD5 digest of the raw request body. Use an empty string when there
          is no body.
      * - ``CONTENT-TYPE``
        - The request ``Content-Type``, for example ``application/json``.
      * - ``TIMESTAMP``
        - The same value sent in the ``x-timestamp`` header.
      * - ``PATH``
        - The request path, for example ``/api/v1/verifications``.

2. Derive the **signing key** by Base64url-decoding the application secret to raw bytes.

3. Compute ``HMAC-SHA256(signing_key, string_to_sign)`` and Base64-encode the result. This
   value is the ``<signature>``.

.. important::

   Calculate ``CONTENT-MD5`` and the signature from the exact request body bytes sent to the
   API. Changing whitespace, field ordering, content type, timestamp, or request path after
   signing causes signature verification to fail.

.. code-block:: text

   Authorization: Application 3f1c...e9:Base64(HMAC-SHA256(Base64urlDecode(secret), string_to_sign))
   x-timestamp: 1752573720

.. note::

   The same signing scheme applies to :ref:`request callbacks
   <otp_verification_callbacks>` sent to your server. You can use the same HMAC calculation
   to sign outgoing requests and verify incoming callbacks.

Reference implementation (bash)
-------------------------------

Use this self-contained ``bash`` script to compute a signature from the request parts. It
requires ``openssl`` and can be used to check your own implementation against a known input.

Assign the request values at the top of the script. The script prints the ``<signature>``.

.. code-block:: bash

   #!/bin/bash
   set -euo pipefail

   # --- Request parts (assign these from your actual request) ---
   SECRET='c2FtcGxlLWFwcGxpY2F0aW9uLXNlY3JldC0wMTIzNDU2Nzg5'   # application secret (URL-safe base64)
   HTTP_METHOD='POST'
   CONTENT_TYPE='application/json'
   REQUEST_PATH='/api/v1/verifications'
   TIMESTAMP='1752573720'   # seconds since epoch, e.g. from `date +%s` or `time.time()`
   BODY='{"data":{"destination":"+4915112345678","delivery_method":"sms","sms":{"languages":["en-US"]}}}'

   # CONTENT-MD5: Base64(MD5(body)), empty string when the body is empty.
   if [ -n "$BODY" ]; then
     CONTENT_MD5="$(printf '%s' "$BODY" | openssl dgst -md5 -binary | openssl base64 -A)"
   else
     CONTENT_MD5=''
   fi

   # String to sign: METHOD, CONTENT-MD5, CONTENT-TYPE, x-timestamp:TS, PATH (newline-joined).
   STRING_TO_SIGN="$(printf '%s\n%s\n%s\nx-timestamp:%s\n%s' \
     "$HTTP_METHOD" "$CONTENT_MD5" "$CONTENT_TYPE" "$TIMESTAMP" "$REQUEST_PATH")"

   # Signing key = raw bytes of the URL-safe base64 secret. Convert the URL-safe
   # alphabet (-_) to standard (+/) and restore '=' padding so `openssl base64 -d` accepts it.
   STD_SECRET="$(printf '%s' "$SECRET" | tr '_-' '/+')"
   case $(( ${#STD_SECRET} % 4 )) in
     2) STD_SECRET="${STD_SECRET}==" ;;
     3) STD_SECRET="${STD_SECRET}=" ;;
   esac
   SIGNING_KEY_HEX="$(printf '%s' "$STD_SECRET" | openssl base64 -d -A | od -An -v -tx1 | tr -d ' \n')"

   # HMAC-SHA256 over the string to sign, base64-encoded.
   printf '%s' "$STRING_TO_SIGN" \
     | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$SIGNING_KEY_HEX" -binary \
     | openssl base64 -A
   echo

.. note::

   ``PATH`` is a reserved shell variable. The script uses ``REQUEST_PATH`` so it does not
   overwrite the executable search path.

With the sample values above, the script prints:

.. code-block:: text

   BY/LCMM2R4eDkONcS4DyssymoWKAYXgUoxTc50Yssf8=

If your implementation produces the same signature for these input values, it matches this
test vector. The signed request would include:

.. code-block:: text

   Authorization: Application <your-application-key>:BY/LCMM2R4eDkONcS4DyssymoWKAYXgUoxTc50Yssf8=
   x-timestamp: 1752573720

.. tip::

   The :ref:`Ruby SDK <otp_verification_sdk_ruby>` signs requests automatically in
   ``application`` mode. You only need to implement this signing scheme when integrating
   without an SDK.


.. _otp_verification_callbacks:

=========
Callbacks
=========

Callbacks let DIDWW send verification-related HTTP requests to your server. The currently
supported callback is the synchronous **verification request callback**, which lets your
backend approve or reject a verification before the challenge is delivered.

Configure a **callback URL** on your OTP application in the User Panel to receive callbacks.

----

Verification request callback
=============================

The verification request callback lets your backend decide whether a verification can
proceed. When the callback applies to a start request, the Verification API sends a request
to your configured callback endpoint before delivering the challenge.

If your callback endpoint approves the request, delivery proceeds. If it denies the request
or does not return a usable response, the verification is denied and nothing is delivered.

Because the callback is synchronous, the :ref:`start endpoint
<otp_verification_api_start>` does not return until your callback endpoint responds or the
callback request times out.

When it is sent
---------------

Whether the callback is sent depends on the application's callback URL and the
:ref:`authentication mode <otp_verification_authentication>` of the start request:

.. list-table::
   :header-rows: 1
   :widths: 20 25 55

   * - Auth mode
     - Callback URL set?
     - Behavior
   * - ``public``
     - Yes
     - Callback is **sent**. Your server decides.
   * - ``public``
     - No
     - The verification start is **denied** because ``public`` authentication requires a
       callback URL.
   * - ``basic``
     - Yes
     - Callback is **sent**. Your server decides.
   * - ``basic``
     - No
     - Callback is **skipped**; the verification proceeds.
   * - ``application``
     - Any
     - Callback is **skipped**. The signed request already proves it came from your
       trusted server.

Request from DIDWW
------------------

To receive this request, configure the callback URL on the OTP application before starting a
verification. Your application does not call the callback URL directly. When an eligible start
request reaches the Verification API, the API pauses the verification flow and sends an HTTP
``POST`` to the configured callback URL before delivering the challenge.

This happens when the start request uses ``public`` or ``basic`` authentication and the OTP
application has a callback URL, as described in `When it is sent`_. The Verification API waits
for your callback endpoint to approve or deny the request before completing the start request.

The callback request contains a JSON body describing the verification and signed headers that
your server can authenticate:

.. code-block:: http

   POST /your/callback/path HTTP/1.1
   Host: your-server.example.com
   Content-Type: application/json
   Authorization: Application <application-key>:<signature>
   x-timestamp: 1752573720

   {
     "event": "verification_request",
     "data": {
       "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
       "destination": "4915112345678",
       "delivery_method": "sms"
     }
   }

The ``Authorization`` and
``x-timestamp`` headers let your server verify the request signature. The JSON body identifies
the verification that is waiting for your server's approval or denial. The following table
describes the fields in that JSON body:

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Field
     - Type
     - Description
   * - ``event``
     - ``string``
     - Always ``verification_request`` for this callback.
   * - ``data.id``
     - ``string``
     - The verification identifier (UUID).
   * - ``data.destination``
     - ``string``
     - The number being verified, in E.164 without a leading ``+``.
   * - ``data.delivery_method``
     - ``string``
     - The requested delivery method: ``sms`` or ``callout``.

Verifying the signature
-----------------------

Each callback includes a signature that lets your server confirm that the request came from
the Verification API and was not modified in transit. Verify this signature before using the
callback data or returning an approval decision.

The callback uses the same HMAC-SHA256 signing scheme as ``application`` authentication,
with your application secret as the signing key. The ``Authorization`` header contains
``Application <application-key>:<signature>``, and ``x-timestamp`` contains the signing time
in Unix seconds.

Recreate the signature from the callback request and compare it with the signature in the
``Authorization`` header. See :ref:`Signed requests
<otp_verification_signed_requests>` for the string-to-sign format and signing procedure. For
a callback, the ``PATH`` component is the path from your configured callback URL.

.. warning::

   The callback endpoint is reachable from the public internet. Verify the signature and
   timestamp before approving or processing the callback request.

Callback response
-----------------

After receiving the callback request, your callback endpoint must respond to the Verification
API over the same HTTP connection. This response is sent from your backend to the Verification
API, not to the application that started the verification.

Return an HTTP ``2xx`` response with a JSON body containing an ``action`` field. Use ``allow``
to approve the verification request or ``deny`` to reject it.

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Response from your callback
     - Decision
   * - ``2xx`` with ``{ "action": "allow" }``
     - Approve the verification request.
   * - ``2xx`` with ``{ "action": "deny" }``
     - Reject the verification request.
   * - No usable callback response
     - Treat the callback as unsuccessful and deny the verification request.

The following examples show the responses your callback endpoint can return:

.. tab-set::

   .. tab-item:: Allow

      .. code-block:: http

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "action": "allow"
         }

   .. tab-item:: Deny

      .. code-block:: http

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "action": "deny"
         }

Result returned by the Verification API
---------------------------------------

After processing the callback response, the Verification API completes the original
:ref:`start request <otp_verification_api_start>` and returns the verification result to the
application that started it.

The following table shows how each callback outcome appears in the start response:

.. list-table::
   :header-rows: 1
   :widths: 28 32 40

   * - Callback outcome
     - Start response
     - Delivery result
   * - ``allow``
     - ``201 Created`` with ``status`` ``pending``
     - The Verification API creates the verification and attempts to deliver the challenge.
   * - ``deny``
     - ``201 Created`` with ``status`` ``denied`` and ``error_code``
       ``denied_by_callback``
     - The Verification API creates the denied verification. No challenge is delivered.
   * - No usable callback response
     - ``201 Created`` with ``status`` ``denied`` and ``error_code``
       ``denied_invalid_callback_response``
     - The Verification API creates the denied verification. No challenge is delivered.

A callback response is unusable when the callback endpoint returns a non-``2xx`` status,
times out, encounters a transport error, returns invalid JSON, provides an unsupported
``action``, or returns a response body larger than 8 KB.

Approved and denied start requests can both return ``201 Created``. This status confirms that
the verification record was created. It does not confirm that the callback approved the
request or that the challenge was delivered. Inspect ``status`` and ``error_code`` to
determine the result.

.. note::

   If ``public`` authentication is used without a callback URL configured on the OTP
   application, no callback request is sent. The Verification API creates the verification
   with ``status`` ``denied`` and ``error_code`` ``denied_missing_callback_url``. The original
   start request can still return ``201 Created``.

Timeouts
--------

Callback requests use a **5-second connection timeout** and a **15-second read timeout**. If
your server cannot be reached or does not return a usable response within these limits, the
verification is created with ``status`` ``denied`` and ``error_code``
``denied_invalid_callback_response``.

Design your callback endpoint to return its decision within these timeout limits.


.. _otp_verification_getting_started:

===============
Getting Started
===============

This guide walks you through creating an **OTP application**, generating API credentials,
and running your first verification from start to finish. The walkthrough uses the sandbox
environment so you can test the integration before moving it to production.

----

.. _otp_verification_environments:

Choose an environment
=====================

Create the OTP application and credentials in the same environment as the Verification API
endpoint you plan to use:

.. list-table::
   :header-rows: 1
   :widths: 18 32 30 20

   * - Environment
     - User Panel
     - Verification API base URL
     - Use
   * - Sandbox
     - `DIDWW Sandbox User Panel <https://my-sandbox.didww.com/#/users/sign_in>`__
     - ``https://verification-sandbox.didww.com``
     - Integration testing
   * - Production
     - `DIDWW Production User Panel <https://my.didww.com/users/sign_in>`__
     - ``https://verification.didww.com``
     - Live verifications

.. important::

   Credentials are environment-specific. Use credentials from a sandbox OTP application
   with the sandbox API, and credentials from a production OTP application with the
   production API.

----

Before you begin
================

- **An account in the selected environment** is required. For testing, open
  the `DIDWW Sandbox User Panel <https://my-sandbox.didww.com/#/otp_verify>`__. For
  production, sign in to the
  `DIDWW Production User Panel <https://my.didww.com/users/sign_in>`__ or
  `create a DIDWW account <https://my.didww.com/users/sign_up>`__.
- **Access to the corresponding User Panel** is required to create an OTP application and
  copy its credentials.
- **A positive account balance** is required for production. The verification fee is billed
  when a verification reaches ``verified``. SMS and call delivery costs are billed
  separately.
- **A phone number you control** is required when testing delivery through the production
  environment.

----

Step 1: Create an OTP application
=================================

An **OTP application** groups the credentials and settings used by your verification
requests. You need one before you can start verifications, because each request is tied to an
OTP application key, secret, callback URL, and minimum authentication mode.

For this walkthrough, create the application in
the `DIDWW Sandbox User Panel <https://my-sandbox.didww.com/#/otp_verify>`__.

1. Open the User Panel for your selected environment: use
   the `DIDWW Sandbox User Panel <https://my-sandbox.didww.com/#/otp_verify>`__ for testing
   or the `DIDWW Production User Panel <https://my.didww.com/users/sign_in>`__ for live
   verifications.
2. Expand **OTP Verify**.
3. Select **Applications**.
4. Click **Create application**.
5. Enter a name for the application.
6. Optionally, enter a description.
7. Set a **callback URL** if you plan to use ``public`` authentication, including the iOS
   and Android SDK examples in this guide. The Verification API calls this URL so your
   backend can approve or reject each start request. The callback URL is optional for
   ``basic`` and ``application`` authentication. See
   :ref:`Callbacks <otp_verification_callbacks>`.
8. Select the minimum :ref:`authentication mode <otp_verification_authentication>` required
   for requests to this OTP application:

   - **Public**: anyone with the credential key can call the OTP endpoint.
   - **Basic**: callers must use HTTP Basic authentication with the credential key as the
     username and the credential secret as the password.
   - **Application**: callers must sign each request with the credential secret.

9. Click **Create** to save the application.

.. figure:: https://doc.didww.com/_images/step1.png
   :alt: Create OTP application form in the DIDWW Sandbox User Panel

   Create an OTP application in the DIDWW Sandbox User Panel.

Step 2: Get your API credentials
================================

Each OTP application has a **key** and a **secret**. The key identifies the OTP application
when you make verification requests. The secret is used for stronger authentication modes,
such as HTTP Basic or signed ``application`` authentication.

Copy the credentials from the OTP application in your selected environment. This walkthrough
uses credentials created in the DIDWW Sandbox User Panel.

The REST API and Ruby SDK examples use both credentials with ``basic`` authentication. The
iOS and Android SDK examples use only the key with ``public`` authentication.

1. In **OTP Verify** > **Applications**, find the application you created.
2. In the **Credentials** column, copy the **key** and **secret** for that application.
   Use the copy icon to copy each value without revealing it on screen.
3. If you need to view the actual value before copying it, click the eye icon.

.. warning::

   Treat the secret like a password. Store it securely and never expose it in client-side
   code or public repositories. If it is leaked, rotate it from the corresponding DIDWW
   User Panel.

.. figure:: https://doc.didww.com/_images/step2.png
   :alt: OTP application credentials in the DIDWW Sandbox User Panel

   Copy the key and secret from the Credentials column.

Step 3: Start a verification
============================

Call the :ref:`start endpoint <otp_verification_api_start>` with the destination number and
delivery method. The examples use the sandbox environment and send an SMS code.

.. note::

   The REST API and Ruby SDK examples use ``basic`` authentication. The iOS and Android SDK
   examples use ``public`` authentication, which requires the callback URL configured in
   Step 1. An OTP application with minimum auth mode ``public`` accepts both authentication
   modes. All examples use credentials created in the DIDWW Sandbox User Panel.

.. tab-set::

   .. tab-item:: REST API
      :sync: rest-api

      .. http:example:: curl

         POST /api/v1/verifications HTTP/1.1
         Host: verification-sandbox.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "destination": "+4915112345678",
             "delivery_method": "sms",
             "sms": {
               "languages": ["en-US"]
             }
           }
         }

         HTTP/1.1 201 Created
         Content-Type: application/json

         {
           "data": {
             "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
             "destination": "4915112345678",
             "delivery_method": "sms",
             "fee": "0.06",
             "status": "pending",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "sms": {
               "template": "Your code is {{CODE}}",
               "language": "en-US",
               "interception_timeout": 120
             }
           }
         }

      .. note::

         The ``Authorization`` header contains the Base64 encoding of ``key:secret``. Most
         HTTP clients build this header when you supply the key as the username and the
         secret as the password.

   .. tab-item:: Ruby SDK
      :sync: ruby

      Install the :ref:`Ruby SDK <otp_verification_sdk_ruby>`, then create a sandbox client
      and start the verification:

      .. code-block:: ruby

         require "didww/otp_verification"

         client = DIDWW::OTPVerification::Client.new(
           key:    "your-app-key",
           secret: "your-app-secret",
           env:    :sandbox
         )

         verification = client.start_verification(
           destination:     "+4915112345678",
           delivery_method: "sms",
           sms:             {languages: ["en-US"]}
         )

         verification.id       # => "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
         verification.status   # => "pending"
         verification.pending? # => true

   .. tab-item:: iOS SDK
      :sync: ios

      Install the :ref:`iOS SDK <otp_verification_sdk_ios>`, then create a sandbox client
      with public authentication and start the verification:

      .. code-block:: swift

         import DIDWWVerification

         let client = VerificationClient(
             environment: .sandbox,
             auth: .public(appKey: "your-app-key")
         )

         let verification = try await client.start(
             destination: "+4915112345678",
             method: .sms,
             sms: .init(languages: ["en-US"])
         )

         verification.id     // "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
         verification.status // .pending

   .. tab-item:: Android SDK
      :sync: android

      Install the :ref:`Android SDK <otp_verification_sdk_android>`. Inside an
      ``AndroidViewModel``, create a sandbox client with public authentication and start
      collecting the verification states. Calling ``start(...)`` creates a handle. The
      request is sent when ``handle.states`` is first collected.

      .. code-block:: kotlin

         import androidx.lifecycle.viewModelScope
         import com.didww.android.sdk.verification.Auth
         import com.didww.android.sdk.verification.DeliveryMethod
         import com.didww.android.sdk.verification.Environment
         import com.didww.android.sdk.verification.SmsOptions
         import com.didww.android.sdk.verification.VerificationState
         import com.didww.android.sdk.verification.all.DidwwVerification
         import kotlinx.coroutines.flow.MutableStateFlow
         import kotlinx.coroutines.launch

         val didww = DidwwVerification(
             context = application,
             auth = Auth.Public("your-app-key"),
             environment = Environment.Sandbox,
         )

         val verificationState = MutableStateFlow<VerificationState>(
             VerificationState.Starting,
         )

         val handle = didww.start(
             destination = "+4915112345678",
             method = DeliveryMethod.SMS,
             sms = SmsOptions(languages = listOf("en-US")),
         )

         viewModelScope.launch {
             handle.states.collect { verificationState.value = it }
         }

Keep the returned ``id``, ``verification``, or ``handle``, depending on your integration.
You need it to report the code and read the verification status in the next steps.

Step 4: Report the code
=======================

When the user enters the code they received, submit it to the
:ref:`report endpoint <otp_verification_api_report>`:

.. tab-set::

   .. tab-item:: REST API
      :sync: rest-api

      .. http:example:: curl

         PATCH /api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 HTTP/1.1
         Host: verification-sandbox.didww.com
         Content-Type: application/json
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         {
           "data": {
             "delivery_method": "sms",
             "code": "123456"
           }
         }

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "data": {
             "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
             "destination": "4915112345678",
             "delivery_method": "sms",
             "fee": "0.06",
             "status": "verified",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "sms": {
               "template": "Your code is {{CODE}}",
               "language": "en-US",
               "interception_timeout": 120
             }
           }
         }

   .. tab-item:: Ruby SDK
      :sync: ruby

      .. code-block:: ruby

         verification = client.report_verification(
           "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
           delivery_method: "sms",
           code:            "123456"
         )

         verification.status    # => "verified"
         verification.verified? # => true

   .. tab-item:: iOS SDK
      :sync: ios

      .. code-block:: swift

         let result = try await client.verify(
             verification,
             code: "123456"
         )

         result.status // .verified

   .. tab-item:: Android SDK
      :sync: android

      Submit the code through the handle created in Step 3. The existing state collector
      receives the result.

      .. code-block:: kotlin

         handle.submit("123456")

      A successful submission emits ``VerificationState.Submitting`` followed by
      ``VerificationState.Verified``. If the code is rejected, the flow returns to
      ``VerificationState.AwaitingInput`` with ``lastError`` set.

A ``status`` of ``verified`` confirms the user controls the number. If the code is incorrect,
the report is rejected and the verification remains available for another attempt until the
attempt limit is reached. See :ref:`Errors and status codes <otp_verification_api_errors>` for
the exact limit and other status values.

Step 5: Check the status (optional)
===================================

Read the current status of a verification at any time. REST, Ruby, and iOS make a status
request. Android reads the latest state received by the collector created in Step 3.

.. tab-set::

   .. tab-item:: REST API
      :sync: rest-api

      .. http:example:: curl

         GET /api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 HTTP/1.1
         Host: verification-sandbox.didww.com
         Accept: application/json
         Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

         HTTP/1.1 200 OK
         Content-Type: application/json

         {
           "data": {
             "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
             "destination": "4915112345678",
             "delivery_method": "sms",
             "fee": "0.06",
             "status": "verified",
             "error_code": null,
             "error_detail": null,
             "expires_at": "2026-07-15T10:02:00.000Z",
             "sms": {
               "template": "Your code is {{CODE}}",
               "language": "en-US",
               "interception_timeout": 120
             }
           }
         }

   .. tab-item:: Ruby SDK
      :sync: ruby

      .. code-block:: ruby

         verification = client.get_verification("0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21")

         verification.status    # => "verified"
         verification.verified? # => true

   .. tab-item:: iOS SDK
      :sync: ios

      .. code-block:: swift

         let current = try await client.status(verification)

         current.status // .verified

   .. tab-item:: Android SDK
      :sync: android

      Do not collect ``handle.states`` a second time. Read the latest value mirrored by the
      collector created in Step 3:

      .. code-block:: kotlin

         when (val current = verificationState.value) {
             is VerificationState.AwaitingInput -> println("pending")
             is VerificationState.Verified -> println("verified")
             is VerificationState.Denied -> println("denied")
             is VerificationState.Failed -> println("failed")
             is VerificationState.SetupError -> println("configuration error")
             VerificationState.Expired -> println("expired")
             else -> println("in progress")
         }

Move to production
==================

After the sandbox flow works as expected, configure the integration separately for
production:

1. Sign in to the
   `DIDWW Production User Panel <https://my.didww.com/users/sign_in>`__.
2. Create a new OTP application in the production account and configure its callback URL
   and minimum authentication mode.
3. Copy the key and secret from the production OTP application. Store them separately from
   the sandbox credentials.
4. Change the API or SDK environment from sandbox to production:

   .. list-table::
      :header-rows: 1
      :widths: 22 39 39

      * - Integration
        - Sandbox
        - Production
      * - REST API
        - ``https://verification-sandbox.didww.com``
        - ``https://verification.didww.com``
      * - Ruby SDK
        - ``env: :sandbox``
        - ``env: :production`` or omit ``env``
      * - iOS SDK
        - ``environment: .sandbox``
        - ``environment: .production``
      * - Android SDK
        - ``environment = Environment.Sandbox``
        - ``environment = Environment.Production``

5. Run a controlled verification using a phone number you can access.

.. warning::

   Production requests can contact real destinations and incur verification and delivery
   charges. Confirm that the production OTP application, credentials, callback URL, and API
   environment are configured together before sending requests.

Next steps
==========

- Compare the delivery channels in :ref:`Verification Methods <otp_verification_methods>`.
- Review the available authentication modes and choose the one that fits your integration in
  :ref:`Authentication <otp_verification_authentication>`.
- Gate verifications in real time with a
  :ref:`request callback <otp_verification_callbacks>`.
- Review every field and status code in the
  :ref:`API Reference <otp_verification_api_reference>`.


.. _otp_verification_sdk_android:

===========
Android SDK
===========

The Android SDK (``com.didww.android.sdk.verification``) is an on-device Kotlin client for the
:ref:`Verification API <otp_verification_api_reference>`. It supports SMS and phone call
through a coroutine-based API, represents each verification as a ``Flow`` of states, and
provides typed errors that your app can handle.

- **Source:** https://github.com/didww/didww-verification-android-sdk
- **Requires:** Android ``minSdk 23``.
- **Build from source:** Android ``compileSdk 36``, JDK ``17``, and Kotlin ``2.4.10``.
- **Dependencies:** Kotlin coroutines and ``kotlinx.serialization``.
- **Transport:** Uses the Android platform HTTP stack. There is no third-party HTTP client to
  configure.
- **Permissions:** Declares ``INTERNET`` directly and does not require a dangerous runtime
  permission.
- **Sensitive data:** Does not persist or write OTP codes, phone numbers, or credentials to
  diagnostic logs.

.. note::

   Mobile app credentials can be extracted from the app binary. For that reason, the
   on-device SDK supports only the ``public`` and ``basic`` authentication schemes.
   HMAC-signed server-to-server authentication is not available because it requires a
   signing secret. See :ref:`Authentication <otp_verification_authentication>`.

   The SDK is written for Kotlin. Coroutines, ``Flow``, and default arguments are part of its
   public API, so Java is not a supported integration path.

Before you begin
================

- Create an OTP application and obtain its credentials in the environment where the SDK will
  send verification requests. See
  :ref:`Getting Started <otp_verification_getting_started>`.
- Set the OTP application's **Callback URL** to an endpoint on your backend. Configure that
  endpoint to verify callback signatures using the application secret and return ``allow`` or
  ``deny``. See :ref:`Callbacks <otp_verification_callbacks>`.
- Keep the OTP application's minimum authentication mode set to ``public`` so requests made
  with ``Auth.Public`` are accepted.
- Copy the application key into the Android app and use it with ``Auth.Public``. Keep the
  application secret on your backend; do not include it in the APK.
- Choose the :ref:`verification methods <otp_verification_methods>` your app will support and
  add the matching SDK artifact. Use ``verification-all`` to select methods at runtime,
  ``verification-sms`` for SMS only, or ``verification-core`` for phone call only. See
  `Installation`_.
- Collect each handle's ``states`` flow exactly once from a lifecycle-aware scope such as
  ``viewModelScope``. The first collection sends the verification request. See
  `Collect once`_.
- Provide manual code entry for every supported method. Automatic SMS capture requires Google
  Play Services and should supplement, rather than replace, manual entry. See
  `Automatic SMS capture`_.

----

How a verification flows
========================

The SDK models a verification as a **state machine** rather than a sequence of separate
requests. Your app starts a handle, collects its states, and submits the user's code. Each
outcome, including success, failure, denial, and expiry, is returned as a state.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "primaryColor": "#e0f2fe",
       "primaryBorderColor": "#38bdf8",
       "primaryTextColor": "#1f2d3d",
       "lineColor": "#38bdf8",
       "secondaryColor": "#ccfbf1",
       "tertiaryColor": "#fef3c7",
       "fontSize": "14px"
     }
   }}%%

   stateDiagram-v2
       [*] --> Starting: First collection starts create or lookup

       Starting --> AwaitingInput
       Starting --> Denied
       Starting --> SetupError
       Starting --> Failed

       AwaitingInput --> Submitting: Submit a value
       AwaitingInput --> Captured: SMS code captured</br>automatically
       Captured --> Submitting

       Submitting --> Verified
       Submitting --> AwaitingInput: Rejected, lastError set
       Submitting --> Failed
       Submitting --> Expired

       Verified --> [*]
       Failed --> [*]
       Denied --> [*]
       SetupError --> [*]
       Expired --> [*]

Your app does not verify the code itself. It collects the code from the user and passes it to
the SDK. The SDK handles the network requests and state transitions, while your app owns the
user interface.

If the user submits an incorrect code, the verification can remain open for another attempt.
The flow returns to ``AwaitingInput`` with ``lastError`` set, so your app can show the error
while still accepting a new value. If the API returns ``too_many_attempts``, the verification
becomes terminal.

States
------

.. list-table::
   :header-rows: 1
   :widths: 24 56 20

   * - State
     - Meaning
     - Terminal
   * - ``Starting``
     - The create request from ``start(...)`` or the by-number lookup from ``resume(...)`` is
       in flight.
     -
   * - ``AwaitingInput``
     - The verification is waiting for a code. Carries ``verificationId`` and may also provide
       ``deliveryMethod``, ``destination``, ``fee``, ``expiresAtEpochMillis``, ``sms``, and
       ``lastError``.
     -
   * - ``Captured``
     - An SMS code was captured automatically and is about to be submitted. See
       `Automatic SMS capture`_.
     -
   * - ``Submitting``
     - A value is in flight.
     -
   * - ``Verified``
     - The server accepted the value.
     - Yes
   * - ``Failed``
     - Carries a ``FailureReason`` — either an API error or an SDK-side one.
     - Yes
   * - ``Denied``
     - The application's callback rejected the request or did not return a usable response.
     - Yes
   * - ``SetupError``
     - The OTP application is misconfigured. Retrying or changing user input cannot resolve
       it.
     - Yes
   * - ``Expired``
     - The deadline passed with no accepted value.
     - Yes

.. note::

   The ``fee`` value on ``AwaitingInput`` is the quoted verification fee, not an immediate
   charge. It is billed only when the verification reaches ``Verified``. The quote does not
   include the SMS or call used to deliver the challenge, which is billed separately.

Installation
============

The SDK is published as three artifacts. Choose the artifact that matches the delivery methods
your app uses. All artifacts use the ``com.didww.android.sdk.verification`` group ID and are
published to Maven Central.

.. list-table::
   :header-rows: 1
   :widths: 26 44 30

   * - Artifact
     - Contains
     - Depend on it when
   * - ``verification-core``
     - Transport, error model, state machine, and phone call.
     - You only use phone call.
   * - ``verification-sms``
     - ``verification-core`` plus the SMS channel and Google Play Services integration.
     - You only send SMS.
   * - ``verification-all``
     - The umbrella artifact, including ``DidwwVerification``.
     - You choose the channel at runtime.

.. code-block:: kotlin

   // settings.gradle.kts — repositories { mavenCentral() }

   dependencies {
       implementation("com.didww.android.sdk.verification:verification-all:1.0.0")
   }

.. note::

   ``verification-core`` directly declares only ``INTERNET``. ``verification-sms`` also brings
   in Google Play Services and related AndroidX manifest components through its dependencies,
   but it does not require a dangerous runtime permission. Apps that do not use SMS can depend
   on ``verification-core`` to avoid those SMS-related dependencies. See the
   `measured manifest breakdown
   <https://github.com/didww/didww-verification-android-sdk/blob/main/docs/manifest-cost.md>`__.

Quick start
===========

The following example keeps the SDK client and verification handle in a ``ViewModel``. It
starts an SMS verification, collects the handle exactly once, and exposes the current state to
the UI through a ``StateFlow``:

.. code-block:: kotlin

   import android.app.Application
   import androidx.lifecycle.AndroidViewModel
   import androidx.lifecycle.viewModelScope
   import com.didww.android.sdk.verification.Auth
   import com.didww.android.sdk.verification.DeliveryMethod
   import com.didww.android.sdk.verification.Environment
   import com.didww.android.sdk.verification.VerificationHandle
   import com.didww.android.sdk.verification.VerificationState
   import com.didww.android.sdk.verification.all.DidwwVerification
   import kotlinx.coroutines.flow.MutableStateFlow
   import kotlinx.coroutines.flow.StateFlow
   import kotlinx.coroutines.flow.asStateFlow
   import kotlinx.coroutines.launch

   class VerifyViewModel(application: Application) : AndroidViewModel(application) {

       private val didww = DidwwVerification(
           context = application,
           auth = Auth.Public(BuildConfig.DIDWW_APPLICATION_KEY),
           environment = Environment.Sandbox,
       )

       private val _state = MutableStateFlow<VerificationState?>(null)
       val state: StateFlow<VerificationState?> = _state.asStateFlow()

       private var handle: VerificationHandle? = null

       fun start(destination: String) {
           val started = didww.start(destination, DeliveryMethod.SMS)
           handle = started
           _state.value = null

           // Collect each handle once, outside the view layer.
           viewModelScope.launch {
               started.states.collect { emission ->
                   // An older handle must not overwrite the state of a newer start.
                   if (started === handle) _state.value = emission
               }
           }
       }

       fun submit(value: String) {
           handle?.submit(value)
       }
   }

Render the ``StateFlow`` with lifecycle awareness. The UI functions below are placeholders for
your own components:

.. code-block:: kotlin

   import androidx.compose.runtime.Composable
   import androidx.compose.runtime.getValue
   import androidx.lifecycle.compose.collectAsStateWithLifecycle

   @Composable
   fun VerifyScreen(viewModel: VerifyViewModel) {
       val state by viewModel.state.collectAsStateWithLifecycle()

       when (val current = state) {
           null -> PhoneNumberEntry(onStart = viewModel::start)
           VerificationState.Starting -> Spinner("Requesting a code")
           is VerificationState.AwaitingInput -> CodeEntry(
               hint = current.sms?.template,
               error = current.lastError?.detail,
               expiresAt = current.expiresAtEpochMillis,
               onSubmit = viewModel::submit,
           )
           is VerificationState.Captured -> Spinner("Code received")
           VerificationState.Submitting -> Spinner("Checking")
           is VerificationState.Verified -> Success()
           is VerificationState.Failed -> Failure(current.reason)
           is VerificationState.Denied -> Failure(current.error?.detail)
           is VerificationState.SetupError -> Misconfigured(current.code, current.detail)
           VerificationState.Expired -> Expired()
       }
   }

Calling ``start()`` does not send the request. It only creates the handle. The request starts
when your app first collects ``handle.states``. This example uses the sandbox; switch to
``Environment.Production`` and production credentials for live verifications.

The SDK retains ``context.applicationContext`` internally. Passing an ``Activity`` as the
constructor context does not cause the SDK to retain that ``Activity``.

Collect once
------------

.. warning::

   ``handle.states`` is a cold ``Flow`` and can be collected only once. If it is collected a
   second time, the handle emits ``Failed(FailureReason.Sdk(SdkError.AlreadyRunning))``. After
   that, the same handle cannot be used again.

Collect ``handle.states`` from a ``ViewModel``-scoped coroutine and mirror the states into a
``StateFlow`` for the UI to render. Do not collect directly from a composable or an
``Activity`` that can be recreated.

This keeps lifecycle events, such as screen rotation, from attempting to collect the same
handle again. Reuse the same ``DidwwVerification`` instance across starts so its in-process
supersession tracking also remains active.

The first collection starts the request. Cancelling the collection cancels the in-flight
request and releases resources registered by the channel. There is no separate ``stop()``
method. To retry, start a new handle.

Submitting a value
------------------

The handle can receive submitted values as soon as it is created. If the user submits a value
before ``AwaitingInput`` is emitted, the SDK buffers it instead of dropping it.

``submit()`` never blocks and never throws, so your UI does not need to wait for a network
round trip to call it. Disable repeated submission while the state is ``Submitting``. Every
submitted value is queued, so duplicate taps can produce additional report attempts.

A submitted value can be accepted only after the verification has been dispatched, such as
after the SMS is sent or the call is placed. If a value is submitted too early, the API returns
``ApiErrorCode.NOT_READY_TO_REPORT`` (``not_ready_to_report``). This is retryable: the state
machine returns to ``AwaitingInput`` with ``lastError`` set. The value can be submitted again
after the verification is ready.

Expiry
------

``AwaitingInput.expiresAtEpochMillis`` is the server-provided expiry time for the
verification. The SDK does not define its own TTL.

The local countdown uses elapsed time instead of the device wall clock, so time changes on the
device, such as an NTP correction or a manual date change, do not shorten the verification
window.

The SDK can emit ``Expired`` from this local countdown, but the server remains authoritative. A
late submitted value is still sent to the API, and ``Expired`` is not emitted while a submission
is in flight.

Delivery methods
================

``DidwwVerification`` selects the delivery method at runtime:

.. code-block:: kotlin

   didww.start(number, DeliveryMethod.SMS)     // a code by text message
   didww.start(number, DeliveryMethod.CALLOUT) // a spoken code

If your app uses only one delivery method, you can use its channel-specific class directly:

.. code-block:: kotlin

   import com.didww.android.sdk.verification.sms.SmsVerification          // verification-sms
   import com.didww.android.sdk.verification.callout.CalloutVerification  // verification-core

   SmsVerification(context, auth).start(number)
   CalloutVerification(context, auth).start(number)

For both ``SMS`` and ``CALLOUT``, the user submits the code they received.

Delivery-method options
-----------------------

Method-specific options use the same name as the delivery method. For example, SMS options are
passed with ``sms`` in Kotlin and sent as an ``sms`` block in the API request.

.. code-block:: kotlin

   didww.start(number, DeliveryMethod.SMS, sms = SmsOptions(languages = listOf("en-US")))

The SDK also computes the Android SMS Retriever app hash when it is available. The resulting
request has this form:

.. code-block:: json

   {
     "data": {
       "destination": "+4915112345678",
       "delivery_method": "sms",
       "sms": {
         "languages": ["en-US"],
         "app_hash": "<computed-app-hash>"
       }
     }
   }

``CALLOUT`` takes the announcement language the same way:

.. code-block:: kotlin

   didww.start(number, DeliveryMethod.CALLOUT, callout = CalloutOptions(languages = listOf("de-DE")))

``SmsOptions.languages`` and ``CalloutOptions.languages`` accept the same tags with the same
semantics, so one language list works for both delivery methods. The catalogues behind them
differ, however: the announcement recordings are a different set from the message templates,
so a tag that is honored for SMS can still fall back for a phone call. See
:ref:`SMS languages <otp_verification_sms_languages>` and
:ref:`phone call languages <otp_verification_callout_languages>`.

Passing options for a different channel throws ``IllegalArgumentException`` before the request
is sent:

.. code-block:: kotlin

   didww.start(number, DeliveryMethod.CALLOUT, sms = SmsOptions(...))   // throws

The API reads only the options block that matches ``delivery_method``. The SDK rejects
mismatched options early so the app does not start a verification with unintended defaults.

In the response, ``AwaitingInput.sms`` contains SMS-specific details returned by the API:
``template`` (the message with ``{{CODE}}`` still in it), ``language`` (the template language
the API selected), and ``interceptionTimeoutSeconds``. ``AwaitingInput.callout`` contains
``language``, the language the announcement was played in. Both report what the API
**selected**, which is not necessarily the first language requested.

Resume after process recreation
===============================

A ``VerificationHandle`` exists only in memory. If Android terminates your app process after a
verification starts, persist the destination and use ``resume(...)`` to reattach to the latest
verification for that number. Do not call ``start(...)`` to recover an existing verification;
starting another one supersedes the previous verification and sends a new challenge.

Like ``start(...)``, ``resume(...)`` performs no I/O until the returned handle's ``states``
flow is collected:

.. code-block:: kotlin

   fun resume(destination: String) {
       val resumed = didww.resume(destination, DeliveryMethod.SMS)
       handle = resumed
       _state.value = null

       viewModelScope.launch {
           resumed.states.collect { emission ->
               if (resumed === handle) _state.value = emission
           }
       }
   }

The SDK removes non-digit characters from the destination when it builds the by-number path,
so formatted and unformatted versions of the same number reach the same endpoint. A value with
no digits throws ``IllegalArgumentException`` before a request is sent.

The resumed handle behaves according to the verification found by the API:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - API result
     - State emitted by the handle
   * - The latest verification is active
     - ``AwaitingInput``. The app can submit the code through the resumed handle.
   * - The latest verification is finished
     - Its terminal state, such as ``Verified``, ``Failed``, ``Denied``, or ``Expired``.
   * - No verification exists for the number
     - ``Failed`` with an API error whose ``known`` value is ``ApiErrorCode.NOT_FOUND``.

The ``method`` argument selects the channel-specific client behavior. For SMS, it enables the
automatic capture checks. The delivery method returned by the API remains authoritative and is
used when the SDK reports a submitted value.

See :ref:`Get verification status by number
<otp_verification_api_status_by_number>` and :ref:`Report a verification by number
<otp_verification_api_report_by_number>` for the underlying API behavior.

Environments
============

Choose the environment when creating the SDK client. If no environment is provided, the SDK
uses ``Environment.Production``. The SDK removes a trailing slash from the selected base URL
and appends ``/api/v1``.

.. list-table::
   :header-rows: 1
   :widths: 34 66

   * - Environment
     - Host
   * - ``Environment.Production`` (default)
     - ``https://verification.didww.com``
   * - ``Environment.Sandbox``
     - ``https://verification-sandbox.didww.com``
   * - ``Environment.Custom(url)``
     - A custom scheme and host, optionally with a base path, for a local backend, proxy, or
       test server.

.. note::

   Use ``Environment.Sandbox`` while building and testing your integration.

   Use credentials from an OTP application created in the same environment as the SDK client.
   See :ref:`Choose an environment <otp_verification_environments>`.

   .. code-block:: kotlin

      DidwwVerification(context, auth, Environment.Sandbox)
      DidwwVerification(context, auth, Environment.Custom("http://10.0.2.2:3000"))

Timeouts are configured through ``Config``. See `Cancellation and timeouts`_.

Authentication
==============

.. list-table::
   :header-rows: 1
   :widths: 30 40 30

   * - Scheme
     - Header
     - Use
   * - ``Auth.Public(applicationKey)``
     - ``Application <key>``
     - Production, on-device.
   * - ``Auth.Basic(key, secret)``
     - ``Basic base64(key:secret)``
     - Local development only.

Use ``Auth.Public`` for production mobile apps. The application key identifies your
application, but it does not by itself authorize a verification. DIDWW asks your application's
callback URL to approve each request before sending an SMS or phone call. This corresponds to
the API's :ref:`public auth mode <otp_verification_authentication>`.

.. warning::

   ``Auth.Basic`` uses a server-to-server secret. Do not include this secret in a production
   mobile app, because it can be recovered from the APK. The SDK logs a warning at runtime if
   ``Auth.Basic`` is used in a build that is not marked debuggable. If this secret has already
   been shipped in an app, treat it as disclosed and rotate it.

Keep the OTP application's **minimum auth mode** set to ``public`` when it is used by the
Android SDK. Raising the minimum auth mode rejects SDK requests: ``basic`` requires a secret
in the APK, and signed authentication also requires a signing secret on the device. Use a
stricter minimum auth mode only for applications driven by your own server.

A start can come back denied
============================

With ``Auth.Public``, DIDWW asks your application's :ref:`request callback
<otp_verification_callbacks>` to authorize the start request before sending an SMS or phone
call. If the callback denies the request, the HTTP request can still succeed with
``201 Created`` and the flow reaches ``Denied`` rather than ``AwaitingInput``.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",

       "signalColor": "#1f2d3d",
       "signalTextColor": "#1f2d3d",

       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#facc15",
       "noteTextColor": "#1f2d3d",

       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d",
       "loopTextColor": "#1f2d3d"
     }
   }}%%

   sequenceDiagram
       participant SDK as Verification SDK
       participant API as Verification API
       participant CB as Your backend

       SDK->>API: POST /api/v1/verifications
       API->>CB: POST {callback_url}<br/>Authorization: Application {appKey}:{signature}<br/>x-timestamp: {unix seconds}
       Note over CB: verify the signature,<br/>then decide

       alt your backend allows
           CB-->>API: 200 {"action":"allow"}
           API-->>SDK: 201 Created — AwaitingInput
       else your backend denies
           CB-->>API: 200 {"action":"deny"}
           API-->>SDK: 201 Created — Denied<br/>denied_by_callback
       else no usable answer
           CB--xAPI: non-2xx, timeout, invalid JSON,<br/>unknown action, or a body over 8 KB
           API-->>SDK: 201 Created — Denied<br/>denied_invalid_callback_response
       end

       Note over SDK,CB: No challenge is dispatched in either denied branch.

SetupError means a configuration problem
----------------------------------------

``SetupError`` indicates a configuration problem that the user cannot fix. With
``Auth.Public``, this happens when the application has no callback URL configured. In that
case, each start request is denied with ``denied_missing_callback_url`` until a callback URL
is added.

.. code-block:: kotlin

   is VerificationState.SetupError ->
       // Retrying will not help; no user input can rescue it.
       Log.e("didww", "verification misconfigured: ${state.code} ${state.detail}")

Treat ``SetupError`` as an application configuration issue, not as a phone number problem.
Log it or report it to your team, and avoid showing it to the end user as a retryable
verification failure. See :ref:`Callbacks <otp_verification_callbacks>`.

Automatic SMS capture
=====================

**SMS codes can be captured automatically.** The SDK computes the app's SMS Retriever hash,
sends it with each SMS verification, and starts listening only when the API response echoes the
same hash. When a matching message arrives, the flow moves to ``Captured`` and submits the code
without the user typing it. Handle ``VerificationState.Captured`` as a normal part of your
flow.

**The SMS Retriever app hash does not need manual configuration.** The SDK computes it at
runtime from the certificate used to sign the installed APK. This is the certificate that
Google Play services checks when matching incoming SMS messages.

No extra configuration is needed for Play App Signing. If Google re-signs the app before
installation, the SDK reads the certificate used on the installed APK and computes the matching
hash from it.

Automatic capture begins after the create or resume response is decoded. An SMS that arrives
before that point cannot be captured by the SDK, so manual entry must remain available.

.. note::

   Always provide manual entry as a fallback. Manual entry works for SMS and phone call and
   remains available while automatic capture is listening. Automatic SMS capture requires
   Google Play services and is not available when the app depends on ``verification-core``
   alone, because that artifact does not include the SMS channel.

``AwaitingInput.sms.interceptionTimeoutSeconds`` is the automatic capture window, not the
verification deadline. It tells the SDK how long to keep listening for a matching SMS. When
the window ends, the SDK stops listening, but the verification remains active and manual entry
still works. ``expiresAtEpochMillis`` is the value that defines when the verification expires.

The SDK writes limited diagnostics to Android Logcat under the ``DidwwVerification`` tag,
including app-hash availability, the computed app hash, and SMS Retriever re-arming. These
diagnostics do not include OTP codes, phone numbers, or credentials.

Error handling
==============

A failed verification is reported through the state flow rather than thrown as an exception.
Each verification outcome is represented as a ``VerificationState``.

Two invalid calls throw ``IllegalArgumentException`` synchronously, before a request is sent:

- Passing ``sms`` options to a non-SMS delivery method.
- Calling ``resume(...)`` with a destination that contains no digits.

``Failed`` carries a ``FailureReason`` with either an API error or an SDK-side error:

.. code-block:: kotlin

   when (val reason = state.reason) {
       is FailureReason.Api -> reason.error       // the server said no — an ApiErrorItem
       is FailureReason.Sdk -> when (reason.error) {
           is SdkError.Transport   -> "offline, timed out, or TLS failed"
           is SdkError.Decoding    -> "the response could not be read"
           SdkError.Superseded     -> "another verification replaced this one"
           SdkError.AlreadyRunning -> "states was collected twice — see Collect once"
       }
   }

SDK-side failures have the following meanings:

.. list-table::
   :header-rows: 1
   :widths: 36 64

   * - Error
     - Meaning
   * - ``SdkError.Transport``
     - The request did not complete because of DNS, connection, TLS, timeout, socket, or URL
       failure. A non-successful HTTP response without a usable API error envelope is also
       reported here.
   * - ``SdkError.Decoding``
     - A successful HTTP response could not be decoded as a verification.
   * - ``SdkError.Superseded``
     - A newer handle from the same SDK client replaced this handle for the same destination.
   * - ``SdkError.AlreadyRunning``
     - The handle's ``states`` flow was collected more than once.

Server-side errors are returned as ``ApiErrorItem`` values, matching the API's
:ref:`coded error envelope <otp_verification_api_errors>`:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Property
     - Meaning
   * - ``code``
     - The raw slug, always present — for example ``code_invalid``.
   * - ``detail``
     - Fixed human-readable text. Display it; never branch on it.
   * - ``known``
     - The typed ``ApiErrorCode`` when this SDK version recognises the slug, otherwise ``null``.

.. code-block:: kotlin

   when (error.known) {
       ApiErrorCode.CODE_INVALID      -> showError("That code is not right.")
       ApiErrorCode.TOO_MANY_ATTEMPTS -> showError("Too many attempts. Start over.")
       ApiErrorCode.BALANCE_INSUFFICIENT,
       ApiErrorCode.UNAUTHORIZED      -> reportToYourBackend(error.code)
       null                           -> showError(error.detail)   // a slug newer than this SDK
       else                           -> showError(error.detail)
   }

``ApiErrorCode`` does not have an ``.other`` case. If the SDK receives an error code it does
not recognise, ``known`` is ``null`` and ``code`` still contains the raw value. This lets the
SDK decode newer API error codes without losing the original code. Branch on ``code`` or
``known``, never on ``detail``.

Cancellation and timeouts
=========================

Cancellation uses standard coroutine cancellation. Because the request starts when ``states``
is collected, cancelling the collecting coroutine cancels the in-flight request and releases
resources registered by the channel, including an active SMS listener. There is no separate
``stop()`` method. When a ``ViewModel`` is cleared, its coroutine scope is cancelled
automatically. Cancellation ends collection without emitting a ``Failed`` state.

.. code-block:: kotlin

   val job = viewModelScope.launch {
       handle.states.collect { _state.value = it }
   }

   job.cancel()   // cancels the request and releases everything the channel registered

Per-request timeouts are configured through ``Config``. They are transport timeouts, not the
verification expiry policy. A verification expires according to the server-provided
``expiresAtEpochMillis`` value:

.. code-block:: kotlin

   DidwwVerification(
       context, auth, Environment.Production,
       Config(connectTimeoutMillis = 15_000, readTimeoutMillis = 30_000),   // the defaults
   )

One active verification per number
==================================

Only one unfinished verification can exist for the same application and phone number. If your
app collects a new start handle for a number that already has a verification in progress, the
new verification supersedes the previous one on the server.

The SDK marks the older handle as ``SdkError.Superseded`` as soon as another handle is created
by the same ``DidwwVerification`` instance with the same destination string. This local signal
can therefore arrive before the new handle is collected. Reuse one client instance across
starts so this in-process tracking remains available. Different formatting, such as
``+49 151...`` and ``49151...``, is not normalized for this local comparison.

If another client, process, device, or backend supersedes the verification, the current handle
learns about it only after its next request is rejected. The API does not push this update to
the SDK.

Android SDK behavior
====================

.. list-table::
   :header-rows: 1
   :widths: 34 66

   * - Capability
     - On Android
   * - Polling for status
     - The SDK does not provide ``status()``. The ``states`` flow reports transitions caused by
       the handle's requests and local expiry countdown.
   * - Resume by phone number
     - ``resume(destination, method)`` looks up the latest verification for the number and
       returns a new state-driven handle. Use it after process recreation when the original
       handle is no longer available.
   * - Report requests
     - A handle created by ``start(...)`` reports by verification ID. A handle created by
       ``resume(...)`` reports through the by-number endpoint. The Android SDK uses ``PUT`` for
       both report forms.
   * - Language
     - Kotlin. Coroutines and ``Flow`` are part of the public surface, so Java is not a
       supported integration path.

Sample application
==================

The `Android SDK sample application
<https://github.com/didww/didww-verification-android-sdk/tree/main/sample>`__ demonstrates
state rendering, lifecycle-aware collection, automatic SMS capture, repeated starts, and SDK
error handling.


.. _otp_verification_sdk_dart:

=======================
Dart and Flutter SDK
=======================

The Dart SDK is a client for the :ref:`Verification API <otp_verification_api_reference>`. It
is **pure Dart on** ``dart:io`` **with no dependencies**, so it runs on the Dart VM and in
Flutter and adds nothing to your dependency tree.

It ships as two packages:

.. list-table::
   :header-rows: 1
   :widths: 34 66

   * - Package
     - Contents
   * - ``didww_verification``
     - ``VerificationClient`` (the five endpoints) and ``VerificationSession`` (the state
       machine a screen needs). Pure Dart.
   * - ``didww_verification_sms``
     - A Flutter plugin implementing automatic SMS code capture on Android over the SMS
       Retriever API. Optional, and a no-op off Android.

Most Flutter applications want the session. A server-side Dart process can use the client
alone.

.. note::

   On-device use omits the signed ``application`` authentication mode because a signing secret
   must never be included in an app. Use the ``public`` mode, where your backend authorizes
   each start request through a :ref:`callback <otp_verification_callbacks>`.

----

Requirements
============

.. list-table::
   :widths: 30 70

   * - Dart SDK
     - 3.6 or later.
   * - Flutter
     - 3.27 or later, for ``didww_verification_sms``.
   * - Dependencies
     - None for ``didww_verification``.

Installation
============

.. code-block:: yaml

   dependencies:
     didww_verification: ^0.1.0
     didww_verification_sms: ^0.1.0   # optional: Android SMS auto-capture

.. important::

   **Android release builds need ``INTERNET`` declared.** Flutter's application template
   declares ``android.permission.INTERNET`` in
   ``android/app/src/debug/AndroidManifest.xml`` and ``.../profile/AndroidManifest.xml``, but
   **not** in ``main/``. A debug build works and the release build has no network, and the
   first request fails with a socket error that reads like an SDK fault. Declare it yourself:

   .. code-block:: xml

      <!-- android/app/src/main/AndroidManifest.xml -->
      <uses-permission android:name="android.permission.INTERNET" />

Quick start
===========

``VerificationClient`` is the five endpoints:

.. code-block:: dart

   import 'package:didww_verification/didww_verification.dart';

   final client = VerificationClient(
     auth: const PublicAuthorization('your-application-key'),
     environment: VerificationEnvironment.sandbox,
   );

   final started = await client.startVerification(
     destination: '+49 151 1234567',
     deliveryMethod: DeliveryMethod.sms,
     sms: const SmsOptions(languages: ['en-US']),
   );

   started.id;            // '0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21'
   started.knownStatus;   // VerificationStatus.pending
   started.sms?.language; // 'en-US'

   final finished = await client.reportVerification(
     started.id,
     deliveryMethod: started.deliveryMethod,
     value: const ReportValue.code('123456'),
   );

   finished.knownStatus;  // VerificationStatus.verified

   client.close();

Every method returns a new ``Verification`` describing the state at that moment. Objects are
snapshots and are never updated in place. Call ``close()`` when the client is no longer
needed.

``VerificationSession``: the state machine
==========================================

``VerificationSession`` wraps the client in the state machine a screen actually needs: one
stream of states, single-flighted calls, and automatic code capture when you supply it.

.. code-block:: dart

   final session = VerificationSession(
     client: VerificationClient(auth: const PublicAuthorization('your-application-key')),
   );

   // In a widget:
   StreamBuilder<VerificationState>(
     stream: session.states,
     initialData: session.state,
     builder: (context, snapshot) => switch (snapshot.data!) {
       VerificationIdle() || VerificationStarting() => const CircularProgressIndicator(),
       VerificationAwaitingInput(:final lastError) => CodeField(
           error: lastError?.detail,
           onSubmitted: session.submit,
         ),
       VerificationCaptured(:final value) => CodeField(value: value, enabled: false),
       VerificationSubmitting() => const CircularProgressIndicator(),
       VerificationVerified() => const Text('Verified'),
       VerificationExpired() => const Text('That code expired'),
       VerificationDenied(:final error) => Text(error?.detail ?? 'Refused'),
       VerificationSetupError(:final code) => Text('Application misconfigured: $code'),
       VerificationFailed(:final reason) => Text('$reason'),
     },
   );

   await session.start(
     destination: '+49 151 1234567',
     deliveryMethod: DeliveryMethod.sms,
   );

Call ``session.dispose()`` from ``State.dispose``. It is awaitable, safe to call twice, and
cancels every subscription and timer.

``states`` returns **the same object on every call**, so ``StreamBuilder`` does not
resubscribe on each rebuild. Every new listener receives the current state immediately.

The states
----------

``VerificationState`` is sealed, so the switch above needs no ``default`` arm and a state
added in a later release is a compile error rather than a silent gap.

.. list-table::
   :header-rows: 1
   :widths: 30 12 58

   * - State
     - Terminal
     - Means
   * - ``VerificationIdle``
     -
     - Nothing started, or ``reset()`` was called.
   * - ``VerificationStarting``
     -
     - The start or resume request is in flight.
   * - ``VerificationAwaitingInput``
     -
     - Live. Carries the id, the channel, ``expiresAt``, the ``sms`` or ``callout`` block and
       ``lastError``.
   * - ``VerificationCaptured``
     -
     - A code was recovered from a message and is about to be submitted.
   * - ``VerificationSubmitting``
     -
     - A report is in flight.
   * - ``VerificationVerified``
     - ✔
     - The reported value was correct.
   * - ``VerificationExpired``
     - ✔
     - The API says the deadline passed.
   * - ``VerificationDenied``
     - ✔
     - Refused before dispatch.
   * - ``VerificationSetupError``
     - ✔
     - The application is misconfigured; no user input can fix it.
   * - ``VerificationFailed``
     - ✔
     - Anything else, with an ``ApiFailure`` or an ``SdkFailure``.

Calls that cannot go wrong
--------------------------

- ``start()`` and the resumes **never throw**. Every outcome, failure included, arrives
  through ``states``.
- A second ``start()`` while one is in flight sends nothing and reports
  ``SdkFailure(SdkAlreadyRunning())``.
- A second ``submit()`` while one is in flight is dropped, so a double tap cannot burn two
  attempts. ``submit()`` before the verification is live is buffered; after a terminal state
  it is ignored.
- ``submit()`` returns nothing on purpose. **Drive your spinner from** ``states``, never from
  the call — every case where the value is dropped is one where the current state already says
  why.

Authentication
==============

.. list-table::
   :header-rows: 1
   :widths: 34 30 36

   * - Scheme
     - Header
     - Use it
   * - ``PublicAuthorization(key)``
     - ``Application <key>``
     - On a device. Carries no secret.
   * - ``BasicAuthorization(key: …, secret: …)``
     - ``Basic <base64(key:secret)>``
     - Server-side only.

.. warning::

   **A secret compiled into an application binary is recoverable** — a release APK or IPA is a
   file someone can unzip. ``PublicAuthorization`` exists so an app never has to carry one.
   Reach for ``BasicAuthorization`` only where the process is yours.

Request signing is a third scheme the API accepts and this package deliberately does not
implement: it needs a signing secret, which is the thing an app must not hold.

.. note::

   Never append anything to the application key. The API routes on the first colon anywhere
   after the ``Application `` prefix, so ``Application key:anything`` selects the signed scheme
   and fails authentication rather than falling back.

A ``public`` start is authorized by a callback to **your** server before the verification is
created. If your application has no callback URL registered, every ``public`` start comes back
already denied with ``denied_missing_callback_url``. See
:ref:`Callbacks <otp_verification_callbacks>`.

Environments
============

.. code-block:: dart

   VerificationClient(auth: auth);  // production
   VerificationClient(auth: auth, environment: VerificationEnvironment.sandbox);
   VerificationClient(
     auth: auth,
     environment: VerificationEnvironment.custom(Uri.parse('https://proxy.example.com/verify')),
   );

A custom base carries a scheme, a host and optionally a base path. The SDK appends the API
version itself, so do not include it.

Methods
=======

.. list-table::
   :header-rows: 1
   :widths: 52 48

   * - Method
     - Endpoint
   * - ``startVerification(...)``
     - ``POST /verifications``
   * - ``reportVerification(id, ...)``
     - ``PUT /verifications/{id}``
   * - ``getVerification(id)``
     - ``GET /verifications/{id}``
   * - ``reportVerificationByNumber(number, ...)``
     - ``PUT /verifications/by_number/{number}``
   * - ``getVerificationByNumber(number)``
     - ``GET /verifications/by_number/{number}``

The SDK adds the ``/api/v1`` base path to these requests.

``getVerificationByNumber`` returns the newest verification for a number whatever its status.
That is usually the live one, because a start supersedes what came before it — but a start
that was itself *denied* supersedes nothing, so it is newest while an earlier verification is
still live. It bills nothing, which makes it the cheap way to reattach after a screen was
rebuilt or the app was restarted.

Delivery-method options
=======================

Method-specific options travel in a parameter named after the delivery method, and the SDK
sends only the block matching ``deliveryMethod``:

.. code-block:: dart

   await client.startVerification(
     destination: destination,
     deliveryMethod: DeliveryMethod.sms,
     sms: const SmsOptions(languages: ['pl-PL', 'en-US']),
   );

   await client.startVerification(
     destination: destination,
     deliveryMethod: DeliveryMethod.callout,
     callout: const CalloutOptions(languages: ['pt-BR', 'pt-PT']),
   );

``SmsOptions.languages`` and ``CalloutOptions.languages`` accept the same tags with the same
semantics, so one language list works for both delivery methods. The catalogues behind them
differ, however: the announcement recordings are a different set from the message templates,
so a tag that is honored for SMS can still fall back for a phone call. See
:ref:`SMS languages <otp_verification_sms_languages>` and
:ref:`phone call languages <otp_verification_callout_languages>`.

.. note::

   ``app_hash`` is not part of ``SmsOptions``. It is a property of the installed Android build
   rather than a choice a caller makes, and a malformed one fails the whole verification, so
   it is supplied by the capture implementation and validated before it reaches the wire.
   ``startVerification`` takes an ``appHash`` parameter for that path; a value that is not
   eleven characters of ``[A-Za-z0-9+/]`` is **dropped**, and the request goes out identical
   to one that never carried a hash. Losing autofill beats failing a paid verification.

Reporting a value
=================

``ReportValue`` is sealed and single-field, so supplying no value — or a value that is not the
one the channel expects — cannot be expressed:

.. list-table::
   :header-rows: 1
   :widths: 26 74

   * - Delivery method
     - Value
   * - ``sms``
     - ``const ReportValue.code('123456')``
   * - ``callout``
     - ``const ReportValue.code('123456')``

``reportVerification`` throws ``ChannelMismatchException`` **before sending anything** when the
value does not suit the channel.

Verification responses
======================

.. list-table::
   :header-rows: 1
   :widths: 30 26 44

   * - Field
     - Dart type
     - Description
   * - ``id``
     - ``String``
     - Verification identifier.
   * - ``destination``
     - ``String``
     - Destination number normalized without a leading ``+``.
   * - ``deliveryMethod``
     - ``String``
     - Raw delivery method. ``knownDeliveryMethod`` is the typed value, or ``null`` when this
       release does not model it.
   * - ``status``
     - ``String``
     - Raw status. ``knownStatus`` is the typed value; ``isFinished`` is ``false`` for a
       status this release does not model, never a guess.
   * - ``fee``
     - ``String?``
     - Quoted verification fee, as a decimal string. Never parse it as a ``double``.
   * - ``errorCode``
     - ``String?``
     - Raw outcome code. ``knownErrorCode`` is the typed value; ``outcome`` is the same as an
       ``ApiErrorItem``.
   * - ``errorDetail``
     - ``String?``
     - Human-readable text for ``errorCode``.
   * - ``expiresAt``
     - ``DateTime``
     - The deadline, in UTC.
   * - ``sms``
     - ``SmsInfo?``
     - SMS response fields. It is ``null`` for a phone call.
   * - ``callout``
     - ``CalloutInfo?``
     - Phone call response fields. It is ``null`` for SMS.

Reading delivery-method details
-------------------------------

.. code-block:: dart

   verification.sms?.template;                   // 'Your code is {{CODE}}'
   verification.sms?.language;                   // 'en-US'
   verification.sms?.interceptionTimeoutSeconds; // 120
   verification.sms?.appHash;                    // 'A1b2C3d4E5f', or null

   verification.callout?.language;               // 'de-DE'

Both ``language`` values report the language the API **selected**, which is not necessarily
the first one requested. Compare with the list you sent to detect a fallback to ``en-US``.

``interceptionTimeoutSeconds`` is **a budget, not a deadline and not a countdown.** It says
how long to keep an on-device listener armed. It does not shorten the verification: manual
entry keeps working until ``expiresAt``. Do not render it as a timer to the user.

Automatic SMS capture
=====================

``start()`` and ``submit()`` work identically with and without it; without it the user types
the code. Supply an ``SmsAutoCapture`` to have it filled in:

.. code-block:: dart

   import 'package:didww_verification_sms/didww_verification_sms.dart';

   final session = VerificationSession(
     client: client,
     autoCapture: const SmsRetrieverAutoCapture(), // a no-op off Android
   );

On Android this is implemented over the SMS Retriever API, so the app needs no SMS permission
and sees no message but its own. Everywhere else, capture reports that it has nothing rather
than throwing, so an app can depend on the package unconditionally.

``hasAutoCapture`` is true from construction, so a screen can decide up front whether to
promise the user anything. ``isAutoCaptureArmed`` is true only once capture is actually
running for the current verification.

Capture arms **only when the API echoes back the same app hash the device computed.** The hash
is computed before the start request and sent with it; if the response's ``sms.appHash`` is
absent or different, the platform listener is never touched. On a resume the hash is computed
and compared but never sent, which is what lets a resumed SMS verification keep capturing.

The subscription is cancelled on any terminal state, when the API's ``interception_timeout``
budget elapses, when ``expiresAt`` passes, and on ``reset()`` and ``dispose()`` — whichever
comes first.

.. warning::

   Play App Signing re-signs your upload artifact, so a hash computed from a locally signed
   build never matches in production, and the only symptom is that capture silently never
   fires. Display ``getAppHash()`` in your app during development and register the value you
   see there.

Re-entering the screen: resume first, start second
==================================================

``start()`` bills the account and supersedes whatever the destination already had. The
session's guards are **per instance**, so a route remount — ``Navigator.pushReplacement``, a
tab switch that disposes the route, a deep link back into the same page — builds a *new*
session whose guards cannot see the old one, and a second ``start()`` bills again.

``resumeByNumber`` bills nothing, so the recipe costs nothing:

.. code-block:: dart

   await session.resumeByNumber(destination);
   if (session.state is! VerificationAwaitingInput) {
     await session.start(destination: destination, deliveryMethod: DeliveryMethod.sms);
   }

The check is ``is! VerificationAwaitingInput`` rather than "did it 404", because the by-number
read answers with the **newest** verification for the number whatever its status.

``resumeById`` does the same for a verification you persisted across an app restart — and
answers ``404`` once a finished verification passes the
:ref:`retention period <otp_verification_retention>`, so persist the outcome rather than the
id if you need it later. Neither resume takes ``SmsOptions`` or ``CalloutOptions``: every
option there is a create-time choice.

Which rejections keep the verification alive
============================================

Five codes send the session back to ``VerificationAwaitingInput`` with ``lastError`` set, so
the user can try again: ``code_invalid``, ``code_blank``, ``delivery_method_invalid``,
``validation_failed``, ``not_ready_to_report``. Everything else is terminal.

Three of those boundaries look wrong and are not:

- **``not_ready_to_report`` arrives while the status reads ``pending``.** ``pending`` is public
  before the message has finished dispatching, so the report is refused for a moment on a
  verification that looks ready. Retry it; it is not terminal.
- **``too_many_attempts`` is terminal, and there is no local attempt counter anywhere.**
  Whether another attempt is allowed is the API's decision, and that code is how it says no.
- **``already_verified`` is a failure, never ``VerificationVerified``.** The verification
  succeeded earlier, but *this* submission was wrong. Reporting success would admit someone who
  typed the wrong code.

A rejection during ``VerificationStarting`` is always terminal, whatever the code: nothing is
retryable before a verification exists.

Error handling
==============

Verification outcomes and thrown exceptions are different. A request can succeed and return a
``Verification`` whose status is ``failed``, ``expired`` or ``denied``. Handle those through
``knownStatus`` and ``knownErrorCode``.

Thrown exceptions describe a transport, decoding, HTTP or client-side validation failure.
``VerificationException`` is sealed, so a ``switch`` over it needs no ``default`` arm:

.. list-table::
   :header-rows: 1
   :widths: 36 14 50

   * - Exception
     - HTTP status
     - Meaning
   * - ``ConfigurationException``
     - —
     - The client or a value it was given is unusable. Thrown before any request.
   * - ``ChannelMismatchException``
     - —
     - The reported value does not suit the delivery method. Thrown before any request.
   * - ``TransportException``
     - —
     - No response: a network failure, a timeout, or a socket error.
   * - ``DecodingException``
     - —
     - A response arrived and was not the shape this release expects.
   * - ``UnauthorizedException``
     - ``401``
     - Authentication failed, or the mode is below the application's minimum.
   * - ``BalanceInsufficientException``
     - ``402``
     - The account balance is insufficient.
   * - ``NotFoundException``
     - ``404``
     - No verification matches the identifier or number.
   * - ``ValidationException``
     - ``400``, ``422``
     - Request validation failed.
   * - ``ServerException``
     - ``5xx``
     - The API failed to process the request.

An unmodelled error code resolves to a ``null`` ``ApiErrorItem.known`` and an element that is
not an object is skipped, so neither poisons the rest of the envelope.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the full list of
machine-readable error codes.

Testing
=======

``package:didww_verification/testing.dart`` exports ``FakeTransport``, so a test can script
responses and inspect the exact bytes sent without a network.

Next steps
==========

- :ref:`Start a verification <otp_verification_api_start>`: Review all start-request and
  response fields.
- :ref:`Callbacks <otp_verification_callbacks>`: Review the request callback that authorizes
  each ``public`` start.
- :ref:`Errors and status codes <otp_verification_api_errors>`: Look up machine-readable error
  codes.


.. _otp_verification_sdks:

====
SDKs
====

The DIDWW OTP Verification SDKs let you call the :ref:`Verification API
<otp_verification_api_reference>` from your language of choice without hand-rolling HTTP
requests. Each SDK wraps the verification endpoints and handles :ref:`authentication
<otp_verification_authentication>`, so you can work with native objects and methods instead
of raw JSON and headers.

.. note::

   - **Server-side** SDKs support every authentication mode, including HMAC request signing, and
     can verify inbound :ref:`callback <otp_verification_callbacks>` signatures.

   - **On-device** SDKs omit the signed ``application`` mode because a signing secret must never be
     included in an app. They use the ``public`` mode, where your backend authorizes each start
     request through a callback.

----

Available SDKs
==============

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - SDK
     - Status
     - Notes
   * - :ref:`Ruby <otp_verification_sdk_ruby>`
     - Available
     - Server-side. Supports start, report, status, all auth modes, and callback verification.
   * - :ref:`Python <otp_verification_sdk_python>`
     - Coming soon
     - Planned server-side SDK.
   * - :ref:`Node.js <otp_verification_sdk_node>`
     - Available
     - Server-side. Supports start, report, status, all auth modes, and callback verification.
       No third-party dependencies.
   * - :ref:`Android <otp_verification_sdk_android>`
     - Available
     - On-device Kotlin SDK. Supports start and submit for SMS and phone call, with a ``Flow``
       state machine, typed errors, and automatic SMS code capture.
   * - :ref:`iOS <otp_verification_sdk_ios>`
     - Available
     - On-device SDK. Supports start, submit, and status by verification ID or by number, with
       ``async``/``await`` and typed errors.
   * - :ref:`React Native <otp_verification_sdk_react_native>`
     - Available
     - On-device SDK. One ``useVerification()`` hook drives the whole flow, with a state
       machine, typed errors, and automatic SMS code capture on Android.
   * - :ref:`Dart and Flutter <otp_verification_sdk_dart>`
     - Available
     - Pure Dart client plus a ``Stream`` state machine, and an optional Flutter plugin for
       automatic SMS code capture on Android. No dependencies.

.. note::

   You can integrate directly with the :ref:`REST API <otp_verification_api_reference>` when
   you need a custom setup or a platform-specific SDK is not available. The
   :ref:`Authentication <otp_verification_authentication>` guide includes a reference signing
   example that you can adapt for your own integration.


.. _otp_verification_sdk_ios:

=======
iOS SDK
=======

The iOS SDK (``DIDWWVerification``) is an on-device Swift client for the
:ref:`Verification API <otp_verification_api_reference>`. It supports SMS and phone call
verification through ``async``/``await`` methods, Swift data types, and structured errors that
your app can catch and handle.

- **Source:** https://github.com/didww/didww-verification-ios-sdk
- **Runtime requirement:** iOS ``13.0+``
- **Swift Package Manager requirement:** Swift ``6.1`` / Xcode ``16.3+``
- **Dependencies:** none; the SDK uses ``URLSession`` and ``Codable``

.. note::

   A mobile app cannot keep a credential secret private. For this reason, use ``public``
   authentication for production iOS apps. The HMAC-signed server-to-server mode is not
   available in the SDK because it requires a signing secret. See
   :ref:`Authentication <otp_verification_authentication>`.

----

Before you begin
================

- Create an OTP application and obtain its credentials in the environment where the SDK will
  send verification requests. See
  :ref:`Getting Started <otp_verification_getting_started>`.
- Set the OTP application's **Callback URL** to an endpoint on your backend. Configure that
  endpoint to verify callback signatures using the application secret and return ``allow`` or
  ``deny``. See :ref:`Callbacks <otp_verification_callbacks>`.
- Keep the OTP application's minimum authentication mode set to ``public`` so requests made
  with ``.public(appKey:)`` are accepted.
- Copy the application key into the iOS app and use it with ``.public(appKey:)``. Keep the
  application secret on your backend; do not include it in the app binary.
- Choose the :ref:`verification methods <otp_verification_methods>` your app will support and
  provide an input screen for the code required by each method.

How a verification flows
========================

Your app starts a verification, checks the initial status, collects the code from the user,
and submits it through the SDK. You can request the current status while the verification is
pending.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",

       "signalColor": "#1f2d3d",
       "signalTextColor": "#1f2d3d",

       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#facc15",
       "noteTextColor": "#1f2d3d",

       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d",
       "loopTextColor": "#1f2d3d"
     }
   }}%%

   sequenceDiagram
       actor User as End user
       participant App as Your iOS app
       participant SDK as Verification SDK
       participant API as Verification API

       User->>App: Enters phone number
       App->>SDK: client.start(destination:method:sms:)
       SDK->>API: POST /api/v1/verifications<br/>Authorization: Application {appKey}
       Note over SDK,API: With .public authentication,<br/>your backend approves the request<br/>before delivery.
       API-->>SDK: 201 Created - initial status
       SDK-->>App: Verification
       API->>User: SMS / phone call
       Note over API,User: Delivery is asynchronous.<br/>201 means accepted, not delivered.<br/>Delivery can still fail later.

       opt Check status while waiting
           App->>SDK: client.status(verification)
           SDK->>API: GET /api/v1/verifications/{id}
           API-->>SDK: 200 OK - current status
       end

       User->>App: Enters the code
       App->>SDK: client.verify(verification, code:)
       SDK->>API: PUT /api/v1/verifications/{id}
       API-->>SDK: 200 OK - status "verified"
       SDK-->>App: VerificationResult
       App-->>User: Verification completed

Your app does not verify the code itself. It collects the code from the user and passes it to
the SDK. The SDK handles the network requests, while your app controls the user interface and
the action taken after verification.

Installation
============

Swift Package Manager
---------------------

In Xcode, choose **File > Add Package Dependencies** and enter the repository URL, or declare
the package in ``Package.swift``:

.. code-block:: swift

   dependencies: [
       .package(url: "https://github.com/didww/didww-verification-ios-sdk.git", from: "1.0.0")
   ],
   targets: [
       .target(name: "YourApp", dependencies: [
           .product(name: "DIDWWVerification", package: "didww-verification-ios-sdk")
       ])
   ]

Swift Package Manager requires Swift ``6.1`` or Xcode ``16.3+`` to build the package.

CocoaPods
---------

Add the SDK directly from its Git repository and pin it to a release tag:

.. code-block:: ruby

   pod 'DIDWWVerification', :git => 'https://github.com/didww/didww-verification-ios-sdk.git', :tag => '1.0.0'

The CocoaPods specification supports Swift ``5.9`` and iOS ``13.0+``.

Quick start
===========

The following example creates a sandbox client with ``public`` authentication, starts an SMS
verification, checks the initial status, and submits the code entered by the user:

.. code-block:: swift

   import DIDWWVerification

   let client = VerificationClient(
       environment: .sandbox,
       auth: .public(appKey: "your-app-key"),
       configuration: .init(timeout: 30)
   )

   let verification = try await client.start(
       destination: "+4915112345678",
       method: .sms,
       sms: .init(languages: ["en-US"])
   )

   if verification.status == .pending {
       let result = try await client.verify(verification, code: "123456")

       switch result.status {
       case .verified:
           print("verified")
       case .failed, .denied:
           print(result.errorDetail ?? "not verified")
       case .expired:
           print("expired")
       case .pending:
           print("still pending")
       case .other(let raw):
           print("unrecognised status: \(raw)")
       }
   } else {
       print(verification.errorDetail ?? "verification did not start")
   }

The SDK sends the start request when ``start(...)`` is called. A successful HTTP request can
still return a verification with status ``.denied``, so check ``verification.status`` before
showing the input screen.

Use ``client.status(verification)`` when you need the latest state. The SDK does not poll
automatically.

Delivery-method options
-----------------------

Pass method-specific options through the parameter named after the delivery method:
``sms:`` takes an ``SMSOptions``, ``callout:`` takes a ``CalloutOptions``. The SDK sends them
in the matching object of the API request.

The following example requests a German SMS template:

.. code-block:: swift

   try await client.start(
       destination: "+4915112345678",
       method: .sms,
       sms: .init(languages: ["de-DE"])
   )

This sends:

.. code-block:: json

   {
     "data": {
       "destination": "+4915112345678",
       "delivery_method": "sms",
       "sms": {
         "languages": ["de-DE"]
       }
     }
   }

A phone call verification takes the announcement language the same way:

.. code-block:: swift

   try await client.start(
       destination: "+5511987654321",
       method: .callout,
       callout: .init(languages: ["pt-BR", "pt-PT"])
   )

This sends:

.. code-block:: json

   {
     "data": {
       "destination": "+5511987654321",
       "delivery_method": "callout",
       "callout": {
         "languages": ["pt-BR", "pt-PT"]
       }
     }
   }

Language preferences use BCP 47 tags. ``SMSOptions`` and ``CalloutOptions`` accept the same
tags with the same semantics, so one language list works for both delivery methods. The
catalogues behind them differ, however: the announcement recordings are a different set from
the message templates, so a tag that is honored for SMS can still fall back for a phone call.
See :ref:`SMS languages <otp_verification_sms_languages>` and
:ref:`phone call languages <otp_verification_callout_languages>` for matching and fallback
behavior.

If ``sms:`` or ``callout:`` is passed with a different ``method:``, the SDK throws
``VerificationError.channelMismatch`` before sending a network request. This prevents the API
from starting a verification with unintended default options.

A start can come back denied
----------------------------

With ``.public`` authentication, the Verification API sends a synchronous
:ref:`request callback <otp_verification_callbacks>` to your backend before delivering the
challenge. If your backend denies the request or the callback response cannot be used,
``start()`` still returns normally with HTTP ``201 Created``. The returned ``Verification`` has
status ``.denied``, and ``errorCode`` explains why no challenge was sent.

.. mermaid::

   %%{init: {
     "theme": "base",
     "themeVariables": {
       "actorBkg": "#e0f2fe",
       "actorBorder": "#38bdf8",
       "actorTextColor": "#1f2d3d",
       "actorLineColor": "#38bdf8",

       "signalColor": "#1f2d3d",
       "signalTextColor": "#1f2d3d",

       "noteBkgColor": "#fef3c7",
       "noteBorderColor": "#facc15",
       "noteTextColor": "#1f2d3d",

       "labelBoxBkgColor": "#ccfbf1",
       "labelBoxBorderColor": "#2dd4bf",
       "labelTextColor": "#1f2d3d",
       "loopTextColor": "#1f2d3d"
     }
   }}%%

   sequenceDiagram
       participant SDK as Verification SDK
       participant API as Verification API
       participant CB as Your backend

       SDK->>API: POST /api/v1/verifications
       API->>CB: POST {callback_url}<br/>Authorization: Application {appKey}:{signature}<br/>x-timestamp: {unix seconds}
       Note over CB: Verify the signature,<br/>then decide

       alt Your backend allows
           CB-->>API: 200 {"action":"allow"}
           API-->>SDK: 201 Created - status "pending"
       else Your backend denies
           CB-->>API: 200 {"action":"deny"}
           API-->>SDK: 201 Created - status "denied"<br/>errorCode "denied_by_callback"
       else No usable answer
           CB--xAPI: Non-2xx, timeout, invalid JSON,<br/>unknown action, or a body over 8 KB
           API-->>SDK: 201 Created - status "denied"<br/>errorCode "denied_invalid_callback_response"
       end

       Note over SDK,CB: No challenge is delivered in either denied branch.

A denied start can also happen when no callback URL is configured. If ``.public``
authentication is used without a callback URL on the application, ``start()`` returns a
``Verification`` with status ``.denied`` and ``errorCode``
``denied_missing_callback_url``. See :ref:`Callbacks <otp_verification_callbacks>`.

Handle ``.denied`` as part of the normal result from ``start()``:

.. code-block:: swift

   let verification = try await client.start(destination: number, method: .sms)

   switch verification.status {
   case .pending:
       presentCodeEntry(for: verification)
   case .denied:
       show(verification.errorDetail ?? "verification denied")
   default:
       show("unexpected start status: \(verification.status)")
   }

Returned values
===============

The SDK uses two related types for verification data:

.. list-table::
   :header-rows: 1
   :widths: 25 30 45

   * - Type
     - Returned by
     - Purpose
   * - ``Verification``
     - ``start(...)``
     - A handle containing the verification identifier, delivery method, expiry, quoted fee,
       and creation-time status.
   * - ``VerificationResult``
     - ``verify(...)`` and ``status(...)``
     - The state returned after reporting a value or requesting the latest verification status.

The ``status`` on ``Verification`` is the state returned when the verification was created. It
is not updated automatically. Pass the handle to ``status(_:)`` to retrieve a
``VerificationResult`` with the current state:

.. code-block:: swift

   let current = try await client.status(verification)

   if current.status.isTerminal {
       stopPolling()
   }

``Verification.Status`` and ``Verification.Reason`` include an ``.other(String)`` fallback. If
the API adds a new value, the SDK preserves the raw value instead of failing to decode the
response. An unknown status is treated as non-terminal.

``verification.isExpired`` compares ``expiresAt`` with the device clock. It is a local
convenience; the Verification API remains authoritative when a value is submitted.

.. note::

   The ``fee`` value is the quoted verification fee, not an immediate charge. It is billed only
   when the verification reaches ``.verified``. SMS or call delivery costs are billed
   separately as ordinary DIDWW traffic.

Report or check status by phone number
======================================

The SDK can address a verification by destination number when your app no longer holds the
original ``Verification`` handle.

Use ``status(number:)`` to get the newest verification for a number:

.. code-block:: swift

   let current = try await client.status(number: "+4915112345678")

If an active verification exists, the status request returns it. Otherwise, it returns the
most recent finished verification. A ``404`` means that no verification history exists for the
number.

Use the by-number ``verify`` methods to report a value to the active verification:

.. code-block:: swift

   let result = try await client.verify(
       number: "+4915112345678",
       code: "123456",
       method: .sms
   )

Reporting by number requires an active verification that can receive the value. If no active
verification exists, the API returns ``404`` even when a finished verification exists for the
same number.

Common phone-number formatting is accepted. Before building the request path, the SDK removes
all non-digit characters. For example, ``"+49 151 1234 5678"`` and
``"4915112345678"`` reach the same endpoint. If the value contains no digits, the SDK throws
``VerificationError.invalidNumber`` before sending a network request.

One active verification per number
----------------------------------

Only one unfinished verification can exist for the same OTP application and phone number. If
your app calls ``start()`` again for a number with an unfinished verification, the new
verification supersedes the previous one. The previous verification changes to ``.failed``
with reason ``.superseded``.

By-number operations resolve to the new verification. To observe ``.superseded``, request the
status of the previous verification through its original handle with ``status(_:)``.

.. warning::

   When reporting a code by number, ``method:`` must match the delivery method used to start the
   active verification. An incorrect method and an incorrect code use the same
   ``APIError.validationFailed`` case, but the contained ``APIErrorItem`` identifies the cause.
   Check ``item.known`` or ``item.code`` for ``delivery_method_invalid`` or ``code_invalid``.

Environments
============

Choose the environment when creating the client. The SDK uses ``.production`` by default and
adds ``/api/v1`` to the selected URL.

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - Environment
     - Host
   * - ``.production`` (default)
     - ``https://verification.didww.com``
   * - ``.sandbox``
     - ``https://verification-sandbox.didww.com``
   * - ``.custom(URL)``
     - A custom scheme and host with an optional base path, such as a local backend, proxy, or
       test server.

.. note::

   Use ``.sandbox`` while building and testing your integration. Use credentials from an OTP
   application created in the same environment as the client. See
   :ref:`Choose an environment <otp_verification_environments>`.

   .. code-block:: swift

      let client = VerificationClient(
          environment: .sandbox,
          auth: .public(appKey: "your-sandbox-app-key")
      )

For ``.custom(URL)``, provide the URL before ``/api/v1``. For example, a custom URL ending in
``/verification`` produces endpoint paths under ``/verification/api/v1``.

Authentication
==============

.. list-table::
   :header-rows: 1
   :widths: 34 38 28

   * - Mode
     - Header
     - Use
   * - ``.public(appKey:)``
     - ``Application <appKey>``
     - Production, on-device.
   * - ``.basic(appKey:secret:)``
     - ``Basic base64(appKey:secret)``
     - Local development in a trusted environment.

Use ``.public`` for production mobile apps. It sends only the application key, and the
application's callback URL authorizes each start request. Without a callback URL,
``start()`` returns HTTP ``201`` with status ``.denied`` and ``errorCode``
``denied_missing_callback_url``.

The SDK case names match the API's :ref:`authentication modes
<otp_verification_authentication>`. Both public and signed application authentication use the
``Application`` header scheme. The signed mode is not implemented in the iOS SDK because it
requires the secret on the device.

.. warning::

   ``.basic`` embeds the application secret in your app, where it can be extracted from the
   binary. Use it only for local development in a trusted environment. If the secret has been
   distributed in an app, treat it as disclosed and rotate it.

Leave the OTP application's minimum authentication mode at ``public`` for an on-device iOS
integration. Raising it to ``basic`` or ``application`` rejects requests made with
``.public``. Use a higher minimum only for an application called exclusively from your own
server.

Reading delivery-method details
===============================

``VerificationResult.details`` contains delivery-method-specific data returned by the API,
keyed by the delivery method. SMS responses carry the message template and the template
language; phone call responses carry the announcement language.

.. code-block:: swift

   if case .sms(let sms) = result.details {
       print(sms.template ?? "no template")
       print(sms.language ?? "no language")
   }

   if case .callout(let callout) = result.details {
       print(callout.language ?? "no language")
   }

Both ``language`` values report the language the API **selected**, which is not necessarily
the first one requested. Compare with the list you sent to detect a fallback to ``en-US``.

Error handling
==============

Verification outcomes and thrown errors are different. A request can succeed and return a
``Verification`` or ``VerificationResult`` with status ``.failed``, ``.expired``, or
``.denied``. Handle those values through ``status`` and ``reason``.

Thrown errors describe an HTTP, transport, decoding, or client-side validation failure. The
SDK uses ``APIError`` for failures returned by the API or transport layer and
``VerificationError`` for validation performed before a request is sent.

.. list-table::
   :header-rows: 1
   :widths: 44 12 44

   * - Case
     - HTTP status
     - Meaning
   * - ``APIError.invalidParameters([APIErrorItem])``
     - ``400``
     - The request body or required parameters are malformed.
   * - ``APIError.unauthorized``
     - ``401``
     - Authentication failed or the request uses a mode below the OTP application's minimum.
       This case does not expose structured error items.
   * - ``APIError.insufficientBalance``
     - ``402``
     - The account balance is insufficient to start a verification.
   * - ``APIError.notFound``
     - ``404``
     - The requested verification could not be resolved.
   * - ``APIError.validationFailed([APIErrorItem])``
     - ``422``
     - Validation or reporting failed, for example because of an incorrect code or delivery
       method.
   * - ``APIError.unexpectedStatus(code:items:)``
     - Other
     - The API returned another unsuccessful HTTP status. The case preserves its code and any
       error items.
   * - ``APIError.unexpectedResponse(String)``
     -
     - The response body could not be decoded.
   * - ``APIError.transport(URLError)``
     -
     - The request failed because of connectivity, DNS, TLS, or a timeout.
   * - ``VerificationError.channelMismatch(expected:)``
     -
     - The supplied options do not match the selected delivery method. The error is thrown before
       a network request is sent.
   * - ``VerificationError.invalidNumber``
     -
     - A by-number operation received a value containing no digits. The error is thrown before a
       network request is sent.

The error cases that contain ``APIErrorItem`` values mirror the API's
:ref:`coded error envelope <otp_verification_api_errors>`:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Property
     - Meaning
   * - ``code``
     - The raw error code, always present, for example ``destination_blank``.
   * - ``detail``
     - Fixed human-readable text. Display it when needed, but do not use it for application
       logic.
   * - ``known``
     - The typed ``APIErrorCode`` when this SDK version recognizes the code; otherwise ``nil``.

``APIErrorCode`` has no ``.other`` case. An unrecognized API error leaves ``known`` as ``nil``
while ``code`` preserves the raw value, so decoding does not fail and the error code is not
lost.

.. code-block:: swift

   do {
       _ = try await client.verify(verification, code: code)
   } catch APIError.validationFailed(let items) {
       for item in items {
           switch item.known {
           case .codeInvalid:
               print("wrong code")
           case .deliveryMethodInvalid:
               print("wrong delivery method")
           case nil:
               print("unmodelled code: \(item.code) - \(item.detail)")
           default:
               print("\(item.code): \(item.detail)")
           }
       }
   } catch APIError.notFound {
       print("verification not found")
   } catch APIError.unauthorized {
       print("authentication failed")
   } catch APIError.insufficientBalance {
       print("insufficient balance")
   } catch APIError.unexpectedResponse(let message) {
       print("response could not be decoded: \(message)")
   } catch APIError.transport(let urlError) {
       print("network request failed: \(urlError)")
   } catch VerificationError.channelMismatch(let expected) {
       print("value does not match \(expected)")
   } catch VerificationError.invalidNumber {
       print("phone number contains no digits")
   } catch is CancellationError {
       print("request cancelled")
   }

Cancellation and timeout
========================

Run an SDK call in a ``Task`` when your app needs to cancel it. Cancelling the task cancels the
underlying ``URLSession`` request and throws ``CancellationError``:

.. code-block:: swift

   let task = Task {
       try await client.status(verification)
   }

   task.cancel()

``Configuration(timeout:)`` sets the timeout for each network request. The default is 30
seconds. This timeout is independent of the verification lifetime represented by
``expiresAt``.

.. warning::

   Do not automatically resubmit a code after a timeout or another ambiguous network failure.
   The API may already have processed the report, and another report can consume an additional
   attempt. Request the current status before asking the user to submit the code again. See
   :ref:`Report a verification <otp_verification_api_report>`.

Debug logging
=============

Logging is disabled by default. To enable it, provide a ``VerificationLogger`` when creating
the client. The SDK logs the request method and URL and the HTTP response status. It never logs
request or response bodies.

Before a message reaches your logger, the SDK masks standard six-digit OTP codes and digit
sequences in the usual phone-number length range. Avoid adding credentials or unredacted user
input in your own logging implementation.

.. code-block:: swift

   struct ConsoleLogger: VerificationLogger {
       func log(_ message: String) { print(message) }
   }

   let client = VerificationClient(
       environment: .sandbox,
       auth: auth,
       configuration: .init(logger: ConsoleLogger())
   )

Sample CLI
==========

The SDK repository includes a macOS command-line sample that demonstrates the complete SMS
flow. It reads the environment, credentials, and destination from environment variables:

.. code-block:: shell

   ENVIRONMENT=sandbox \
   APP_KEY=your-app-key \
   SECRET=your-app-secret \
   DESTINATION=+4915112345678 \
   swift run SampleCLI

.. important::

   The sample uses ``basic`` authentication because it runs as a trusted command-line process.
   Do not copy its secret-based authentication configuration into an iOS app. For an on-device
   integration, use ``.public(appKey:)`` with a request callback.


.. _otp_verification_sdk_node:

===========
Node.js SDK
===========

The Node.js SDK is a server-side client for the :ref:`Verification API
<otp_verification_api_reference>`. It wraps the verification endpoints, supports every
:ref:`authentication mode <otp_verification_authentication>` including signed ``application``
requests, and verifies the signature on inbound :ref:`callbacks <otp_verification_callbacks>`.

It ships as two packages:

.. list-table::
   :header-rows: 1
   :widths: 34 66

   * - Package
     - Contents
   * - ``@didww/verification-core``
     - The client, the wire types, and the error tree. Runtime-agnostic: it needs only
       ``fetch``. Supports the ``public`` and ``basic`` authentication modes.
   * - ``@didww/verification-node``
     - Signed ``application`` authentication and the inbound callback endpoint. Installs
       ``@didww/verification-core`` with it.

Install ``@didww/verification-node`` on a server. It brings the client with it.

----

Requirements
============

.. list-table::
   :widths: 30 70

   * - Runtime
     - Node.js 22 or later.
   * - Module format
     - ESM and CommonJS. TypeScript types are included.
   * - Dependencies
     - No third-party dependencies. ``@didww/verification-core`` declares none at all, and
       ``@didww/verification-node`` depends only on it.

Installation
============

.. code-block:: shell

   npm install @didww/verification-node

For a browser, an edge runtime, or any process that does not need signing or the callback
endpoint, install the client alone:

.. code-block:: shell

   npm install @didww/verification-core

Quick start
===========

Create a client, start an SMS verification, report the code entered by the user, and read the
outcome. This example uses the sandbox environment and HTTP Basic authentication:

.. code-block:: typescript

   import { VerificationClient, basicAuth } from '@didww/verification-core';

   const client = new VerificationClient({
     auth: basicAuth(process.env.DIDWW_OTP_KEY!, process.env.DIDWW_OTP_SECRET!),
     environment: 'sandbox',
   });

   const verification = await client.startVerification({
     destination: '+4915112345678',
     deliveryMethod: 'sms',
     sms: { languages: ['en-US'] },
   });

   verification.id;            // '0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21'
   verification.status;        // 'pending'
   verification.sms?.language; // 'en-US'

   const result = await client.reportVerification(verification.id, {
     deliveryMethod: 'sms',
     code: '123456',
   });

   if (result.status === 'verified') {
     grantAccess();
   }

Every method returns a new decoded object describing the state at that moment. Objects are
snapshots and are never updated in place.

Authentication
==============

.. list-table::
   :header-rows: 1
   :widths: 26 30 44

   * - Mode
     - Constructor
     - Use it
   * - ``public``
     - ``publicAuth(key)``
     - On a device, or wherever no secret may be stored. The start is authorized by a
       :ref:`callback <otp_verification_callbacks>` to your server.
   * - ``basic``
     - ``basicAuth(key, secret)``
     - Server-side only. The secret is sent on every request.
   * - ``application``
     - ``applicationAuth({key, secret})``
     - Server-side only, from ``@didww/verification-node``. The secret never goes on the
       wire, and a signed start is not put to the callback gate.

.. code-block:: typescript

   import { VerificationClient } from '@didww/verification-core';
   import { applicationAuth } from '@didww/verification-node';

   const client = new VerificationClient({
     auth: applicationAuth({
       key: process.env.DIDWW_APPLICATION_KEY!,
       secret: process.env.DIDWW_APPLICATION_SECRET!,
     }),
   });

Each signed request carries an ``Authorization: Application <key>:<signature>`` header and an
``x-timestamp`` header, both derived from a single reading of the clock.

The application secret is URL-safe base64, and the HMAC key is the **bytes it decodes to**,
never its characters. ``applicationAuth`` validates the secret at construction and throws
``ConfigurationError`` for a value that is not canonical URL-safe base64, rather than failing
later with a valid-looking signature the API rejects.

All three constructors throw ``ConfigurationError`` at construction for a blank credential or
for a key containing ``":"``. The API splits on the first colon, so a key containing one
silently becomes a different credential.

Environments
============

.. code-block:: typescript

   new VerificationClient({ auth });                             // production
   new VerificationClient({ auth, environment: 'sandbox' });
   new VerificationClient({ auth, baseUrl: 'https://proxy.example.com' }); // wins over environment

``baseUrl`` is an absolute URL that overrides ``environment``; a path on it is used as a
prefix. It is validated at construction. The SDK appends the ``/api/v1`` base path itself.

Other client options: ``transport``, ``timeoutMs`` (default ``30000``), ``retry``,
``userAgent``, ``logger``, and ``keepRawPayload``.

Methods
=======

.. list-table::
   :header-rows: 1
   :widths: 44 56

   * - Method
     - Endpoint
   * - ``startVerification(options)``
     - ``POST /verifications``
   * - ``reportVerification(id, options)``
     - ``PUT /verifications/{id}``
   * - ``getVerification(id)``
     - ``GET /verifications/{id}``
   * - ``reportVerificationByNumber(number, options)``
     - ``PUT /verifications/by_number/{number}``
   * - ``getVerificationByNumber(number)``
     - ``GET /verifications/by_number/{number}``

The ``*ByNumber`` variants address the newest verification for a number, whatever its status.
The number is reduced to ASCII digits before it is placed in the path.

``getVerification`` and ``getVerificationByNumber`` reject with a ``404`` ``ApiError`` once
the verification they name passes the
:ref:`retention period <otp_verification_retention>`, so persist the outcome rather than the
id if your service needs it later.

``reportVerificationRaw(id, options)`` and ``reportVerificationRawByNumber(number, options)``
are escape hatches for a delivery method this release does not model. No client-side channel
guard runs on them.

.. note::

   **Only ``GET`` requests are retried.** The default policy is two attempts with jittered
   backoff on a transport failure or a ``5xx``. A start or a report that timed out may still
   have been carried out, so retrying one double-charges or burns an attempt. When a start
   times out, call ``getVerificationByNumber`` instead of sending it again.

Delivery-method options
=======================

Method-specific options travel in a property named after the delivery method, and the SDK
sends only the one matching ``deliveryMethod``:

.. code-block:: typescript

   await client.startVerification({
     destination: '+4915112345678',
     deliveryMethod: 'sms',
     sms: { languages: ['de-DE'] },
   });

   await client.startVerification({
     destination: '+5511987654321',
     deliveryMethod: 'callout',
     callout: { languages: ['pt-BR', 'pt-PT'] },
   });

``SmsOptions.languages`` and ``CalloutOptions.languages`` accept the same tags with the same
semantics, so one language list works for both delivery methods. The catalogues behind them
differ, however: the announcement recordings are a different set from the message templates,
so a tag that is honored for SMS can still fall back for a phone call. See
:ref:`SMS languages <otp_verification_sms_languages>` and
:ref:`phone call languages <otp_verification_callout_languages>`.

.. note::

   ``app_hash`` is deliberately not part of ``SmsOptions``. It identifies the running Android
   build rather than a value a server chooses, so it is supplied by
   :ref:`@didww/verification-react-native <otp_verification_sdk_react_native>` on the device.

Reporting a value
=================

Both delivery methods carry the code the user received, and the TypeScript types enforce the
pairing:

.. list-table::
   :header-rows: 1
   :widths: 26 20 54

   * - Delivery method
     - Property
     - Example
   * - ``sms``
     - ``code``
     - ``{deliveryMethod: 'sms', code: '123456'}``
   * - ``callout``
     - ``code``
     - ``{deliveryMethod: 'callout', code: '123456'}``

The wrong pairing does not compile. Supplying it from plain JavaScript throws
``ChannelMismatchError`` before any request is sent.

Verification responses
======================

Every successful request resolves to a decoded ``Verification``:

.. list-table::
   :header-rows: 1
   :widths: 28 26 46

   * - Property
     - Type
     - Description
   * - ``id``
     - ``string``
     - Verification identifier.
   * - ``destination``
     - ``string``
     - Destination number normalized without a leading ``+``.
   * - ``deliveryMethod``
     - ``string``
     - Delivery method used for the verification.
   * - ``fee``
     - ``string | null``
     - Quoted verification fee, as a decimal string. Never parse it as a number.
   * - ``status``
     - ``string``
     - Current verification status.
   * - ``errorCode``
     - ``string | null``
     - Machine-readable reason for a failed, expired, or denied verification.
   * - ``errorDetail``
     - ``string | null``
     - Human-readable text associated with ``errorCode``.
   * - ``expiresAt``
     - ``Date | null``
     - Verification expiration time.
   * - ``sms``
     - ``SmsInfo | null``
     - SMS response fields. It is ``null`` for a phone call.
   * - ``callout``
     - ``CalloutInfo | null``
     - Phone call response fields. It is ``null`` for SMS.

``isPending(verification)`` is the condition to poll on. ``isFinished(verification)`` is its
exact complement, so a status added after this release reads as finished rather than looping
forever.

Reading delivery-method details
-------------------------------

.. code-block:: typescript

   verification.sms?.template;                   // 'Your code is {{CODE}}'
   verification.sms?.language;                   // 'en-US'
   verification.sms?.interceptionTimeoutSeconds; // 120
   verification.sms?.appHash;                    // 'A1b2C3d4E5f', or null

   verification.callout?.language;               // 'de-DE'

Both ``language`` values report the language the API **selected**, which is not necessarily
the first one requested. Compare with the list you sent to detect a fallback to ``en-US``.

``interceptionTimeoutSeconds`` is how long an on-device client should keep listening for
automatic SMS capture. It is not the verification expiration time; manual code entry remains
available until ``expiresAt``.

``appHash`` is returned only when an app hash was stored for the verification.

Error handling
==============

Verification outcomes and thrown errors are different. A request can succeed and return a
verification whose ``status`` is ``failed``, ``expired``, or ``denied``. Handle those through
``status`` and ``errorCode``.

Thrown errors describe a transport, decoding, HTTP, or client-side validation failure. Every
one extends ``DidwwError``:

.. list-table::
   :header-rows: 1
   :widths: 34 14 52

   * - Class
     - HTTP status
     - Meaning
   * - ``ConfigurationError``
     - —
     - The client or a value it was given is unusable. Thrown before any request.
   * - ``ChannelMismatchError``
     - —
     - The reported value does not suit the delivery method. Thrown before any request.
   * - ``TransportError``
     - —
     - No response: a network failure, a timeout, or an abort.
   * - ``DecodingError``
     - —
     - A response arrived and was not the shape this release expects.
   * - ``UnauthorizedError``
     - ``401``
     - Authentication failed, or the mode is below the application's minimum.
   * - ``BalanceInsufficientError``
     - ``402``
     - The account balance is insufficient.
   * - ``NotFoundError``
     - ``404``
     - No verification matches the identifier or number.
   * - ``ValidationError``
     - ``400``, ``422``
     - Request validation failed.
   * - ``ServerError``
     - ``5xx``
     - The API failed to process the request.

.. code-block:: typescript

   import { isApiError, isDidwwError } from '@didww/verification-core';

   try {
     await client.reportVerification(id, { deliveryMethod: 'sms', code });
   } catch (error) {
     if (isApiError(error)) {
       console.warn(error.errors[0]?.code, error.status);
     } else if (isDidwwError(error)) {
       console.warn(error.name, error.message);
     } else {
       throw error;
     }
   }

Use ``isApiError`` and ``isDidwwError`` rather than ``instanceof``. Both hold across two
installed copies of the package, which ``instanceof`` does not.

See :ref:`Errors and status codes <otp_verification_api_errors>` for the full list of
machine-readable error codes.

Verifying inbound callbacks
===========================

When an application starts a verification with ``public`` or ``basic`` authentication, the API
asks your server whether to allow it and waits for the answer before creating the
verification. Until this endpoint answers correctly, every such verification is denied.

``@didww/verification-node`` ships an Express handler:

.. code-block:: typescript

   import express from 'express';
   import { expressCallbackHandler } from '@didww/verification-node';

   const secrets = new Map([['your-app-key', process.env.DIDWW_APPLICATION_SECRET!]]);

   const app = express();

   app.post(
     '/callbacks/didww',
     express.raw({ type: '*/*' }),
     expressCallbackHandler({
       path: '/callbacks/didww',
       secret: (key) => secrets.get(key) ?? null,
       decide: (payload) => ({
         action: payload.data.destination.startsWith('1900') ? 'deny' : 'allow',
       }),
       onRejected: (reason) => console.warn(`callback rejected: ${reason}`),
     }),
   );

   app.listen(3000);

.. important::

   ``express.raw({type: '*/*'})`` is required, and must be mounted on this route only. The
   signature covers the bytes as received. A body parsed by ``express.json()`` and
   re-serialized differs in whitespace and key order and will not verify.

``path`` is the path of the **registered** callback URL, not the path the request arrived on.
The two differ whenever a proxy rewrites the path:

.. list-table::
   :header-rows: 1
   :widths: 50 50

   * - Registered callback URL
     - ``path``
   * - ``https://example.com/cb/didww``
     - ``'/cb/didww'``
   * - ``https://example.com``
     - ``''`` — not ``'/'``
   * - ``https://example.com?x=1``
     - ``''`` — the query is excluded

A registered URL with no path signs the **empty string**. A handler that assumes ``'/'`` there
computes a valid signature over the wrong string and denies every verification for that
application. Pass the literal ``'incoming'`` to use the received pathname instead; in that
mode both ``'/'`` and ``''`` are tried.

``secret`` is a resolver, because one endpoint may serve several applications. Return ``null``
for a key you do not know. A fixed string is accepted too, and is decoded at wiring time so a
malformed one fails at startup.

``decide`` runs only after the signature verifies and must return ``{action: 'allow'}`` or
``{action: 'deny'}``.

.. warning::

   The handler answers with a bare status and no body on purpose: a rejected callback never
   reveals why it was rejected. Use ``onRejected`` to send the reason to your logs instead.

Without Express
---------------

``CallbackVerifier`` is the same logic with no framework attached. Supply the wire values and
write the response yourself:

.. code-block:: typescript

   import { CallbackVerifier } from '@didww/verification-node';

   const verifier = new CallbackVerifier({
     secret: (key) => lookupSecret(key),
     tolerance: 300, // seconds either side of now; this is the default
   });

   const result = await verifier.verify({
     method: 'POST',
     path: '/callbacks/didww', // the registered URL's path
     contentType: headers['content-type'] ?? '',
     body: rawBody,            // the exact received bytes
     timestamp: headers['x-timestamp'],
     authorization: headers['authorization'],
   });

   if (result.ok) {
     console.log(result.payload.key, result.payload.data.id);
   } else {
     console.warn(result.reason, result.key); // log it; do not answer with it
   }

Bodies over 8 KiB are rejected before anything is hashed.

Testing
=======

``@didww/verification-core/testing`` exports ``fakeTransport``, a scripted transport double
that records every request:

.. code-block:: typescript

   import { VerificationClient, publicAuth } from '@didww/verification-core';
   import { fakeTransport } from '@didww/verification-core/testing';

   const body = JSON.stringify({
     data: {
       id: 'ver-1',
       destination: '4915112345678',
       delivery_method: 'sms',
       fee: '0.06',
       status: 'pending',
       error_code: null,
       error_detail: null,
       expires_at: '2026-07-15T10:02:00.000Z',
       sms: { template: 'Your code is {{CODE}}', language: 'en-US', interception_timeout: 120 },
     },
   });

   const { transport, requests } = fakeTransport([{ status: 201, headers: {}, body }]);
   const client = new VerificationClient({ auth: publicAuth('your-app-key'), transport });

   await client.startVerification({ destination: '+4915112345678', deliveryMethod: 'sms' });

   requests[0]?.body; // the exact bytes sent

Next steps
==========

- :ref:`Start a verification <otp_verification_api_start>`: Review all start-request and
  response fields.
- :ref:`Callbacks <otp_verification_callbacks>`: Review the request callback contract the
  handler above implements.
- :ref:`Errors and status codes <otp_verification_api_errors>`: Look up machine-readable error
  codes.


.. _otp_verification_sdk_python:

==========
Python SDK
==========

.. admonition:: Coming soon
   :class: note

   A server-side Python SDK for the DIDWW OTP Verification API is in development.

In the meantime, you can integrate from Python by calling the :ref:`REST API
<otp_verification_api_reference>` directly — it is a small JSON-over-HTTPS surface.
:ref:`Authentication <otp_verification_authentication>` includes a reference signing
implementation you can port if you need the ``application`` auth mode.

Prefer a ready-made client today? The :ref:`Ruby SDK <otp_verification_sdk_ruby>` is
available now.


.. _otp_verification_sdk_react_native:

================
React Native SDK
================

The React Native SDK is an on-device client for the :ref:`Verification API
<otp_verification_api_reference>`. A single hook, ``useVerification()``, drives a whole
verification: it starts the verification, holds the state your screen renders from, submits
what the user typed, and on Android reads the code out of the incoming SMS without requesting
an SMS permission.

It ships as two packages:

.. list-table::
   :header-rows: 1
   :widths: 38 62

   * - Package
     - Contents
   * - ``@didww/verification-react-native``
     - The ``useVerification()`` hook, the state machine, the code-input props, and the
       Android SMS auto-capture native module.
   * - ``@didww/verification-core``
     - The client, the wire types, and the error tree. Installed with it.

.. note::

   On-device SDKs omit the signed ``application`` authentication mode because a signing secret
   must never be included in an app. Use the ``public`` mode, where your backend authorizes
   each start request through a :ref:`callback <otp_verification_callbacks>`.

----

Requirements
============

.. list-table::
   :widths: 30 70

   * - React Native
     - A **development build**. The package ships an Android native module, so Expo Go cannot
       link it. Use ``expo run:android`` or an EAS build.
   * - Android
     - Auto-capture uses the platform SMS Retriever API. The package autolinks on install.
   * - iOS
     - No native module runs. Auto-fill is handled by the system keyboard through
       ``otpInputProps``.
   * - Dependencies
     - No third-party dependencies. ``@didww/verification-react-native`` depends only on
       ``@didww/verification-core``, which declares none at all. ``react`` and
       ``react-native`` are peer dependencies; ``expo-modules-core`` is an optional one.

Installation
============

.. code-block:: shell

   npm install @didww/verification-react-native

There is no config plugin and nothing to add to ``app.json``. The package's own Android
manifest contributes no SMS or call-log permission — not ``RECEIVE_SMS``, not ``READ_SMS``,
not ``READ_CALL_LOG``.

Quick start
===========

Build the client once, at module scope. A client rebuilt on every render rebuilds its
transport too:

.. code-block:: tsx

   import { useEffect, useState } from 'react';
   import { Button, Text, TextInput, View } from 'react-native';
   import { VerificationClient, publicAuth } from '@didww/verification-core';
   import { otpInputProps, useVerification } from '@didww/verification-react-native';

   const client = new VerificationClient({
     auth: publicAuth('your-app-key'),
     environment: 'sandbox',
   });

   export function VerifyScreen({ destination }: { destination: string }) {
     const controller = useVerification({ client });
     const { state } = controller;
     const [typed, setTyped] = useState('');

     // A captured code is handed to you, not submitted for you.
     useEffect(() => {
       if (state.kind === 'captured') controller.submit(state.value);
     }, [state, controller]);

     switch (state.kind) {
       case 'idle':
         return (
           <Button
             title="Send code"
             onPress={() => {
               controller.start({
                 destination,
                 deliveryMethod: 'sms',
                 sms: { languages: ['en-US'] },
               });
             }}
           />
         );

       case 'starting':
       case 'submitting':
         return <Text>Please wait...</Text>;

       case 'awaitingInput':
         return (
           <View>
             {state.lastError === null ? null : (
               <Text>{state.lastError.detail ?? state.lastError.code}</Text>
             )}
             <TextInput {...otpInputProps} value={typed} onChangeText={setTyped} />
             <Button title="Verify" onPress={() => controller.submit(typed)} />
           </View>
         );

       case 'captured':
         return <Text>Code received automatically...</Text>;

       case 'verified':
         return <Text>Verified.</Text>;

       case 'denied':
         return <Text>{state.error?.detail ?? 'This number was not allowed.'}</Text>;

       case 'expired':
         return <Button title="Start again" onPress={() => controller.reset()} />;

       case 'setupError':
         return <Text>{`This app is misconfigured: ${state.code}`}</Text>;

       case 'failed':
         return <Text>Verification failed.</Text>;
     }
   }

The controller's methods — ``start``, ``resume``, ``resumeById``, ``submit`` and ``reset`` —
never throw and never return a promise. Every outcome arrives through ``state``.

Authentication
==============

.. list-table::
   :header-rows: 1
   :widths: 26 30 44

   * - Mode
     - Constructor
     - Use it
   * - ``public``
     - ``publicAuth(key)``
     - The mode to use in an app. The key is an identifier, not a secret.
   * - ``basic``
     - ``basicAuth(key, secret)``
     - Server-side only.

.. warning::

   ``basicAuth`` puts a recoverable secret in your app. The secret is sent verbatim on every
   request, and anything in a shipped bundle can be read out of it — ``__DEV__`` is not a
   protection and neither is minification. The SDK logs a console warning when it detects a
   release build, but the warning is a reminder, not a control.

A ``public`` start is authorized by a callback to **your** server before the verification is
created. If your application has no callback URL registered, every ``public`` start comes back
already denied with ``denied_missing_callback_url``. See
:ref:`Callbacks <otp_verification_callbacks>`, and the
:ref:`Node.js SDK <otp_verification_sdk_node>` for a ready-made handler.

Signed ``application`` authentication is not reachable from React Native at all: it needs
``node:crypto``, which Metro cannot resolve. The alternative is to give the app no credentials
and proxy every call through your own backend.

Every state
===========

.. list-table::
   :header-rows: 1
   :widths: 18 12 70

   * - ``state.kind``
     - Terminal
     - What to render
   * - ``idle``
     - no
     - The "send me a code" affordance. Nothing has been started.
   * - ``starting``
     - no
     - A spinner. No verification exists yet.
   * - ``awaitingInput``
     - no
     - The code field. Carries ``destination``, ``fee``, ``sms``, ``callout``, ``expiresAt``
       and ``lastError``.
   * - ``captured``
     - no
     - A code arrived from SMS auto-capture and has **not** been submitted.
   * - ``submitting``
     - no
     - A spinner over the code field. The verification is still alive.
   * - ``verified``
     - **yes**
     - Success. Carries ``verificationId``.
   * - ``failed``
     - **yes**
     - The failure. Carries ``reason``, which says whether the API or the SDK decided it.
   * - ``denied``
     - **yes**
     - Your callback, or an answer the API could not read, refused this verification.
   * - ``expired``
     - **yes**
     - The verification ran out of time. Offer ``reset()`` and a fresh start.
   * - ``setupError``
     - **yes**
     - **Your app is misconfigured** and the user can do nothing. Do not show a retry button.

Terminal means only ``reset()`` or a fresh ``start()`` leaves it. Reaching a terminal state
also disarms the SMS listener.

``captured`` is deliberately not submitted for you. You may want to show the code you filled
in, or run a check of your own, before it is spent: a report is not idempotent and only three
attempts exist.

Single-flighting
----------------

``start()`` called while one is in flight yields ``already_running`` rather than a second,
billable verification. ``submit()`` is single-flighted too, so a double tap sends one report;
calling it before the verification is live buffers the value and sends it once the start
lands.

Delivery methods
================

The value the user submits depends on the delivery method. ``submit()`` routes it to the right
field for you:

.. list-table::
   :header-rows: 1
   :widths: 26 74

   * - Delivery method
     - What the user submits
   * - ``sms``
     - The code from the text message. Auto-capture can fill it in on Android.
   * - ``callout``
     - The code read aloud during the call.

Delivery-method options
=======================

Method-specific options travel in a property named after the delivery method:

.. code-block:: tsx

   controller.start({
     destination,
     deliveryMethod: 'sms',
     sms: { languages: ['de-DE'] },
   });

   controller.start({
     destination,
     deliveryMethod: 'callout',
     callout: { languages: ['pt-BR', 'pt-PT'] },
   });

Both option types accept the same language tags with the same semantics, so one language list
works for both delivery methods. The catalogues behind them differ, however: the announcement
recordings are a different set from the message templates, so a tag that is honored for SMS
can still fall back for a phone call. See
:ref:`SMS languages <otp_verification_sms_languages>` and
:ref:`phone call languages <otp_verification_callout_languages>`.

Read the language back from ``state.sms.language`` or ``state.callout.language`` to see which
language the API **selected**, which is not necessarily the first one requested.

.. note::

   ``app_hash`` is not part of ``SmsOptions``. It identifies the running build rather than a
   value your code chooses, so the hook computes it on the device and sends it with the start.

Which errors are recoverable
============================

A submit that fails with one of these returns to ``awaitingInput`` with the error in
``lastError``, and the verification stays alive for another attempt: ``code_invalid``,
``code_blank``, ``delivery_method_invalid``, ``validation_failed``, ``not_ready_to_report``.

Everything else is terminal. Two absences are deliberate:

- **``too_many_attempts`` is not recoverable**, and there is no local attempt counter. Whether
  another attempt is allowed is the API's decision, and it answers ``200`` with ``status``
  ``failed`` once the limit is passed rather than a ``4xx``.
- **``already_verified`` is a failure, not a success.** The API returns it when the
  verification was verified earlier *and this submission was wrong*. Treating it as success
  would admit whoever just typed the wrong code.

**Every failure during the start phase is terminal**, including ones that would be recoverable
during submit. The recoverable set presupposes a verification to return to, and while
``starting`` there is none.

``failed`` carries a ``reason`` that is either ``{source: 'api', error}`` — an error the API
produced, with ``code`` and ``detail`` — or ``{source: 'sdk', error}``, which the SDK decided
itself: ``already_running``, ``transport`` (no response) or ``decoding`` (a response arrived
and was not what this release expects). Match on ``source`` before reading ``code``: the API
has a ``superseded`` slug of its own, and ``source`` is what tells the two apart.

The code input
==============

.. code-block:: tsx

   <TextInput {...otpInputProps} value={typed} onChangeText={setTyped} />

``otpInputProps`` sets ``textContentType``, ``autoComplete`` and ``keyboardType`` so both
platforms' keyboards offer the incoming code. On iOS this is the whole of the auto-fill story:
the system surfaces the code above the keyboard and the user taps it.

SMS auto-capture on Android
===========================

When the delivery method is ``sms`` and the native module is present, the hook computes the
build's app hash, sends it with the start, arms the platform SMS Retriever, and moves to
``captured`` when a matching message arrives. The user taps nothing.

The listener disarms itself on a terminal state, when ``expiresAt`` passes, and when the API's
``interceptionTimeoutSeconds`` budget runs out. That last one is a **budget for the listener,
not a deadline for the user**: manual entry keeps working until ``expiresAt``.

Pass ``autoCapture: false`` to ``useVerification`` to turn it off.

The platform hands the SDK exactly one message — the one addressed to this build — and never
the user's inbox.

The app hash
------------

The Retriever delivers a message only when its last token is an 11-character hash of **your
package name plus the certificate the APK was signed with**. The API appends it to the message
body, so it must be sent with the start, which the hook does for you.

.. code-block:: tsx

   import { getAppHash, isSmsAutoCaptureAvailable } from '@didww/verification-react-native';

   const hash = await getAppHash();          // null where the native module is absent
   isSmsAutoCaptureAvailable();              // false where it is absent

``getAppHash()`` never rejects.

.. warning::

   **The signing certificate is the part that catches people.** The hash changes with the
   package name *and* with the signing certificate, so a debug build, a locally signed
   release, and the build your users install can each have a different one. Under Play App
   Signing the certificate that signs the delivered artifact is held by the store, not by the
   upload key you hold, so the hash on a user's device is not the hash of anything you can
   build locally. Read it off an installed build.

**A wrong hash is completely silent.** The SMS arrives, the Retriever does not fire, nothing
throws, nothing is logged in a release build, and the user types the code by hand as if the
feature were never there. There is one guard: the API echoes the hash it stored, and if that
echo does not equal what was sent the listener declines to arm and warns — but only in a
development build. Manual entry always works, so the worst case is a missing convenience.

Where the module is absent
--------------------------

``getAppHash()`` returns ``null``, ``isSmsAutoCaptureAvailable()`` returns ``false``, no hash
is sent, no listener is armed, and the verification runs normally with manual entry. This is
the case on iOS, in Expo Go — where a native module can never be linked — and in a bare React
Native app without Expo Modules. It is not an error and nothing needs handling.

Note that the check is module presence, not ``Platform.OS === 'android'``: on Android in Expo
Go the platform reports ``android`` while capture is impossible.

Resuming
========

``start()`` bills the account and supersedes whatever the destination already had. Reattach
instead of starting again when a screen is remounted:

.. code-block:: tsx

   controller.resume({ destination, deliveryMethod: 'sms' });
   controller.resumeById({ verificationId, deliveryMethod: 'sms' });

``resume`` reattaches to the newest verification for a number; ``resumeById`` reattaches to
one your app persisted across a restart. Both land in whatever state that verification is
actually in, including a terminal one, and neither bills anything. Both answer ``404`` once
the verification they name passes the
:ref:`retention period <otp_verification_retention>`, so persist the outcome rather than the
id if you need it later.

``resume`` answers with the **newest** verification for the number whatever its status, which
is not the same as the live one: a start that was itself denied supersedes nothing, so it is
newest while an earlier verification is still live.

Next steps
==========

- :ref:`Start a verification <otp_verification_api_start>`: Review all start-request and
  response fields.
- :ref:`Node.js SDK <otp_verification_sdk_node>`: Implement the callback endpoint that
  authorizes each ``public`` start.
- :ref:`Errors and status codes <otp_verification_api_errors>`: Look up machine-readable error
  codes.


.. _otp_verification_sdk_ruby:

========
Ruby SDK
========

The Ruby SDK (``didww-otp-verification``) is a server-side client for the
:ref:`Verification API <otp_verification_api_reference>`. It provides methods for starting,
reporting, and retrieving verifications by ID or phone number. It also supports all three
:ref:`authentication modes <otp_verification_authentication>` and verifies inbound
:ref:`callback <otp_verification_callbacks>` signatures.

- **Source:** `GitHub repository <https://github.com/didww/didww-verification-ruby-sdk>`__
- **Requires:** Ruby ``>= 3.1``

----

Before you begin
================

Complete :ref:`Getting Started <otp_verification_getting_started>` in the environment where
the Ruby client will send verification requests. Create the OTP application and copy its
credentials from that environment.

- Choose the :ref:`authentication mode <otp_verification_authentication>` for the integration.
  ``:basic`` is the SDK default and requires the application key and secret.
  ``:application`` also requires both credentials and signs each request. ``:public`` uses
  only the application key but requires a callback URL so your server can approve each start.
- Store the application secret in a server-side environment variable or secret manager. Never
  include it in browser or mobile application code.
- If the OTP application has a callback URL, expose a server endpoint that can receive the
  request and verify its signature before returning ``allow`` or ``deny``. See
  :ref:`Callbacks <otp_verification_callbacks>`.

Installation
============

Add the gem to your ``Gemfile``:

.. code-block:: ruby

   gem "didww-otp_verification"

Then install the dependency:

.. code-block:: shell

   bundle install

Quick start
===========

Create a client, start an SMS verification, submit the code entered by the user, and retrieve
the current status. This example uses the sandbox environment and HTTP Basic authentication:

.. code-block:: ruby

   require "didww/otp_verification"

   client = DIDWW::OTPVerification::Client.new(
     key:    ENV.fetch("DIDWW_OTP_KEY"),
     secret: ENV.fetch("DIDWW_OTP_SECRET"),
     env:    :sandbox
   )

   verification = client.start_verification(
     destination:     "+4915112345678",
     delivery_method: "sms",
     sms:             {languages: ["en-US"]}
   )

   verification.id           # => "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
   verification.status       # => "pending"
   verification.pending?     # => true
   verification.sms_language # => "en-US"

   result = client.report_verification(
     verification.id,
     delivery_method: "sms",
     code:            "123456"
   )

   grant_access if result.verified?

   current = client.get_verification(verification.id)
   current.status

The start, report, and status methods each return a new ``Verification`` object containing the
state returned by that request. The object is a snapshot and is not updated automatically.
Call ``get_verification(...)`` when you need the latest state.

An incorrect code does not return a ``Verification`` object. It raises
``DIDWW::OTPVerification::ValidationError``. See `Error handling`_.

Available methods
=================

.. list-table::
   :header-rows: 1
   :widths: 38 22 40

   * - SDK method
     - HTTP request
     - Purpose
   * - ``start_verification(...)``
     - ``POST /verifications``
     - Start a verification for one phone number.
   * - ``report_verification(id, ...)``
     - ``PATCH /verifications/{id}``
     - Submit a code for a specific verification.
   * - ``get_verification(id)``
     - ``GET /verifications/{id}``
     - Retrieve a specific verification.
   * - ``report_verification_by_number(number, ...)``
     - ``PATCH /verifications/by_number/{number}``
     - Submit a code without providing a verification ID.
   * - ``get_verification_by_number(number)``
     - ``GET /verifications/by_number/{number}``
     - Retrieve the latest verification associated with a phone number.

The SDK adds the ``/api/v1`` base path to these requests.

Delivery methods
================

The delivery method determines which value your application must submit when reporting a
verification:

.. list-table::
   :header-rows: 1
   :widths: 24 25 51

   * - Delivery method
     - Report parameter
     - Example
   * - ``sms``
     - ``code:``
     - ``code: "123456"``
   * - ``callout``
     - ``code:``
     - ``code: "123456"``

The ``delivery_method`` supplied when reporting must match the method used to start the
verification.

Delivery-method options
=======================

Pass method-specific options in a hash named after the delivery method: ``sms:`` when starting
an SMS verification, ``callout:`` when starting a phone call verification. The SDK sends only
the hash matching ``delivery_method``, so passing both is safe.

SMS options
-----------

.. list-table::
   :header-rows: 1
   :widths: 22 78

   * - Field
     - Description
   * - ``languages``
     - Preferred message-template languages as BCP 47 tags, ordered from most to least
       preferred. See :ref:`Supported languages <otp_verification_sms_languages>`.
   * - ``app_hash``
     - Android SMS Retriever application hash. It must contain exactly 11 characters from
       ``A-Z``, ``a-z``, ``0-9``, ``+``, and ``/``. Omit this field when automatic Android
       SMS capture is not used.

The following example starts an SMS verification with a preferred language and an app hash
provided by the Android application:

.. code-block:: ruby

   verification = client.start_verification(
     destination:     "+4915112345678",
     delivery_method: "sms",
     sms: {
       languages: ["en-US"],
       app_hash:  "A1b2C3d4E5f"
     }
   )

The app hash is derived from the Android package name and signing certificate. It is not a
secret and does not authenticate the application. A Ruby backend can pass the value supplied
by the Android application to the Verification API.

The SDK passes keys inside ``sms:`` to the API without validating their names. Check the key
names carefully because an unsupported or misspelled key may be ignored and the API defaults
may be used.

Phone call options
------------------

.. list-table::
   :header-rows: 1
   :widths: 22 78

   * - Field
     - Description
   * - ``languages``
     - Preferred announcement languages as BCP 47 tags, ordered from most to least
       preferred. See :ref:`Supported languages <otp_verification_callout_languages>`.

.. code-block:: ruby

   verification = client.start_verification(
     destination:     "+5511987654321",
     delivery_method: "callout",
     callout:         {languages: ["pt-BR", "pt-PT"]}
   )

The language shorthand
----------------------

``sms.languages`` and ``callout.languages`` accept the same tags with the same semantics, so
one language list works for both delivery methods. Pass it as ``languages:`` and the SDK puts
it in the hash for the delivery method you named:

.. code-block:: ruby

   preferred = ["pt-BR", "pt-PT"]

   client.start_verification(destination: number, delivery_method: "sms", languages: preferred)
   client.start_verification(destination: number, delivery_method: "callout", languages: preferred)

An explicit ``sms:`` or ``callout:`` hash takes precedence over ``languages:``. Use the
explicit hash when you also need ``app_hash``.

Verification responses
======================

Every successful SDK request returns a ``DIDWW::OTPVerification::Verification`` object.

.. list-table::
   :header-rows: 1
   :widths: 28 22 50

   * - Reader
     - Ruby type
     - Description
   * - ``id``
     - ``String``
     - Verification identifier.
   * - ``destination``
     - ``String``
     - Destination number normalized without a leading ``+``.
   * - ``delivery_method``
     - ``String``
     - Delivery method used for the verification.
   * - ``fee``
     - ``BigDecimal``
     - Quoted verification fee.
   * - ``status``
     - ``String``
     - Current verification status.
   * - ``error_code``
     - ``String`` or ``nil``
     - Machine-readable reason for a failed, expired, or denied verification.
   * - ``error_detail``
     - ``String`` or ``nil``
     - Human-readable text associated with ``error_code``.
   * - ``expires_at``
     - ``Time`` or ``nil``
     - Verification expiration time.
   * - ``sms``
     - ``Hash`` or ``nil``
     - SMS-specific response fields. It is ``nil`` for phone call.
   * - ``callout``
     - ``Hash`` or ``nil``
     - Phone call response fields. It is ``nil`` for SMS.
   * - ``raw``
     - ``Hash``
     - Unmodified ``data`` object returned by the API.

Use ``to_h`` to retrieve the same raw response data as ``raw``.

Reading SMS response details
----------------------------

An SMS verification can include an ``sms`` object in the response. Read its fields through
the convenience methods or from the raw hash:

.. code-block:: ruby

   verification.sms_template             # => "Your code is {{CODE}}"
   verification.sms_language             # => "en-US"
   verification.sms_interception_timeout # => 120
   verification.sms_app_hash             # => "A1b2C3d4E5f", or nil
   verification.sms                      # => the raw SMS Hash

``sms_interception_timeout`` is the number of seconds an on-device client should continue
listening for automatic SMS capture. It is not the verification expiration time. Manual code
entry remains available until ``expires_at``.

``sms_app_hash`` is returned only when an app hash was stored for the verification.

``sms_language`` is the language the API **selected**, which is not necessarily the first one
requested. Compare it with the list you sent to detect a fallback to ``en-US``.

Reading phone call response details
-----------------------------------

A phone call verification includes a ``callout`` object in the response:

.. code-block:: ruby

   verification.callout_language # => "de-DE"
   verification.callout          # => the raw callout Hash

``callout_language`` is the language the announcement was played in. The announcement
recordings are a different set from the SMS templates, so a tag that is honored for SMS can
still fall back for a phone call.

Handling verification status
----------------------------

Use the status predicates instead of comparing status strings directly:

.. code-block:: ruby

   verification.pending?
   verification.verified?
   verification.failed?
   verification.expired?
   verification.denied?
   verification.finished?

``finished?`` returns ``true`` for ``verified``, ``failed``, ``expired``, and ``denied``. It
indicates that polling can stop, but it does not mean that the phone number was verified.
Grant access only when ``verified?`` returns ``true``:

.. code-block:: ruby

   current = client.get_verification(verification.id)

   if current.verified?
     grant_access
   elsif current.pending?
     keep_waiting
   elsif current.finished?
     show_verification_error(current.error_code, current.error_detail)
   else
     report_unknown_status(current.status)
   end

``error_code`` and ``error_detail`` describe an unsuccessful verification result. They are
``nil`` while the verification is pending and when it is verified. These fields are different
from the errors attached to a raised ``APIError``.

.. note::

   The ``fee`` value is the quoted verification fee, not an immediate charge. It is billed
   only when the verification becomes ``verified``. SMS or call delivery costs are billed
   separately.

Using phone numbers instead of IDs
==================================

Use the by-number methods when your application retained the destination number but not the
verification ID:

.. code-block:: ruby

   current = client.get_verification_by_number("+4915112345678")

   result = client.report_verification_by_number(
     "+4915112345678",
     delivery_method: "sms",
     code:            "123456"
   )

Supply the phone number in E.164 format. The leading ``+`` is optional. The SDK percent-encodes
the number for the URL path, but it does not normalize or validate the number.

``get_verification_by_number(...)`` returns the latest verification associated with the
number. ``report_verification_by_number(...)`` reports against the unfinished verification
selected by the API for that number. If no verification can receive the report, the SDK raises
``NotFoundError``.

If another verification is started for the same application and phone number, it supersedes
the previous unfinished verification. Use the ID-based methods when the report or status check
must apply to the exact verification originally shown to the user.

Environments
============

Choose the environment when creating the client. The SDK uses ``:production`` by default.

.. list-table::
   :header-rows: 1
   :widths: 32 68

   * - Environment
     - Base URL
   * - ``:production`` (default)
     - ``https://verification.didww.com``
   * - ``:sandbox``
     - ``https://verification-sandbox.didww.com``
   * - Registered environment
     - A custom base URL registered with ``register_env``.

Use ``:sandbox`` while building and testing your integration:

.. code-block:: ruby

   client = DIDWW::OTPVerification::Client.new(
     key:    ENV.fetch("DIDWW_OTP_KEY"),
     secret: ENV.fetch("DIDWW_OTP_SECRET"),
     env:    :sandbox
   )

Use credentials from an OTP application created in the same environment as the client. See
:ref:`Choose an environment <otp_verification_environments>` for the corresponding User Panel
and API URLs.

Register a custom environment, such as a local test server, and select it by name:

.. code-block:: ruby

   DIDWW::OTPVerification.configure do |config|
     config.register_env(:local, "http://localhost:3000")
   end

   client = DIDWW::OTPVerification::Client.new(
     key:    "your-app-key",
     secret: "your-app-secret",
     env:    :local
   )

The SDK adds ``/api/v1`` to each request path. Do not include that path when registering a
custom base URL.

Configuration
=============

Set shared defaults with ``DIDWW::OTPVerification.configure``. Values passed directly to
``Client.new`` override the global defaults.

.. code-block:: ruby

   DIDWW::OTPVerification.configure do |config|
     config.key       = ENV.fetch("DIDWW_OTP_KEY")
     config.secret    = ENV.fetch("DIDWW_OTP_SECRET")
     config.env       = :sandbox
     config.auth_mode = :basic

     config.faraday do |connection|
       connection.options.open_timeout = 5
       connection.options.timeout = 10
     end
   end

   client = DIDWW::OTPVerification::Client.new

For a multi-tenant application, pass credentials and connection options to each client:

.. code-block:: ruby

   client = DIDWW::OTPVerification::Client.new(
     key:      tenant.otp_key,
     secret:   tenant.otp_secret,
     env:      :production,
     base_url: "https://verification-proxy.example.com"
   ) do |connection|
     connection.proxy = "http://proxy.example.com:3128"
     connection.options.timeout = 10
   end

``base_url:`` overrides ``env:``. The URL must contain the scheme and host but should not
include ``/api/v1``.

The SDK uses Faraday for HTTP transport. A custom Faraday adapter can be supplied with
``adapter:``, but the adapter gem must also be added to your application.

.. warning::

   The SDK does not log requests by default. If you add Faraday logging middleware, configure
   it to redact the ``Authorization`` header, application credentials, phone numbers, and
   submitted codes.

Authentication
==============

Select an authentication mode with ``auth_mode:`` on ``Client.new`` or with the global
``config.auth_mode`` setting. The OTP application's minimum authentication mode must allow the
selected mode. See :ref:`Authentication <otp_verification_authentication>`.

.. list-table::
   :header-rows: 1
   :widths: 22 34 14 30

   * - Mode
     - Header
     - Secret
     - Use
   * - ``:basic`` (default)
     - ``Basic base64(key:secret)``
     - Required
     - Server-to-server integrations.
   * - ``:public``
     - ``Application <key>``
     - Not used
     - Untrusted clients controlled through a request callback.
   * - ``:application``
     - ``Application <key>:<signature>`` and ``x-timestamp``
     - Required
     - Signed server-to-server integrations.

HTTP Basic authentication
-------------------------

``:basic`` is the default mode. It sends the application key as the username and the secret
as the password:

.. code-block:: ruby

   client = DIDWW::OTPVerification::Client.new(
     key:       ENV.fetch("DIDWW_OTP_KEY"),
     secret:    ENV.fetch("DIDWW_OTP_SECRET"),
     auth_mode: :basic
   )

Public authentication
---------------------

``:public`` sends only the application key. A callback URL must be configured on the OTP
application so your backend can approve each start request:

.. code-block:: ruby

   client = DIDWW::OTPVerification::Client.new(
     key:       "your-app-key",
     auth_mode: :public
   )

Public authentication is primarily intended for untrusted clients. A Ruby server can use it
when the verification must still pass through the callback approval flow.

Signed application authentication
---------------------------------

``:application`` signs each request with HMAC-SHA256 and sends an ``x-timestamp`` header. The
SDK builds the signature from the final request bytes, so your application does not need to
implement signing:

.. code-block:: ruby

   client = DIDWW::OTPVerification::Client.new(
     key:       ENV.fetch("DIDWW_OTP_KEY"),
     secret:    ENV.fetch("DIDWW_OTP_SECRET"),
     auth_mode: :application
   )

The application secret must be valid URL-safe Base64. The client validates it during
initialization and raises ``ConfigurationError`` when it cannot be decoded.

.. warning::

   Treat the application secret as a password. Store it in a secrets manager or protected
   environment variable, never in source control or client-side code.

Handling a denied start
=======================

With ``:public`` authentication, the Verification API sends a synchronous request to the OTP
application's callback URL before attempting delivery. A denied start can still return
``201 Created`` because the verification record was created successfully. In this case,
``start_verification(...)`` returns a ``Verification`` with status ``denied`` instead of
raising an exception.

Handle the initial status before asking the user to enter a code:

.. code-block:: ruby

   verification = client.start_verification(
     destination:     "+4915112345678",
     delivery_method: "sms"
   )

   if verification.pending?
     show_code_entry(verification)
   elsif verification.denied?
     show_unavailable(verification.error_code, verification.error_detail)
   else
     handle_unexpected_start_status(verification.status)
   end

An explicit callback denial returns ``error_code`` ``denied_by_callback``. An unusable
callback response returns ``denied_invalid_callback_response``. If no callback URL is
configured, the result is ``denied_missing_callback_url``. See
:ref:`Callbacks <otp_verification_callbacks>` for the complete flow.

Verifying inbound callbacks
===========================

Use ``CallbackVerifier`` to verify a signed ``verification_request`` callback before parsing
its body or deciding whether to allow the verification. The verifier checks the signature and
enforces a five-minute timestamp window by default.

Select the application secret using the key from the ``Authorization`` header, then verify the
exact request bytes:

.. code-block:: ruby

   key, signature = DIDWW::OTPVerification::CallbackVerifier
                    .parse_authorization(request.headers["Authorization"])

   secret = find_application_secret(key)

   valid = secret && DIDWW::OTPVerification::CallbackVerifier.new(secret: secret).valid?(
     method:       request.request_method,
     path:         request.path,
     content_type: request.content_type,
     body:         request.raw_post,
     timestamp:    request.headers["x-timestamp"],
     signature:    signature
   )

   unless valid
     # Return 401 Unauthorized and stop processing the callback.
   end

   # After verification, apply your rules and return {"action":"allow"} or
   # {"action":"deny"} with a 2xx status.

Use the raw body exactly as received. Parsing and serializing the JSON again can change the
bytes and invalidate an otherwise correct signature. The ``path`` value must exactly match the
path of the configured callback URL because it is part of the signature.

The callback verifier can be loaded without the HTTP client in a callback-only service:

.. code-block:: ruby

   require "didww/otp_verification/callback_verifier"

Set a different timestamp tolerance only when required by your deployment:

.. code-block:: ruby

   verifier = DIDWW::OTPVerification::CallbackVerifier.new(
     secret:    application_secret,
     tolerance: 300
   )

Rails
-----

``RailsCallbackVerifier`` reads the signed values from an ``ActionDispatch::Request``. Rails
support is optional and must be required explicitly:

.. code-block:: ruby

   require "didww/otp_verification/rails"

Verify the request in a ``before_action``. After verification succeeds, return the callback
decision from the controller action:

.. code-block:: ruby

   class DidwwCallbacksController < ActionController::API
     before_action :verify_didww_signature

     def create
       allowed = expected_destination?(params.dig(:data, :destination))
       render json: {action: allowed ? "allow" : "deny"}
     end

     private

     def verify_didww_signature
       verifier = DIDWW::OTPVerification::RailsCallbackVerifier.new(
         secret: ENV.fetch("DIDWW_OTP_SECRET")
       )

       return if verifier.valid?(request)

       head :unauthorized
     end
   end

Route the same path that is configured as the callback URL on the OTP application:

.. code-block:: ruby

   # config/routes.rb
   post "/callbacks/didww", to: "didww_callbacks#create"

The example above uses one application secret. If the endpoint receives callbacks for multiple
OTP applications, parse the application key first and select the matching secret before
verifying the request.

Error handling
==============

Client configuration problems and API responses raise errors under
``DIDWW::OTPVerification::Error``. Network failures raised by Faraday are not wrapped by the
SDK.

.. list-table::
   :header-rows: 1
   :widths: 38 18 44

   * - Error class
     - HTTP status
     - When it is raised
   * - ``ConfigurationError``
     - Not applicable
     - The client has a missing key or secret, an unknown environment or auth mode, or an
       invalid signing secret.
   * - ``UnauthorizedError``
     - ``401``
     - Authentication failed or the authentication mode is not allowed.
   * - ``BalanceInsufficientError``
     - ``402``
     - The account balance is insufficient.
   * - ``NotFoundError``
     - ``404``
     - The requested verification could not be found, either because no such verification
       exists for the OTP application or because it passed the
       :ref:`retention period <otp_verification_retention>`.
   * - ``ValidationError``
     - ``400`` or ``422``
     - The request is invalid, including an incorrect code.
   * - ``ServerError``
     - ``5xx``
     - The API encountered a server error.
   * - ``APIError``
     - Other HTTP status
     - The API returned another unsuccessful status or an unexpected successful response body.

Every ``APIError`` provides the following readers:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Reader
     - Description
   * - ``status``
     - HTTP response status.
   * - ``errors``
     - Array of ``ErrorItem`` objects from the API response.
   * - ``code``
     - Machine-readable code from the first error, or ``nil``.
   * - ``codes``
     - Machine-readable codes from all returned errors.
   * - ``response``
     - Original Faraday response.

Each ``ErrorItem`` contains ``code`` and ``detail``. Branch on ``code`` in application logic
and use ``detail`` only as display text. Unknown error codes remain available as raw strings.
An error produced by a proxy or another non-JSON response can have an empty ``errors`` array.
See :ref:`Errors and status codes <otp_verification_api_errors>`.

The following example handles an incorrect code separately from authentication, API, and
network failures:

.. code-block:: ruby

   begin
     result = client.report_verification(
       verification.id,
       delivery_method: "sms",
       code:            submitted_code
     )

     grant_access if result.verified?
   rescue DIDWW::OTPVerification::ValidationError => error
     case error.code
     when "code_invalid"
       show_code_error(error.errors.first&.detail)
     when "too_many_attempts"
       require_new_verification
     else
       show_request_error(error.code, error.message)
     end
   rescue DIDWW::OTPVerification::UnauthorizedError
     report_configuration_error
   rescue DIDWW::OTPVerification::APIError => error
     report_api_error(error.status, error.codes)
   rescue Faraday::TimeoutError, Faraday::ConnectionFailed => error
     show_network_error(error)
   end

Timeouts and retries
====================

Set connection and response timeouts through the Faraday configuration block:

.. code-block:: ruby

   client = DIDWW::OTPVerification::Client.new(
     key:    ENV.fetch("DIDWW_OTP_KEY"),
     secret: ENV.fetch("DIDWW_OTP_SECRET")
   ) do |connection|
     connection.options.open_timeout = 5
     connection.options.timeout = 10
   end

The SDK does not retry requests automatically. If you add retry middleware, choose retry
behavior by operation:

- A status ``GET`` request can be retried after a temporary network failure.
- Do not automatically retry ``start_verification(...)``. The first request may already have
  created a verification, superseded an earlier one, or started delivery.
- Do not automatically retry a report request. Each report can consume one of the allowed
  attempts.

If a report request times out after it may have reached the API, retrieve the verification
status before deciding whether to submit the value again.


.. _otp_verification_methods:

====================
Verification methods
====================

Choose SMS or phone call when you :ref:`start a verification
<otp_verification_api_start>`. Set the method with the ``delivery_method`` field. Both methods
deliver a one-time code that the user reports to your application.

Available methods
=================

.. grid:: 1 2 2 3
    :gutter: 4
    :padding: 0

    .. grid-item-card:: :octicon:`comment` **SMS**
        :link: sms
        :link-type: doc
        :text-align: left

        Send a one-time code in a text message. Use this familiar code-entry flow with
        localized SMS templates.

    .. grid-item-card:: :octicon:`unmute` **Phone Call**
        :link: phone-call
        :link-type: doc
        :text-align: left

        Place a call that reads a one-time code aloud. Use this method when SMS is unavailable
        or for landline numbers.

.. toctree::
   :maxdepth: 1
   :hidden:

   SMS <sms.rst>
   Phone Call <phone-call.rst>



.. _otp_verification_method_sms:

===
SMS
===

Use the **SMS** delivery method to send a one-time code in a text message. The user enters
the code in your application, and your application reports it to the Verification API.

----

How it works
============

1. You start a verification with ``delivery_method`` set to ``sms``.
2. The Verification API sends a text message containing a newly generated numeric code to the
   destination.
3. The user enters the code in your application.
4. Your application reports the ``code`` to the
   :ref:`report endpoint <otp_verification_api_report>`.
5. If the code matches, the verification status becomes ``verified``.

Starting an SMS verification
============================

Set ``delivery_method`` to ``sms``. Add optional SMS settings in an ``sms`` object inside
``data``. The API reads this object only when ``delivery_method`` is ``sms``.

Use ``languages`` to select the preferred message-template languages. Use ``app_hash`` with
Android SMS Retriever so a compatible Android application can capture the incoming code
automatically.

The following example uses HTTP Basic authentication and requests the ``en-US`` message
template:

.. http:example:: curl

   POST /api/v1/verifications HTTP/1.1
   Host: verification.didww.com
   Content-Type: application/json
   Accept: application/json
   Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

   {
     "data": {
       "destination": "+4915112345678",
       "delivery_method": "sms",
       "sms": {
         "languages": ["en-US"]
       }
     }
   }

   HTTP/1.1 201 Created
   Content-Type: application/json

   {
     "data": {
       "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
       "destination": "4915112345678",
       "delivery_method": "sms",
       "fee": "0.06",
       "status": "pending",
       "error_code": null,
       "error_detail": null,
       "expires_at": "2026-07-15T10:02:00.000Z",
       "sms": {
         "template": "Your code is {{CODE}}",
         "language": "en-US",
         "interception_timeout": 120
       }
     }
   }

This response shows an approved start with ``status`` ``pending``. A ``201 Created`` response
can also contain ``status`` ``denied`` when a request callback rejects the verification.
Always inspect ``status`` and ``error_code``.

A ``pending`` status means the verification was accepted for delivery. It does not confirm
that the text message reached the destination.

The response includes an ``sms`` object containing SMS-specific information:

- ``template`` contains the message template. ``{{CODE}}`` marks where the generated code
  appears.
- ``language`` is the language the API selected, which is not necessarily the first one
  requested. Compare it with the list you sent to detect a fallback to ``en-US``.
- ``interception_timeout`` specifies how long an on-device SMS listener should remain active.
  It does not control verification expiry. Manual code entry remains available until
  ``expires_at``.
- ``app_hash`` is returned only when the supplied hash was accepted and stored for the
  verification.

.. _otp_verification_sms_languages:

Supported languages
===================

Pass ``sms.languages`` as BCP 47 tags, most preferred first. The first supported tag wins;
if none of them is supported, the message is sent in ``en-US``.

Tags are matched **exactly**, so the region subtag is required: ``pl`` does not match
``pl-PL`` and falls back to ``en-US``. A tag that is not a well-formed BCP 47 tag is
rejected with :ref:`languages_invalid <otp_verification_api_errors>` instead.

Read ``sms.language`` from the response to see which language was actually used.

The following language tags are supported:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - BCP 47 tag
     - Language
   * - ``bg-BG``
     - Bulgarian (Bulgaria)
   * - ``bs-BA``
     - Bosnian (Bosnia and Herzegovina)
   * - ``cs-CZ``
     - Czech (Czechia)
   * - ``da-DK``
     - Danish (Denmark)
   * - ``de-DE``
     - German (Germany)
   * - ``el-GR``
     - Greek (Greece)
   * - ``en-GB``
     - English (United Kingdom)
   * - ``en-US``
     - English (United States)
   * - ``es-419``
     - Spanish (Latin America)
   * - ``es-ES``
     - Spanish (Spain)
   * - ``et-EE``
     - Estonian (Estonia)
   * - ``fi-FI``
     - Finnish (Finland)
   * - ``fr-FR``
     - French (France)
   * - ``he-IL``
     - Hebrew (Israel)
   * - ``hr-HR``
     - Croatian (Croatia)
   * - ``hu-HU``
     - Hungarian (Hungary)
   * - ``is-IS``
     - Icelandic (Iceland)
   * - ``it-IT``
     - Italian (Italy)
   * - ``ja-JP``
     - Japanese (Japan)
   * - ``ka-GE``
     - Georgian (Georgia)
   * - ``lt-LT``
     - Lithuanian (Lithuania)
   * - ``lv-LV``
     - Latvian (Latvia)
   * - ``mk-MK``
     - Macedonian (North Macedonia)
   * - ``ms-MY``
     - Malay (Malaysia)
   * - ``mt-MT``
     - Maltese (Malta)
   * - ``nb-NO``
     - Norwegian Bokmål (Norway)
   * - ``nl-NL``
     - Dutch (Netherlands)
   * - ``pl-PL``
     - Polish (Poland)
   * - ``pt-BR``
     - Portuguese (Brazil)
   * - ``pt-PT``
     - Portuguese (Portugal)
   * - ``ro-RO``
     - Romanian (Romania)
   * - ``ru-RU``
     - Russian (Russia)
   * - ``sk-SK``
     - Slovak (Slovakia)
   * - ``sl-SI``
     - Slovenian (Slovenia)
   * - ``sq-AL``
     - Albanian (Albania)
   * - ``sr-RS``
     - Serbian (Serbia)
   * - ``sv-SE``
     - Swedish (Sweden)
   * - ``th-TH``
     - Thai (Thailand)
   * - ``uk-UA``
     - Ukrainian (Ukraine)
   * - ``zh-CN``
     - Chinese Simplified (China)
   * - ``zh-HK``
     - Chinese Traditional (Hong Kong)

Reporting the code
==================

Submit the code the user received. The ``delivery_method`` must match the verification.
The following example reports a correct code and returns ``status`` ``verified``:

.. http:example:: curl

   PATCH /api/v1/verifications/0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21 HTTP/1.1
   Host: verification.didww.com
   Content-Type: application/json
   Accept: application/json
   Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

   {
     "data": {
       "delivery_method": "sms",
       "code": "123456"
     }
   }

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "data": {
       "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
       "destination": "4915112345678",
       "delivery_method": "sms",
       "fee": "0.06",
       "status": "verified",
       "error_code": null,
       "error_detail": null,
       "expires_at": "2026-07-15T10:02:00.000Z",
       "sms": {
         "template": "Your code is {{CODE}}",
         "language": "en-US",
         "interception_timeout": 120
       }
     }
   }

The response above shows a successful report. The API returns ``200 OK`` with ``status``
``verified`` when the submitted code matches.

If the submitted code is incorrect, the API returns the following response:

.. code-block:: http

   HTTP/1.1 422 Unprocessable Content
   Content-Type: application/json

   {
     "errors": [
       {
         "code": "code_invalid",
         "detail": "code is invalid"
       }
     ]
   }

After an incorrect report, the verification remains ``pending``, and the user can submit
another code until the attempt limit is reached. After three unsuccessful reports, the
verification becomes ``failed`` with ``error_code`` ``too_many_attempts``.

Next steps
==========

- :ref:`Start a verification <otp_verification_api_start>`: Review all start-request and response fields.
- :ref:`Report a verification <otp_verification_api_report>`: Review all report-request and response fields.


.. _otp_verification_method_phone_call:

==========
Phone call
==========

Use the **phone call** delivery method to place a call that reads a one-time code aloud. The
user enters the code in your application, and your application reports it to the Verification
API. This method is useful when SMS is unavailable or for landline numbers.

.. note::

   In API requests, the phone call delivery method is identified by the value ``callout``.

----

How it works
============

1. You start a verification with ``delivery_method`` set to ``callout``, optionally choosing
   the announcement language.
2. The Verification API places a call to the destination and reads a newly generated numeric
   code aloud in the selected language.
3. The user enters the code they heard in your application.
4. Your application reports the ``code`` to the
   :ref:`report endpoint <otp_verification_api_report>`.
5. If the code matches, the verification status becomes ``verified``.

Start a phone call verification
===============================

Set ``delivery_method`` to ``callout``. Use the optional ``callout`` object to choose the
announcement language.

The following example uses HTTP Basic authentication to start a phone call verification:

.. http:example:: curl

   POST /api/v1/verifications HTTP/1.1
   Host: verification.didww.com
   Content-Type: application/json
   Accept: application/json
   Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

   {
     "data": {
       "destination": "+4915112345678",
       "delivery_method": "callout",
       "callout": {
         "languages": ["de-DE"]
       }
     }
   }

   HTTP/1.1 201 Created
   Content-Type: application/json

   {
     "data": {
       "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
       "destination": "4915112345678",
       "delivery_method": "callout",
       "fee": "0.08",
       "status": "pending",
       "error_code": null,
       "error_detail": null,
       "expires_at": "2026-07-15T10:02:00.000Z",
       "callout": {
         "language": "de-DE"
       }
     }
   }

This response shows an approved start with ``status`` ``pending``. A ``201 Created`` response
can also contain ``status`` ``denied`` when a request callback rejects the verification.
Always inspect ``status`` and ``error_code``.

A ``pending`` status means the verification was accepted for delivery. It does not confirm
that the call was answered or the code was heard.

The response includes a ``callout`` object containing ``language``: the language the
announcement is played in. The code itself is read aloud to the user and is never returned in
the API response.

.. _otp_verification_callout_languages:

Supported languages
===================

Pass ``callout.languages`` as BCP 47 tags, most preferred first. The first supported tag
wins; if none of them is supported, the announcement is played in ``en-US``.

Tags are matched **exactly**, so the region subtag is required: ``pt`` does not match
``pt-PT`` and falls back to ``en-US``. A tag that is not a well-formed BCP 47 tag is
rejected with :ref:`languages_invalid <otp_verification_api_errors>` instead.

Read ``callout.language`` from the response to see which language was actually used.

The following language tags are supported:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - BCP 47 tag
     - Language
   * - ``af-ZA``
     - Afrikaans (South Africa)
   * - ``ar-AE``
     - Arabic (United Arab Emirates)
   * - ``ar-EG``
     - Arabic (Egypt)
   * - ``ar-SA``
     - Arabic (Saudi Arabia)
   * - ``bg-BG``
     - Bulgarian (Bulgaria)
   * - ``bs-BA``
     - Bosnian (Bosnia and Herzegovina)
   * - ``cs-CZ``
     - Czech (Czechia)
   * - ``da-DK``
     - Danish (Denmark)
   * - ``de-DE``
     - German (Germany)
   * - ``el-GR``
     - Greek (Greece)
   * - ``en-GB``
     - English (United Kingdom)
   * - ``en-US``
     - English (United States)
   * - ``es-419``
     - Spanish (Latin America)
   * - ``es-ES``
     - Spanish (Spain)
   * - ``et-EE``
     - Estonian (Estonia)
   * - ``fi-FI``
     - Finnish (Finland)
   * - ``fr-FR``
     - French (France)
   * - ``he-IL``
     - Hebrew (Israel)
   * - ``hi-IN``
     - Hindi (India)
   * - ``hr-HR``
     - Croatian (Croatia)
   * - ``hu-HU``
     - Hungarian (Hungary)
   * - ``id-ID``
     - Indonesian (Indonesia)
   * - ``is-IS``
     - Icelandic (Iceland)
   * - ``it-IT``
     - Italian (Italy)
   * - ``ja-JP``
     - Japanese (Japan)
   * - ``lt-LT``
     - Lithuanian (Lithuania)
   * - ``lv-LV``
     - Latvian (Latvia)
   * - ``mk-MK``
     - Macedonian (North Macedonia)
   * - ``ms-MY``
     - Malay (Malaysia)
   * - ``nb-NO``
     - Norwegian Bokmål (Norway)
   * - ``nl-NL``
     - Dutch (Netherlands)
   * - ``pl-PL``
     - Polish (Poland)
   * - ``pt-BR``
     - Portuguese (Brazil)
   * - ``pt-PT``
     - Portuguese (Portugal)
   * - ``ro-RO``
     - Romanian (Romania)
   * - ``sk-SK``
     - Slovak (Slovakia)
   * - ``sl-SI``
     - Slovenian (Slovenia)
   * - ``sr-RS``
     - Serbian (Serbia)
   * - ``sv-SE``
     - Swedish (Sweden)
   * - ``sw-KE``
     - Swahili (Kenya)
   * - ``th-TH``
     - Thai (Thailand)
   * - ``tl-PH``
     - Tagalog (Philippines)
   * - ``tr-CY``
     - Turkish (Cyprus)
   * - ``tr-TR``
     - Turkish (Turkey)
   * - ``uk-UA``
     - Ukrainian (Ukraine)
   * - ``ur-PK``
     - Urdu (Pakistan)
   * - ``vi-VN``
     - Vietnamese (Vietnam)
   * - ``zh-CN``
     - Chinese Simplified (China)
   * - ``zh-HK``
     - Chinese Traditional (Hong Kong)

Reporting the code
==================

Submit the code the user heard. The ``delivery_method`` must be ``callout``. The following
example reports a correct code and returns ``status`` ``verified``:

.. http:example:: curl

   PATCH /api/v1/verifications/2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e HTTP/1.1
   Host: verification.didww.com
   Content-Type: application/json
   Accept: application/json
   Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

   {
     "data": {
       "delivery_method": "callout",
       "code": "123456"
     }
   }

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "data": {
       "id": "2b3c4d5e-6f70-4b3c-9d0e-1f2a3b4c5d6e",
       "destination": "4915112345678",
       "delivery_method": "callout",
       "fee": "0.08",
       "status": "verified",
       "error_code": null,
       "error_detail": null,
       "expires_at": "2026-07-15T10:02:00.000Z",
       "callout": {
         "language": "de-DE"
       }
     }
   }

The response above shows a successful report. The API returns ``200 OK`` with ``status``
``verified`` when the submitted code matches.

If the submitted code is incorrect, the API returns the following response:

.. code-block:: http

   HTTP/1.1 422 Unprocessable Content
   Content-Type: application/json

   {
     "errors": [
       {
         "code": "code_invalid",
         "detail": "code is invalid"
       }
     ]
   }

After an incorrect report, the verification remains ``pending``, and the user can submit
another code until the attempt limit is reached. After three unsuccessful reports, the
verification becomes ``failed`` with ``error_code`` ``too_many_attempts``.

Next steps
==========

- :ref:`Start a verification <otp_verification_api_start>`: Review all start-request and
  response fields.
- :ref:`Report a verification <otp_verification_api_report>`: Review all report-request and
  response fields.