DNID

For the impatient

You may explore this data model via the API Playground, by clicking here

Description

The Cloudonix DNID model represents the binding of certain phone numbers to a voice application configuration, so that when a call has a destination that matches a DNID in the domain, the bound application will be launched.

Properties

Property	Type	Editable	Description
id	Number	No	The unique system identifier for this DNID.
dnid	String	Create, Update	The DNID expression as a regular expression. The Cloudonix Platform offers multiple compatilibity modes so creating a DNID regular expression directly is unneeded and discouraged. See below for details.
source	String	Create, Update	The DNID expression source, to be understood as per the compatibility flags specified below.
prefix	Boolean	Create, Update	DNID expression type: prefix match - this DNID will match any destination that starts with exactly the text in source field, followed by 0 or more additional characters. Default: false.
expression	Boolean	Create, Update	DNID expression type: glob expression - this DNID will match any destination that matches the source field according to glob matching rules. Default: false.
asteriskCompatible	Boolean	Create, Update	DNID experssion type: Asterisk compatible - this DNID will match any destination that would match the Asterisk dial plan extension pattern specified in the source field. Default: false.
application	Object	Create	The Voice Application that will be activated when this number is called.
active	Boolean	Update	Whether this DNID is active and can be matched against. Default: true.

DNID Expression Matching

The simplest way to create DNID expressions is to just set the source field to the exact number you want to match and set all the compatibility flags to false - such a DNID will only match calls to that specific destination number.

Often you want a more "dynamic" way to activate applications, such as capture all calls to destinations that start with a known prefix, or expressions even more complex than that. To facilitate this, Cloudonix supports the following additional flexible rules:

Prefix Matcher

When setting the prefix flag to true, Cloudonix will match any destination that start with the specified value in the source field and are followed by 0 or more additional characters.

This flag may be set in addition to the expression flag.

Glob Expression Matcher

When setting the expression flag to true, Cloudnix will match any destination that matches the glob matching pattern specified in the source field.

This flag may be set in addition to the prefix flag. If both flags are set, Cloudonix will matches the glob pattern followed by 0 or more additional characters.

Asterisk Compatible Expression Matcher

When setting the asteriskCompatible flag, Cloudonix will match any destination that matches the Asterisk dialplan extension pattern specified in the source field.

If this flag is set, neither prefix nor expression flags may be set.

Regular Expression Matcher

Cloudonix performs the actual matching by compiling the value of the source field, according to the compatibility flags discussed above, to a regular expression, and the results can be seen in the dnid field when retrieving a DNID object after it is created or updated.

If a DNID matching pattern is required that is more complex than what is comfortable to do with one of the compatibility flags (or if you are very comfortable with regular expressions), it is allowed to set the dnid field directly to a regular expression value. When setting the dnid field, make sure not to set the source field (or set it to null), otherwise Cloudonix will ignore the value of the dnid field and overwrite it with the result of compiling the source field. Additionally, if the dnid field is set in such a way - all compatibility flags will be forced to false.

API Reference

Base Path /customers/{customer}/domains/{domain}/dnids[/{dnid}]

Request Example

$ curl 'https://api.cloudonix.io/customers/example-customer/domains/example.com/dnids \
--header 'Authorization: Bearer XI•••••••••••••••' -s

When accessing a specific DNID, the DNID may be specified by either the source value of the DNID, or by using the DNID's unique system identifier.

List DNID

GET /customers/{customer}/domains/{domain}/dnids

List all DNID numbers in the domain and their bound application configurations. Returns an array of DNID JSON model objects.

Example

$ curl 'https://api.cloudonix.io/domains/cloudonix-demo-customer.cloudonix.net/dnids'
  --header 'Authorization: Bearer •••••••••••••••'

[
    {
        "id": 552,
        "active": true,
        "dnid": "^(20000.*)$",
        "source": "20000",
        "global": false,
        "expression": false,
        "prefix": true,
        "asteriskCompatible": false,
        "application": {
          ...
        }
    }
]

Retrieve a DNID

GET /customers/{customer}/domains/{domain}/dnids/{dnid}

Retrieve a specific DNID destination configuration, and its respective Voice Application assosciation. Returns a single DNID JSON model object.

Create a DNID

POST /customers/{customer-id}/domains/{domain}/applications/{voice_application}/dnids

Create a new DNID number and associate it to a specific voice application.

PAY ATTENTION

When creating a new DNID number, it must be associated to a Voice Application.

$ curl 'https://api.cloudonix.io/customers/self/domains/mydomain.cloudonix.net/applications/myHelloWorldVoiceApplication/dnids' \
  --header 'Authorization: Bearer XI•••••••••••••••' \
  --data-raw '{ "source":"_30000", "prefix":false, "expression":false, "asteriskCompatible":true }'

{
    "id": 553,
    "domainId": 832,
    "applicationId": 2081,
    "messagingApplicationId": null,
    "active": true,
    "dnid": "^(30000)$",
    "source": "_30000",
    "global": false,
    "expression": false,
    "prefix": false,
    "asteriskCompatible": true,
    "application": {
      ...
    }
}

Update a DNID

PATCH /customers/{customer-id}/domains/{domain}/applications/{voice_application}/dnids/{dnid}

Or

PATCH /customers/{customer-id}/domains/{domain}/dnids/{dnid}

You may update an existing DNID by either changing the destination matcher (with a new source and compatibility flags, or regular expression), changing the application it is bound to, or enabling and disabling the DNID.

Property	Type	Description
active	Boolean	Set to false to disable the DNID so it will not match against calls, or set to true to re-enable it.
source	String	Set to change the DNID matcher, as per the existing or new compatibility flags.
prefix	Boolean	Set to true to parse the source field as a prefix match.
expression	Boolean	Set to true to parse the source field as a glob expression.
asteriskCompatible	Boolean	Set to true to parse the source field as an Asterisk dial plan extension.
dnid	String	Set the DNID to a regular expression matcher.
application	any	Change the voice application that is bound to this DNID. The application may be specified as either the application's UUID, name, or by providing the full application model object.

Delete a DNID

DELETE /customers/{customer-id}/domains/{domain}/applications/{voice_application}/dnids/{dnid}

Additional Endpoints

The above endpoints may also be accessed via the following canonical endpoint URLs:

GET /domains/{domain}/dnids[/{dnid}]

POST /domains/{domain}/applications/{voice_application}/dnids

PATCH /domains/{domain}/dnids/{dnid}

DELETE /domains/{domain}/dnids/{dnid}

info

As a BEST PRACTICE, we recommend using fully abbreviated canonical URLs (the first option) when developing server side operations. When working with front-end applications, use the shorter notation, to prevent leakage of potentially private or restricted information.