DID numbers

This endpoint provides the ability to manage DID numbers (referred to as Phone Numbers in the UI) in your customer accounts. Using this endpoint, you can automate the process of provisioning DID numbers from your DID number pool and allocating them to phone.systems™ customer accounts.

Important

DID numbers are unique per Customer. The same number cannot be provisioned twice to the same Customer.

The provisioned DIDs may be disabled when the number has to be temporarily suspended. Disabled numbers remain in the customer accounts and are visible to the end-user. The UI displays the disabled numbers in red. Also, the system rejects inbound calls made to the disabled numbers.

If ‘external_id’ is provided during provisioning, the DID number will be treated as system number. Such numbers can not be modified by the end-user.

Important

Your account may be pre-configured to disallow Customers to add new DID numbers manually.

The following HTTP method(s) are available:

Relationship to other resources:

Name

Resource Type

Relationship Type

Updatable

Description

customer

customers

To-one

No

Parent customer that this available DID number belongs to

Important

Relationships can be used with include and fields parameters if the method supports it.

Creating a DID Number

Use the HTTP POST method to create a new available DID number:

POST

/api/rest/public/operator/available_did_numbers

This method supports Sparse fieldsets and Inclusion of related resources

Attributes:

Attribute

Value

Description

Optional

Controlled via UI

number

Any integer

The number itself. Used for call routing

No

Depends on account settings

external_id

Integer between 0 and 9223372036854775807

Number ID in external system

Yes

No

enabled

“true”, “false”

DID number status

Yes, default is “true”

No

Request and Response examples:

http

POST /api/rest/public/operator/available_did_numbers HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

{
  "data": {
   "type": "available_did_numbers",
   "attributes": {
     "number": "441174090316"
   },
    "relationships": {
      "customer": {
        "data": {
          "id": "123",
          "type": "customers"
        }
      }
    }
  }
}

curl

curl -i -X POST https://api.telecom.center/api/rest/public/operator/available_did_numbers -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"number": "441174090316"}, "relationships": {"customer": {"data": {"id": "123", "type": "customers"}}}, "type": "available_did_numbers"}}' --user username:password

response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "c31a684b-02e1-4311-8f61-34d8dac2758d",
    "type": "available_did_numbers",
    "links": {
      "self": "https://api.telecom.center/api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d"
},
    "attributes": {
      "number": "441174090316",
      "enabled": true
    }
  }
}

Important

Added DID numbers are not yet ready to receive calls. Customers must add these numbers to the call flow configuration in the UI before they form part of the PBX logic.

Fetching DID Numbers

Use the HTTP GET method to retrieve a list of existing available DID numbers:

GET

/api/rest/public/operator/available_did_numbers

This method supports Sorting, Pagination, Sparse fieldsets and Inclusion of related resources

Other supported parameters:

Parameter

Value

Description

filter[id]

Available DID Number ID

Used for filtering results by resource ID

filter[customer.id]

Customer ID

Used for filtering results by Customer ID

filter[number]

A valid DID number

Used for filtering results by number

filter[enabled]

true, false

Used for filtering results by status

http

GET /api/rest/public/operator/available_did_numbers HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

curl

curl -i -X GET https://api.telecom.center/api/rest/public/operator/available_did_numbers -H "Content-Type: application/vnd.api+json" --user username:password

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json


{
 "data": [
   {
     "id": "c31a684b-02e1-4311-8f61-34d8dac2758d",
     "type": "available_did_numbers",
     "links": {
       "self": "https://pbx2-sandbox.in.didww.com/api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d"
   },
     "attributes": {
       "number": "441174090316",
       "enabled": false
     }
   }
 ],
 "meta": {
   "record_count": 1
 },
 "links": {
   "first": "https://api.telecom.center/api/rest/public/operator/available_did_numbers?filter%5Bid%5D=c31a684b-02e1-4311-8f61-34d8dac2758d&page%5Bnumber%5D=1&page%5Bsize%5D=50",
   "last": "https://api.telecom.center/api/rest/public/operator/available_did_numbers?filter%5Bid%5D=c31a684b-02e1-4311-8f61-34d8dac2758d&page%5Bnumber%5D=1&page%5Bsize%5D=50"
 }
}

The response body contains an array of all available DID numbers.

Additionally, an available DID number ID may be included in the request URL to retrieve a single available DID number:

GET

/api/rest/public/operator/available_did_numbers/{id}

Updating a DID Number

Use the HTTP PATCH method to update an existing available DID number:

PATCH

/api/rest/public/operator/available_did_numbers/{id}

This method supports Sparse fieldsets and Inclusion of related resources

Attributes:

Parameter

Value

Description

filter[id]

Available DID Number ID

Used for filtering results by resource ID

filter[customer.id]

Customer ID

Used for filtering results by Customer ID

filter[number]

A valid DID number

Used for filtering results by number

filter[enabled]

true, false

Used for filtering results by status

Other supported parameters:

Parameter

Value

Description

include

“customer”

Used for including linked object details to the response

Request and Response examples:

http

PATCH /api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

{
  "data": {
    "id": "c31a684b-02e1-4311-8f61-34d8dac2758d",
    "type": "available_did_numbers",
    "attributes": {
      "number": "441174090316",
      "enabled": false
    }
  }
}

curl

curl -i -X PATCH https://api.telecom.center/api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"enabled": false, "number": "441174090316"}, "id": "c31a684b-02e1-4311-8f61-34d8dac2758d", "type": "available_did_numbers"}}' --user username:password

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "c31a684b-02e1-4311-8f61-34d8dac2758d",
    "type": "available_did_numbers",
    "links": {
      "self": "https://api.telecom.center/api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d"
},
    "attributes": {
      "number": "441174090316",
      "enabled": false
    }
  }
}

Deleting a DID Number

Use the HTTP DELETE method to delete an available DID number from a customer’s account:

DELETE

/api/rest/public/operator/available_did_numbers/{id}

Important

the linked object (if such object exists) in the call flow configuration will also be deleted.

Request and Response examples:

http

DELETE /api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

curl

curl -i -X DELETE https://api.telecom.center/api/rest/public/operator/available_did_numbers/c31a684b-02e1-4311-8f61-34d8dac2758d -H "Content-Type: application/vnd.api+json" --user username:password

response

HTTP/2 204 No Content
Content-Type: application/vnd.api+json

The HTTP status code 204 will be the response after a successful deletion of an available DID number with an empty response body.