### Install Composer Dependencies

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Installs the necessary Composer packages for the examples. Ensure you are in the examples directory.

```bash
cd examples && composer install
```

--------------------------------

### Run an Example Script

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Executes an example script using the PHP interpreter. Replace 'your_api_key' with your actual DIDWW API key.

```bash
DIDWW_API_KEY=your_api_key php examples/balance.php
```

--------------------------------

### Install DIDWW API v3 PHP SDK

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Install the SDK using Composer. Ensure you have PHP 8.2+.

```sh
composer require didww/didww-api-3-php-sdk
```

--------------------------------

### Check Emergency Requirements for a Country

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Fetches the emergency service setup requirements for a given country. This helps in understanding the estimated setup time before proceeding.

```php
use Didww\Enum\CallbackMethod;

// Check emergency requirements for a country/type
$requirements = Didww\Item\EmergencyRequirement::all([
    'filter' => ['country.id' => 'country-uuid'],
])->getData();
foreach ($requirements as $req) {
    echo $req->getEstimateSetupTime() . "\n"; // e.g. "7-14 days"
}
```

--------------------------------

### Client Setup

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Configure the global singleton client with credentials and optional Guzzle HTTP options for sandbox or production environments.

```php
use Didww\Credentials;
use Didww\Configuration;

// Sandbox environment
$credentials = new Credentials('YOUR_API_KEY', 'sandbox');
Configuration::configure($credentials, ['timeout' => 20]);

// Production environment
$credentials = new Credentials('YOUR_API_KEY', 'production');
Configuration::configure($credentials, ['timeout' => 30]);

// Custom API version override (defaults to '2026-04-16')
$credentials = new Credentials('YOUR_API_KEY', 'production', '2026-04-16');
Configuration::configure($credentials);
```

--------------------------------

### Create Address

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

This code example demonstrates how to create an address, including city, postal code, street address, and linking it to an identity and country.

```php
$address = new Didww\Item\Address();
$address->setCityName('New York');
$address->setPostalCode('10001');
$address->setAddress('123 Main St');
$address->setIdentity(Didww\Item\Identity::build('identity-uuid'));
$address->setCountry(Didww\Item\Country::build('country-uuid'));
$addressDocument = $address->save()
```

--------------------------------

### Order Capacity

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

This code example demonstrates how to order a specific quantity of capacity from a capacity pool, identified by its pool ID.

```php
// Order capacity
$order = new Didww\Item\Order([
    'items' => [
        new Didww\Item\OrderItem\Capacity([
            'capacity_pool_id' => 'pool-uuid',
            'qty' => 1,
        ]),
    ],
]);
```

--------------------------------

### End-to-End SIP Trunk Registration Flow

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Manages the SIP registration for an in-trunk. This example covers creating a trunk with registration enabled, renaming it, disabling registration by setting the host, and re-enabling it.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;
use DIDWW\Enums\TrunkType;

try {
    $client = new Client();

    // 1. Create an in-trunk with SIP registration enabled
    $trunkData = [
        'name' => 'SIP Registration Trunk',
        'type' => TrunkType::IN,
        'enabled_sip_registration' => true,
        'host' => 'sip.example.com',
        'port' => 5060,
        'use_did_in_ruri' => false
    ];
    $trunk = $client->trunks()->create($trunkData);
    echo "Created trunk with ID: {$trunk['id']}, enabled_sip_registration: " . ($trunk['enabled_sip_registration'] ? 'true' : 'false') . "\n";

    // 2. Rename the trunk
    $renamedTrunk = $client->trunks()->update($trunk['id'], ['name' => 'Renamed SIP Registration Trunk']);
    echo "Renamed trunk to: {$renamedTrunk['name']}\n";

    // 3. Disable SIP registration by setting host to null
    $disabledTrunk = $client->trunks()->update($trunk['id'], ['host' => null]);
    echo "Disabled SIP registration. enabled_sip_registration: " . ($disabledTrunk['enabled_sip_registration'] ? 'true' : 'false') . "\n";

    // 4. Re-enable SIP registration by toggling the flag
    $reEnabledTrunk = $client->trunks()->update($trunk['id'], ['enabled_sip_registration' => true]);
    echo "Re-enabled SIP registration. enabled_sip_registration: " . ($reEnabledTrunk['enabled_sip_registration'] ? 'true' : 'false') . "\n";

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### Order Channel Capacity

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Provides an example of ordering additional channel capacity for a specified capacity pool.

```php
use Didww\Item\Order;
use Didww\Item\OrderItem\Capacity;

// Order channel capacity
$order = new Didww\Item\Order([
    'items' => [
        new Didww\Item\OrderItem\Capacity([
            'capacity_pool_id' => 'pool-uuid',
            'qty'              => 5,
        ]),
    ],
]);
$orderDocument = $order->save();
```

--------------------------------

### Regenerate Voice Out Trunk Credentials

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Provides an example of how to regenerate credentials for an existing voice out trunk.

```php
use Didww\Item\VoiceOutTrunkRegenerateCredential;
use Didww\Item\VoiceOutTrunk;

// Regenerate credentials
$regen = new Didww\Item\VoiceOutTrunkRegenerateCredential();
$regen->setVoiceOutTrunk(Didww\Item\VoiceOutTrunk::build('trunk-uuid'));
$regenDocument = $regen->save();
```

--------------------------------

### Filter, Sort, and Paginate Regions

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Example of fetching regions with applied filters for country ID and name, including related country data, sorting by name, and specifying pagination parameters.

```php
$regionsDocument = Didww\Item\Region::all([
    'filter' => ['country.id' => 'uuid', 'name' => 'Arizona'],
    'include' => 'country',
    'sort' => 'name',
    'page' => ['size' => 25, 'number' => 1],
]);
$regions = $regionsDocument->getData();
```

--------------------------------

### Read-Only Resources

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Examples for retrieving lists of various read-only resources like Countries, Regions, Cities, Areas, NANPA Prefixes, POPs, DID Group Types, Proof Types, Public Keys, Address Requirements, and the Balance.

```APIDOC
## Read-Only Resources

```php
// Countries
$countries = Didww\Item\Country::all()->getData();
$country = Didww\Item\Country::find('uuid')->getData();

// Regions
$regions = Didww\Item\Region::all()->getData();

// Cities
$cities = Didww\Item\City::all()->getData();

// Areas
$areas = Didww\Item\Area::all()->getData();

// NANPA Prefixes
$prefixes = Didww\Item\NanpaPrefix::all()->getData();

// POPs (Points of Presence)
$pops = Didww\Item\Pop::all()->getData();

// DID Group Types
$types = Didww\Item\DidGroupType::all()->getData();

// DID Groups (with stock keeping units)
$groups = Didww\Item\DidGroup::all(['include' => 'stock_keeping_units'])->getData();

// Available DIDs
$available = Didww\Item\AvailableDid::all([
    'include' => 'did_group.stock_keeping_units',
])->getData();

// Proof Types
$proofTypes = Didww\Item\ProofType::all()->getData();

// Public Keys
$publicKeys = Didww\Item\PublicKey::all()->getData();

// Address Requirements (renamed from Requirements in 2026-04-16)
$requirements = Didww\Item\AddressRequirement::all()->getData();

// Balance (singleton)
$balance = Didww\Item\Balance::find()->getData();
```
```

--------------------------------

### Dirty-Only PATCH Serialization in PHP SDK

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Demonstrates how the SDK tracks changes and only sends modified fields in PATCH requests. Useful for optimizing API calls by reducing payload size and preventing unintended data overwrites. Includes examples for loading, building, and updating resources, as well as handling null values and included resources.

```php
// Load a DID from the API - all fields are marked as persisted
$did = Didww\Item\Did::find('uuid')->getData();

// Change only the description - only dirty fields are sent
$did->setDescription('New description');
$did = $did->save()->getData(); // reassign to get synced persisted state
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"description":"New description"}}}
```

```php
// Build a resource by ID and set a single field
$did = Didww\Item\Did::build('uuid');
$did->setCapacityLimit(10);
$did = $did->save()->getData();
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"capacity_limit":10}}}
```

```php
// Explicitly clear a field by setting it to null
$did = Didww\Item\Did::build('uuid');
$did->setDescription(null);
$did = $did->save()->getData();
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"description":null}}}
```

```php
// Included resources also start with clean dirty state
$didDocument = Didww\Item\Did::find('uuid', ['include' => 'voice_in_trunk']);
$trunk = $didDocument->getData()->voiceInTrunk()->getIncluded();
// $trunk has persisted state synced - modifying and saving it sends only dirty fields
$trunk->setName('Renamed trunk');
$trunk = $trunk->save()->getData();
// PATCH body: {"data":{"type":"voice_in_trunks","id":"...","attributes":{"name":"Renamed trunk"}}}
```

--------------------------------

### List, Find, and Update DIDs

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Use `Didww\Item\Did` to manage DIDs. The SDK sends only changed fields in PATCH requests. Ensure you have the necessary setup for DID management.

```php
// List all DIDs with filters and relationships
$dids = Didww\Item\Did::all([
    'filter'  => ['blocked' => false, 'terminated' => false],
    'include' => 'voice_in_trunk,capacity_pool',
    'page'    => ['size' => 50, 'number' => 1],
])->getData();

foreach ($dids as $did) {
    echo $did->getNumber() . ' — created: ' . $did->getCreatedAt()->format('Y-m-d') . "\n";
    echo 'Expires: ' . ($did->getExpiresAt()?->format('Y-m-d') ?? 'never') . "\n";
}
```

```php
// Find a single DID and include its trunk
$didDocument = Didww\Item\Did::find('did-uuid', ['include' => 'voice_in_trunk']);
$did = $didDocument->getData();
$trunk = $did->voiceInTrunk()->getIncluded(); // already-loaded included resource
```

```php
// Update only description (dirty-only PATCH)
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"description":"Main line"}}}
$did->setDescription('Main line');
$did = $did->save()->getData();
```

```php
// Build a resource by UUID and update a single field without loading first
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"capacity_limit":10}}}
$did = Didww\Item\Did::build('did-uuid');
$did->setCapacityLimit(10);
$did = $did->save()->getData();
```

```php
// Assign a SIP trunk to a DID
$did = Didww\Item\Did::build('did-uuid');
$did->setVoiceInTrunk(Didww\Item\VoiceInTrunk::build('trunk-uuid'));
$did->save();
```

```php
// Assign a trunk group instead
$did = Didww\Item\Did::build('did-uuid');
$did->setVoiceInTrunkGroup(Didww\Item\VoiceInTrunkGroup::build('group-uuid'));
$did->save();
```

```php
// Clear a nullable field
$did = Didww\Item\Did::build('did-uuid');
$did->setDescription(null);
$did->save();
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"description":null}}}
```

--------------------------------

### Create Voice Out Trunks with Credentials and IP Authentication

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Shows how to create an outbound SIP trunk using CredentialsAndIp authentication. Server-generated username and password are provided. Includes setting CLI mismatch action and media encryption.

```php
use Didww\Enum\MediaEncryptionMode;
use Didww\Enum\OnCliMismatchAction;
use Didww\Item\AuthenticationMethod\CredentialsAndIp;

// Create with CredentialsAndIp auth
$trunk = new Didww\Item\VoiceOutTrunk();
$trunk->setName('Outbound Trunk ' . bin2hex(random_bytes(4)));
$trunk->setAuthenticationMethod(new CredentialsAndIp([
    'allowed_sip_ips' => ['203.0.0.113.0/24'], // replace with your SIP CIDR
]));
$trunk->setOnCliMismatchAction(OnCliMismatchAction::REJECT_CALL);
$trunk->setMediaEncryptionMode(MediaEncryptionMode::DISABLED);
$trunk->setCapacityLimit('100');
$trunk->setDefaultDid(Didww\Item\Did::build('did-uuid'));

$trunkDocument = $trunk->save();
$trunk = $trunkDocument->getData();
$auth = $trunk->getAuthenticationMethod();
echo $auth->getUsername() . "\n"; // server-generated
echo $auth->getPassword() . "\n"; // server-generated
echo ($trunk->isActive() ? 'active' : 'blocked') . "\n";
```

--------------------------------

### VoiceOutTrunk Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/voice_out_trunks endpoint.

```APIDOC
## GET /v3/voice_out_trunks

### Description
Retrieves a list of voice-out trunks with optional filtering.

### Method
GET

### Endpoint
/v3/voice_out_trunks

### Query Parameters
- **filter[allow_any_did_as_cli]** (boolean) - Optional - Filter by whether any DID is allowed as CLI.
- **filter[authentication_method.type]** (string) - Optional - Filter by authentication method type.
- **filter[default_did.id]** (string) - Optional - Filter by default DID ID.
- **filter[default_dst_action]** (string) - Optional - Filter by default destination action.
- **filter[external_reference_id]** (string) - Optional - Filter by external reference ID.
- **filter[media_encryption_mode]** (string) - Optional - Filter by media encryption mode.
- **filter[name]** (string) - Optional - Filter by name.
- **filter[name_contains]** (string) - Optional - Filter by name containing a specific string.
- **filter[on_cli_mismatch_action]** (string) - Optional - Filter by action on CLI mismatch.
- **filter[status]** (string) - Optional - Filter by status.
- **filter[threshold_reached]** (boolean) - Optional - Filter by whether the threshold is reached.
```

--------------------------------

### Configuration

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Configure the SDK with your API credentials for either sandbox or production environments. Set a timeout for requests.

```APIDOC
## Configuration

### Sandbox
```php
$credentials = new Didww\Credentials('YOUR_API_KEY', 'sandbox');
Didww\Configuration::configure($credentials, ['timeout' => 20]);
```

### Production
```php
$credentials = new Didww\Credentials('YOUR_API_KEY', 'production');
Didww\Configuration::configure($credentials, ['timeout' => 20]);
```

### Environments

| Environment | Base URL |
|-------------|----------|
| `production` | `https://api.didww.com/v3` |
| `sandbox` | `https://sandbox-api.didww.com/v3` |
```

--------------------------------

### VoiceInTrunk Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/voice_in_trunks endpoint.

```APIDOC
## GET /v3/voice_in_trunks

### Description
Retrieves a list of voice-in trunks with optional filtering.

### Method
GET

### Endpoint
/v3/voice_in_trunks

### Query Parameters
- **filter[configuration.type]** (string) - Optional - Filter by configuration type.
- **filter[external_reference_id]** (string) - Optional - Filter by external reference ID.
- **filter[name]** (string) - Optional - Filter by name.
```

--------------------------------

### VoiceInTrunkGroup Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/voice_in_trunk_groups endpoint.

```APIDOC
## GET /v3/voice_in_trunk_groups

### Description
Retrieves a list of voice-in trunk groups with optional filtering.

### Method
GET

### Endpoint
/v3/voice_in_trunk_groups

### Query Parameters
- **filter[external_reference_id]** (string) - Optional - Filter by external reference ID.
```

--------------------------------

### SupportingDocumentTemplate Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/supporting_document_templates endpoint.

```APIDOC
## GET /v3/supporting_document_templates

### Description
Retrieves a list of supporting document templates with optional filtering.

### Method
GET

### Endpoint
/v3/supporting_document_templates

### Query Parameters
- **filter[name]** (string) - Optional - Filter by template name.
- **filter[name_contains]** (string) - Optional - Filter by template name containing a specific string.
- **filter[permanent]** (boolean) - Optional - Filter by permanent status.
```

--------------------------------

### Configure SIP Trunk with SIP Registration in PHP

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Illustrates how to configure a Voice In Trunk for SIP registration authentication. This involves setting `enabled_sip_registration` to true and understanding how the SDK cascades dependent fields. Server-generated credentials (`incoming_auth_username`, `incoming_auth_password`) are surfaced in the response.

```php
$sip = new Didww\Item\Configuration\Sip([
    'enabled_sip_registration' => true,
    'use_did_in_ruri' => true,
    'cnam_lookup' => true,
]);

$trunk = new Didww\Item\VoiceInTrunk(['name' => 'Office (registered)', 'configuration' => $sip]);
$created = $trunk->save()->getData();
$config = $created->getConfiguration();
// $config->getIncomingAuthUsername() — server-generated
// $config->getIncomingAuthPassword() — server-generated
```

--------------------------------

### List DIDs and Demonstrate Updates

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Lists all DIDs associated with the account and demonstrates how to update DID information, including emergency fields.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;

try {
    $client = new Client();

    // List DIDs
    $dids = $client->dids()->list();

    if (!empty($dids)) {
        echo "First DID details:\n";
        $firstDid = $dids[0];
        echo "DID: {$firstDid['did']}\n";
        echo "Status: {$firstDid['status']}\n";

        // Demonstrate DID update (example with emergency fields)
        $updateData = [
            'caller_id_name' => 'Test Name',
            'emergency_fields' => [
                'address_id' => 12345 // Replace with a valid address ID
            ]
        ];
        $updatedDid = $client->dids()->update($firstDid['id'], $updateData);
        echo "\nUpdated DID {$firstDid['id']} details:\n";
        echo "Caller ID Name: {$updatedDid['caller_id_name']}\n";
        echo "Emergency Address ID: {$updatedDid['emergency_fields']['address_id']}\n";

    } else {
        echo "No DIDs found.";
    }

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### SharedCapacityGroup Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/shared_capacity_groups endpoint.

```APIDOC
## GET /v3/shared_capacity_groups

### Description
Retrieves a list of shared capacity groups with optional filtering.

### Method
GET

### Endpoint
/v3/shared_capacity_groups

### Query Parameters
- **filter[capacity_pool.id]** (string) - Optional - Filter by capacity pool ID.
- **filter[external_reference_id]** (string) - Optional - Filter by external reference ID.
- **filter[name]** (string) - Optional - Filter by name.
```

--------------------------------

### Region Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/regions endpoint.

```APIDOC
## GET /v3/regions

### Description
Retrieves a list of regions with optional filtering.

### Method
GET

### Endpoint
/v3/regions

### Query Parameters
- **filter[country.id]** (string) - Optional - Filter regions by country ID.
- **filter[iso]** (string) - Optional - Filter regions by ISO code.
- **filter[name]** (string) - Optional - Filter regions by name.
```

--------------------------------

### Read-Only Reference Resources: Proof Types and Public Keys

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Fetches proof types and public keys.

```php
// Proof types and public keys
$proofTypes = Didww\Item\ProofType::all()->getData();
$publicKeys = Didww\Item\PublicKey::all()->getData();
```

--------------------------------

### ProofType Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/proof_types endpoint.

```APIDOC
## GET /v3/proof_types

### Description
Retrieves a list of proof types with optional filtering.

### Method
GET

### Endpoint
/v3/proof_types

### Query Parameters
- **filter[entity_type]** (string) - Optional - Filter proof types by entity type.
```

--------------------------------

### Proof Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/proofs endpoint.

```APIDOC
## GET /v3/proofs

### Description
Retrieves a list of proofs with optional filtering.

### Method
GET

### Endpoint
/v3/proofs

### Query Parameters
- **filter[external_reference_id]** (string) - Optional - Filter proofs by their external reference ID.
```

--------------------------------

### Order DIDs by SKU with Back-ordering

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Illustrates ordering DIDs by SKU, with the option to allow back-ordering if DIDs are not immediately available. Includes setting up callback URLs for asynchronous notifications.

```php
use Didww\Enum\CallbackMethod;
use Didww\Item\Order;
use Didww\Item\OrderItem\Did;

// Order DIDs by SKU (with back-ordering enabled)
$order = new Didww\Item\Order([
    'allow_back_ordering' => true,
    'items' => [
        new Didww\Item\OrderItem\Did(['sku_id' => 'sku-uuid', 'qty' => 2]),
    ],
]);
$order->setCallbackUrl('https://example.com/webhook/orders');
$order->setCallbackMethod(CallbackMethod::POST);
$orderDocument = $order->save();
$order = $orderDocument->getData();
echo $order->getReference() . "\n";     // order reference string
echo $order->getStatus()->value . "\n"; // "pending"
echo $order->getAmount() . "\n";        // total amount
```

--------------------------------

### PermanentSupportingDocument Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/permanent_supporting_documents endpoint.

```APIDOC
## GET /v3/permanent_supporting_documents

### Description
Retrieves a list of permanent supporting documents with optional filtering.

### Method
GET

### Endpoint
/v3/permanent_supporting_documents

### Query Parameters
- **filter[external_reference_id]** (string) - Optional - Filter documents by their external reference ID.
```

--------------------------------

### Order Filters

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/FILTERS.md

Filters available for the GET /v3/orders endpoint.

```APIDOC
## GET /v3/orders

### Description
Retrieves a list of orders with optional filtering.

### Method
GET

### Endpoint
/v3/orders

### Query Parameters
- **filter[created_at_gteq]** (string) - Optional - Filter orders created on or after a specific date.
- **filter[created_at_lteq]** (string) - Optional - Filter orders created on or before a specific date.
- **filter[external_reference_id]** (string) - Optional - Filter orders by their external reference ID.
- **filter[reference]** (string) - Optional - Filter orders by their reference.
- **filter[status]** (string) - Optional - Filter orders by their status.
```

--------------------------------

### Fetch Proof Types

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Retrieve a list of all available proof types.

```php
// Proof Types
$proofTypes = Didww\Item\ProofType::all()->getData();
```

--------------------------------

### Configure DIDWW API v3 PHP SDK Client

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Initialize the global singleton client with credentials and optional Guzzle HTTP options. Supports sandbox and production environments, and custom API version overrides.

```php
use Didww\Credentials;
use Didww\Configuration;

// Sandbox environment
$credentials = new Credentials('YOUR_API_KEY', 'sandbox');
Configuration::configure($credentials, ['timeout' => 20]);

// Production environment
$credentials = new Credentials('YOUR_API_KEY', 'production');
Configuration::configure($credentials, ['timeout' => 30]);

// Custom API version override (defaults to '2026-04-16')
$credentials = new Credentials('YOUR_API_KEY', 'production', '2026-04-16');
Configuration::configure($credentials);

// Environments:
// sandbox:    https://sandbox-api.didww.com/v3
// production: https://api.didww.com/v3
```

--------------------------------

### Configure DIDWW API Client

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Configure the SDK with your API credentials and desired environment (sandbox or production). Set a timeout for requests.

```php
$credentials = new Didww\Credentials('YOUR_API_KEY', 'sandbox');
Didww\Configuration::configure($credentials, ['timeout' => 20]);
```

```php
$credentials = new Didww\Credentials('YOUR_API_KEY', 'production');
Didww\Configuration::configure($credentials, ['timeout' => 20]);
```

--------------------------------

### Create and Release DID Reservations

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Demonstrates how to temporarily reserve an available DID for a limited time, and how to release the reservation before it expires.

```php
use Didww\Item\DidReservation;
use Didww\Item\AvailableDid;

$reservation = new Didww\Item\DidReservation();
$reservation->setDescription('Reserved for client ABC');
$reservation->setAvailableDid(Didww\Item\AvailableDid::build('available-did-uuid'));
$reservationDocument = $reservation->save();

if (!$reservationDocument->hasErrors()) {
    $reservation = $reservationDocument->getData();
    echo $reservation->getId() . "\n";
    echo $reservation->getExpiresAt()?->format('Y-m-d H:i:s') . "\n";
}

// Release a reservation
$reservation->delete();
```

--------------------------------

### Create and Manage Voice In Trunk Groups

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Demonstrates how to create, update, and delete voice inbound trunk groups for load balancing. Includes error handling for save operations.

```php
$group = new Didww\Item\VoiceInTrunkGroup();
$group->setName('Primary Group ' . bin2hex(random_bytes(4)));
$group->setCapacityLimit(50);
$groupDocument = $group->save();

if ($groupDocument->hasErrors()) {
    foreach ($groupDocument->getErrors() as $error) {
        echo $error->getDetail() . "\n";
    }
} else {
    $group = $groupDocument->getData();
    echo $group->getId() . "\n";
    echo $group->getName() . "\n";
}

// Update and delete
$group->setName('Updated Group');
$group->save();
$group->delete();
```

--------------------------------

### Create, Update, and Delete SIP Voice In Trunk in PHP

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Shows how to create a new SIP trunk with specific configurations, update an existing trunk, and delete a trunk using the DIDWW PHP SDK. Ensure all necessary enum values and default IDs are correctly set during creation.

```php
use Didww\Enum\CliFormat;
use Didww\Enum\Codec;
use Didww\Enum\MediaEncryptionMode;
use Didww\Enum\SstRefreshMethod;
use Didww\Enum\TransportProtocol;

// Create SIP trunk
$sip = new Didww\Item\Configuration\Sip([
    'host' => 'sip.example.com',
    'port' => 5060,
    'codec_ids' => Didww\Item\Configuration\Base::getDefaultCodecIds(),
    'transport_protocol_id' => TransportProtocol::UDP,
    'sst_refresh_method_id' => SstRefreshMethod::INVITE,
    'media_encryption_mode' => MediaEncryptionMode::DISABLED,
    'rerouting_disconnect_code_ids' => Didww\Item\Configuration\Base::getDefaultReroutingDisconnectCodeIds(),
]);

$trunk = new Didww\Item\VoiceInTrunk();
$trunk->setName('My SIP Trunk');
$trunk->setCliFormat(CliFormat::E164);
$trunk->setRingingTimeout(30);
$trunk->setConfiguration($sip);

$trunkDocument = $trunk->save();
$trunk = $trunkDocument->getData();

// Update trunk
$trunk->setDescription('Updated');
$trunk->save();

// Delete trunk
$trunk->delete();
```

--------------------------------

### Filtering Voice Out Trunks

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Provides examples for filtering voice out trunks based on status, CLI mismatch action, and authentication method type.

```APIDOC
## Filtering Voice Out Trunks

```php
// Voice Out Trunks
Didww\Item\VoiceOutTrunk::all(['filter' => [
    'status'                    => 'active',
    'on_cli_mismatch_action'    => 'reject_call',
    'authentication_method.type' => 'credentials_and_ip',
]])->getData();
```
```

--------------------------------

### Emergency Services

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Manages E911/emergency calling setup for DIDs, including checking requirements, creating verifications, and listing active emergency calling services.

```APIDOC
## Emergency Services

`Didww\Item\EmergencyVerification` and `Didww\Item\EmergencyCallingService` manage E911/emergency calling setup for DIDs (API 2026-04-16).

```php
use Didww\Enum\CallbackMethod;

// Check emergency requirements for a country/type
$requirements = Didww\Item\EmergencyRequirement::all([
    'filter' => ['country.id' => 'country-uuid'],
])->getData();
foreach ($requirements as $req) {
    echo $req->getEstimateSetupTime() . "\n"; // e.g. "7-14 days"
}

// Create an emergency verification
$emergVerification = new Didww\Item\EmergencyVerification();
$emergVerification->setCallbackUrl('https://example.com/webhook/emergency');
$emergVerification->setCallbackMethod(CallbackMethod::POST);
$emergVerification->setAddress(Didww\Item\Address::build('address-uuid'));
$emergVerification->setDids([Didww\Item\Did::build('did-uuid')]);
$emergDocument = $emergVerification->save();
$emergVerification = $emergDocument->getData();
echo $emergVerification->getStatus()->value . "\n"; // "pending"

// List emergency calling services
$services = Didww\Item\EmergencyCallingService::all([
    'filter' => ['status' => 'active'],
])->getData();
foreach ($services as $svc) {
    echo $svc->getName() . ' — ' . $svc->getStatus()->value . "\n";
    echo 'Activated: ' . ($svc->getActivatedAt()?->format('Y-m-d') ?? 'N/A') . "\n";
}
```
```

--------------------------------

### List Orders with Filters

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Shows how to retrieve a list of orders, applying filters (e.g., by status) and sorting (e.g., by creation date).

```php
use Didww\Item\Order;

// List orders with filters
$orders = Didww\Item\Order::all([
    'filter' => ['status' => 'pending'],
    'sort'   => '-created_at',
])->getData();
foreach ($orders as $o) {
    echo $o->getReference() . ' — ' . $o->getCreatedAt()->format('Y-m-d') . "\n";
}
```

--------------------------------

### Webhook Signature Validation

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

This section explains how to validate incoming DIDWW webhook callbacks using HMAC-SHA1. It provides a code example for checking the `X-DIDWW-Signature` header.

```APIDOC
## Webhook Signature Validation

`Didww\Callback\RequestValidator` validates incoming DIDWW webhook callbacks using HMAC-SHA1 with the API key. Check the `X-DIDWW-Signature` header.

```php
use Didww\Callback\RequestValidator;

// In your webhook controller / handler:
$apiKey    = 'YOUR_API_KEY';
$validator = new RequestValidator($apiKey);

// Reconstruct full URL and payload from incoming request
$requestUrl  = 'https://example.com/webhook/orders?ref=abc123';
$payloadParams = [
    'event'      => 'order.completed',
    'order_id'   => 'order-uuid',
    'status'     => 'completed',
];
$signature = $_SERVER['HTTP_X_DIDWW_SIGNATURE'] ?? '';

$valid = $validator->validate($requestUrl, $payloadParams, $signature);

if ($valid) {
    echo "Webhook signature is valid\n";
    // process event...
} else {
    http_response_code(403);
    echo "Invalid signature\n";
}

// Get the expected header name:
echo RequestValidator::getHeaderName(); // "X-DIDWW-Signature"
```
```

--------------------------------

### Create Voice Out Trunk with Credentials and IP Authentication

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Use this snippet to create a new voice out trunk with credentials and IP-based authentication. Ensure to replace the placeholder IP address with your actual SIP infrastructure CIDR. The username and password for authentication are server-generated.

```php
use Didww\Enum\OnCliMismatchAction;
use Didww\Item\AuthenticationMethod\CredentialsAndIp;

$trunk = new Didww\Item\VoiceOutTrunk();
$trunk->setName('My Outbound Trunk');
// NOTE: 203.0.113.0/24 is RFC 5737 TEST-NET-3 documentation space.
// Replace with the real CIDR of your SIP infrastructure.
$trunk->setAuthenticationMethod(new CredentialsAndIp([
    'allowed_sip_ips' => ['203.0.113.0/24'],
]));
$trunk->setOnCliMismatchAction(OnCliMismatchAction::REPLACE_CLI);
$trunk->setDefaultDid(Didww\Item\Did::build('did-uuid'));
$trunkDocument = $trunk->save();
// $trunkDocument->getData()->getAuthenticationMethod()->getUsername() -- server-generated
// $trunkDocument->getData()->getAuthenticationMethod()->getPassword() -- server-generated
```

--------------------------------

### Create SIP and PSTN Trunks

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Creates both SIP and PSTN trunks using enum-based configuration. Prints the details of the created trunks.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;
use DIDWW\Enums\TrunkType;
use DIDWW\Enums\TrunkProtocol;

try {
    $client = new Client();

    // Create a SIP trunk
    $sipTrunkData = [
        'name' => 'My SIP Trunk',
        'type' => TrunkType::SIP,
        'protocol' => TrunkProtocol::SIP,
        'capacity' => 10,
        'description' => 'SIP trunk for outgoing calls'
    ];
    $sipTrunk = $client->trunks()->create($sipTrunkData);
    echo "Created SIP Trunk - ID: {$sipTrunk['id']}, Name: {$sipTrunk['name']}\n";

    // Create a PSTN trunk
    $pstnTrunkData = [
        'name' => 'My PSTN Trunk',
        'type' => TrunkType::PSTN,
        'capacity' => 5,
        'description' => 'PSTN trunk for incoming calls'
    ];
    $pstnTrunk = $client->trunks()->create($pstnTrunkData);
    echo "Created PSTN Trunk - ID: {$pstnTrunk['id']}, Name: {$pstnTrunk['name']}\n";

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### Order DID by SKU

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

This snippet demonstrates how to order a DID by its SKU. It includes setting a callback URL and method for order status updates.

```php
use Didww\Enum\CallbackMethod;

// Order by SKU
$order = new Didww\Item\Order([
    'allow_back_ordering' => true,
    'items' => [
        new Didww\Item\OrderItem\Did(['sku_id' => 'sku-uuid', 'qty' => 2]),
    ],
]);
$order->setCallbackUrl('https://example.com/callback');
$order->setCallbackMethod(CallbackMethod::POST);
$orderDocument = $order->save()
```

--------------------------------

### Create Voice Out Trunks with Twilio Authentication

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Demonstrates creating an outbound SIP trunk specifically for Twilio integration, requiring only the Twilio Account SID.

```php
use Didww\Item\AuthenticationMethod\Twilio;

// Create with Twilio auth
$trunk = new Didww\Item\VoiceOutTrunk();
$trunk->setName('Twilio Trunk ' . bin2hex(random_bytes(4)));
$trunk->setAuthenticationMethod(new Twilio([
    'twilio_account_sid' => 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
]));
$trunk->save();
```

--------------------------------

### Create Voice In Trunk Group in PHP

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Demonstrates the creation of a Voice In Trunk Group with a specified name and capacity limit using the DIDWW PHP SDK.

```php
$group = new Didww\Item\VoiceInTrunkGroup();
$group->setName('Primary Group');
$group->setCapacityLimit(50);
$groupDocument = $group->save();
```

--------------------------------

### Order a Reserved DID

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Demonstrates ordering a DID that has been previously reserved, using the reservation ID.

```php
use Didww\Item\Order;
use Didww\Item\OrderItem\ReservationDid;

// Order a reserved DID
$order = new Didww\Item\Order([
    'items' => [
        new Didww\Item\OrderItem\ReservationDid([
            'sku_id'             => 'sku-uuid',
            'did_reservation_id' => 'reservation-uuid',
        ]),
    ],
]);
$order->save();
```

--------------------------------

### List and Create Emergency Verifications

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Fetches existing emergency verifications and demonstrates how to create a new one. This is crucial for emergency service compliance.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;

try {
    $client = new Client();

    // List existing emergency verifications
    $verifications = $client->emergencyVerifications()->list();
    echo "Existing Emergency Verifications:\n";
    foreach ($verifications as $verification) {
        echo "- ID: {$verification['id']}, Status: {$verification['status']}, Created At: {$verification['created_at']}\n";
    }

    // Example: Create a new emergency verification (replace with valid IDs)
    // $verificationData = [
    //     'address_id' => 12345,
    //     'identity_id' => 67890,
    //     'requirement_id' => 112233
    // ];
    // $newVerification = $client->emergencyVerifications()->create($verificationData);
    // echo "\nCreated new emergency verification - ID: {$newVerification['id']}, Status: {$newVerification['status']}\n";

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### Create and List CDR Exports

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Demonstrates the creation of Call Detail Record (CDR) exports and listing existing exports. Includes the `external_reference_id` field.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;

try {
    $client = new Client();

    // Create a CDR export
    $exportData = [
        'type' => 'cdr',
        'filter' => [
            'date_from' => '2023-01-01',
            'date_to' => '2023-01-31'
        ],
        'external_reference_id' => 'my-cdr-export-123'
    ];
    $newExport = $client->exports()->create($exportData);
    echo "Created CDR export with ID: {$newExport['id']}\n";

    // List CDR exports
    $exports = $client->exports()->list(['type' => 'cdr']);
    echo "\nExisting CDR Exports:\n";
    foreach ($exports as $export) {
        echo "- ID: {$export['id']}, Status: {$export['status']}, External Reference: {$export['external_reference_id']}\n";
    }

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### List Regions with Pagination

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Lists regions, demonstrating the use of 'includes' for related data and pagination parameters for handling large result sets.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;

try {
    $client = new Client();

    // List regions with includes and pagination
    $regions = $client->regions()->list([
        'includes' => ['country'],
        'page' => 1,
        'per_page' => 5
    ]);

    echo "Regions (Page 1):\n";
    foreach ($regions as $region) {
        echo "- {$region['name']} ({$region['region_code']}), Country: {$region['country']['name']}\n";
    }

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### Order a Specific Available DID

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Shows how to order a DID that has already been identified as available, using its specific ID.

```php
use Didww\Item\Order;
use Didww\Item\OrderItem\AvailableDid;

// Order a specific available DID
$order = new Didww\Item\Order([
    'items' => [
        new Didww\Item\OrderItem\AvailableDid([
            'sku_id'           => 'sku-uuid',
            'available_did_id' => 'available-did-uuid',
        ]),
    ],
]);
$order->save();
```

--------------------------------

### List Identities, Addresses, and Proofs

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/examples/README.md

Retrieves lists of identities, addresses, and proofs associated with the account. Includes the `birth_country` field for identities.

```php
<?php

require __DIR__ . '/../vendor/autoload.php';

use DIDWW\Client;

try {
    $client = new Client();

    // List identities
    $identities = $client->identities()->list(['includes' => ['address', 'proofs']]);
    echo "Identities:\n";
    foreach ($identities as $identity) {
        echo "- ID: {$identity['id']}, Name: {$identity['first_name']} {$identity['last_name']}, Birth Country: {$identity['birth_country']}\n";
        // You can further loop through 'address' and 'proofs' if included
    }

    // List addresses
    $addresses = $client->addresses()->list();
    echo "\nAddresses:\n";
    foreach ($addresses as $address) {
        echo "- ID: {$address['id']}, Street: {$address['street']}, City: {$address['city']}\n";
    }

    // List proofs
    $proofs = $client->proofs()->list();
    echo "\nProofs:\n";
    foreach ($proofs as $proof) {
        echo "- ID: {$proof['id']}, Type: {$proof['type']}, Filename: {$proof['filename']}\n";
    }

} catch (\Exception $e) {
    echo "Error: {$e->getMessage()}\n";
}

```

--------------------------------

### Create and Delete DID Reservation

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

This snippet covers creating a DID reservation with a description and associating it with an available DID. It also shows how to delete an existing reservation.

```php
$reservation = new Didww\Item\DidReservation();
$reservation->setDescription('Reserved for client');
$reservation->setAvailableDid(Didww\Item\AvailableDid::build('available-did-uuid'));
$reservationDocument = $reservation->save();

// Delete reservation
$reservation->delete()
```

--------------------------------

### Fetch Account Balance

Source: https://context7.com/didww/didww-api-3-php-sdk/llms.txt

Fetches the account balance singleton using `Didww\Item\Balance::find()`. No UUID argument is required.

```php
$balance = Didww\Item\Balance::find()->getData();
echo "Total balance: " . $balance->getTotalBalance() . "\n";
// e.g. "Total balance: 42.50"
```

--------------------------------

### Download Export

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

This code shows how to download a completed export file to a specified local path.

```php
// Download the export when completed
$export = $exportDocument->getData();
$export->download('/tmp/export.csv')
```

--------------------------------

### Fetch Cities

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Retrieve a list of all available cities.

```php
// Cities
$cities = Didww\Item\City::all()->getData();
```

--------------------------------

### Fetch NANPA Prefixes

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

Retrieve a list of all available NANPA prefixes.

```php
// NANPA Prefixes
$prefixes = Didww\Item\NanpaPrefix::all()->getData();
```

--------------------------------

### Create Identity

Source: https://github.com/didww/didww-api-3-php-sdk/blob/master/README.md

This snippet shows how to create a new identity with personal details and specify its type. An associated country must also be provided.

```php
use Didww\Enum\IdentityType;

$identity = new Didww\Item\Identity([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone_number' => '12125551234',
    'identity_type' => IdentityType::PERSONAL,
]);
$identity->setCountry(Didww\Item\Country::build('country-uuid'));
$identityDocument = $identity->save()
```