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:

GET /available_did_numbers - For Fetching DID Numbers
POST /available_did_numbers - For Creating a DID Number
DELETE /available_did_numbers/{id} - For Deleting a DID Number
PATCH /available_did_numbers/{id} - For Updating a DID Number

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.