Phone Numbers API

This API allows you to manage numbers within an account.

 

  • Search for available numbers that can be purchased/acquired.
  • v1/phone_numbers?prefix=649&quantity=5

{
"auth_token":"{auth_id}",
"status":"success",
"request_id":"4a977a557c02899b63a3e729aec92510",
"revision":"undefined",
"data":[
"+6496060842",
"+6497779311",
"+6494894608",
"+6492818004",
"+6499982126"
]
}

Activate a new number which will assign it to the given account and provision it via the upstream carrier.

  • v1/accounts/{account_id}/phone_numbers/6496060842/activate

Sample Request

{

   "data":{

   }

}

 Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"91a4ea35bb7f92a4f7f517fc5c41ead8",

   "revision":"undefined",

   "data":{

   }

}

 

  • The data payload is shown empty in this example, however you can set the numbers metadata during creation by including it as you see in the Update Numbers (POST) example.

Reserve a number which will allow the account to control the number and expose it to sub-accounts but return to the reserving account when released. Reserved numbers allow parent accounts to acquire and assign a number which will automatically return to the parent when the assigned sub account is deleted or releases the number (verses "activated" numbers which always return to the available pool or are deleted from the system).

  • v1/accounts/{account_id}/phone_numbers/6496060842/reserve

Sample Request

{

   "data":{

   }

}

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"91a4ea35bb7f92a4f7f517fc5c41ead8",

   "revision":"undefined",

   "data":{

   }

}

 

Numbers can be reserved recursively, for example suppose:

  • Account-A reserves a new number
  • SubAccount-B reserves the number from Account-A
  • SubSubAccount-C activates the number reserved by SubAccount-B

Account-A and SubAccount-B will both retain tracking information regarding the number assignment as well as ultimate control over the number. When SubSubAccount-C releases the number it will return to SubAccount-B as a reserved number. When SubAccount-B releases the number it will return to Account-A as a reserved number. Finally when Account-A releases the number it will be put back into the available pool or deleted depending on the system settings.

Created a special type of restricted number that acts as a placeholder for a porting number.

  • v1/accounts/{account_id}/phone_numbers/6496060842/port

Sample Request

{

   "data":{

      "port":{

         "service_provider":"SPARK",

         "main_number":"+6468867900",

         "billing_name":"Conversant",

         "billing_account_id":"00001234",

         "billing_postal_code":"0123",

         "billing_street_address":"2 Fleet St",

         "billing_extended_address":"DEVONPORT",

         "billing_locality":"Auckland",

         "billing_region":"Auckland",

         "email":"admin@conversant.co.nz"

      }

   }

}

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"91a4ea35bb7f92a4f7f517fc5c41ead8",

   "revision":"undefined",

   "data":{

      "port":{

         "service_provider":"SPARK",

         "main_number":"+14158867900",

         "billing_name":"Conversant",

         "billing_account_id":"00001234",

         "billing_postal_code":"0123",

         "billing_street_address":"2 Fleet St",

         "billing_extended_address":"DEVONPORT",

         "billing_locality":"Auckland",

         "billing_region":"Auckland",

         "email":"admin@conversant.co.nz"

      }

   }

}

  • If the metadata is provided the system will attempt to port the number automatically.

Created a special type of restricted number that acts as a placeholder for a porting number.

  • v1/accounts/{account_id}/phone_numbers/6496060842/docs

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"a65a5160835de1e418961b0c329c4c51",

   "revision":"undefined",

   "data":{

      "my_bill.pdf":{

         "content_type":"appplication/pdf",

         "revpos":3,

         "digest":"md5-xeRbdv03RApfhTSNQeo/KA==",

         "length":578,

         "stub":true

      },

      "loa.pdf":{

         "content_type":"appplication/pdf",

         "revpos":3,

         "digest":"md5-xeRbdv03RApfhTSNQeo/KA==",

         "length":578,

         "stub":true

      }

   }

Created a special type of restricted number that acts as a placeholder for a porting number.

  • v1/accounts/{account_id}/phone_numbers/6496060842/docs/loa.pdf

Sample Request

data:application/pdf;base64,JVBERi0xLjINJ ...

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"39c88783cd34734ad2476ba21705f3ca",

   "revision":"undefined",

   "data":{

      "id":"+6496060842",

      "rev":"3-88349f302445eac9abff1f6aacfd6b3b"

   }

}

  • If an upload of the same name already exists this will replace it.
  • Be sure and URL encode your pdf name in the URL.

 

This is a restricted API to add a number without attempting to provision it with the carrier. Used primarily by system admins and accounts that bring their own carriers.

  • v1/accounts/{account_id}/phone_numbers/6494894608

    

Sample Request

{

   "data":{

   }

}

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"bd205c080f70cfdc76c0474f3f55dddc",

   "revision":"undefined",

   "data":{

   }

}

      
  • The data payload is shown empty in this example, however you can set the numbers metadata during creation by including it as you see in the Update Numbers (POST) example.

 

Get a list of all numbers associated with an account.

  • v1/accounts/{account_id}/phone_numbers

Sample Response

{

         "auth_token":"{auth_id}",

         "status":"success",

         "request_id":"67c892634564dcfe960c4c49bf54785a",

         "revision":"132-0eabfa5b420",

         "data":{

                 "numbers": {

                          "+6496060842":{

                          "state":"in_service",

                          "features":[],

                          "on_subaccount":false,

                          "assigned_to":"{account_id}"

                          },

                 "+6497779311":{

                          "state":"in_service",

                          "features":[

                          "cnam",

                          "inbound_cnam"

                          ],

                          "on_subaccount":false,

                          "assigned_to":"{account_id}"

                },

                 "+6494894608":{

                          "state":"in_service",

                          "features":[

                          "outbound_cnam",

                          "failover"

                          ],

                          "on_subaccount":false,

                          "assigned_to":"{account_id}"

                 }

                 },

                 "casquade_quantity": 15

   }

}

Retrieve all the metadata regarding a number.

  • v1/accounts/{account_id}/phone_numbers/6494894608

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"d883ab5513d02db5909353a7ce121ced",

   "revision":"undefined",

   "data":{

      "failover":{

         "e164":"+6496060842",

         "sip":"sip:sales@conversant.co.nz"

      },

      "cnam":{

         "display_name":"Conversant"

      }

   }

}

Update the numbers metadata.

  • v1/accounts/{account_id}/phone_numbers/6494894608

Sample Request

{

   "data":{

      "failover":{

         "e164":"+6496060842",

         "sip":"sip:sales@conversant.co.nz"

      },

      "cnam":{

         "display_name":"Conversant"

      }

   }

}

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"618c7ca6a82a3c0cb3eb2ba94171203a",

   "revision":"undefined",

   "data":{

      "failover":{

         "e164":"+6496060842",

         "sip":"sip:sales@conversant.co.nz"

      },

      "cnam":{

         "display_name":"Conversant"

      }

   }

}

Release a number back into the system and/or delete it depending on the system settings.

  • v1/accounts/{account_id}/phone_numbers/6498675309

Sample Request

{

   "data":{

   }

}

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"6cd8933ab69bdd1e9907977ff45704e5",

   "revision":"undefined",

   "data":{

   }

}

Classifiers are used internally for billing and to restrict users/devices.

  • v1/accounts/{account_id}/phone_numbers/classifiers

 

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"4c84806b599dc9cb1f194662da779bbb",

   "revision":"undefined",

   "data":{

       "international": {

           "regex": "^011\\d*$|^00\\d*$",

           "friendly_name": "International"

       },

       "unknown": {

           "regex": "^.*$",

           "friendly_name": "Unknown"

       },

       "nz_mobile": {

           "regex": "^\\+642[0-9]{7,}$",

           "friendly_name": "NZ mobile",

           "pretty_print": "SSS(0##) *"

       }

   }

}

Retrieve the account id of the number (which account_id it is assigned to).

  • v1/accounts/{account_id}/phone_numbers/6496060842/identify

Sample Response

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"91a4ea35bb7f92a4f7f517fc5c41ead8",

   "revision":"undefined",

   "data":{

                 "account_id": "an_account_id",

                 "number": "+6496060842"

   }

}

Same as the PUT, POST, DELETE operations (for multiple numbers).

  • v1/accounts/{account_id}/phone_numbers/collection
  • You must provide the numbers you want to create, update or delete.

Sample Request

{

   "data":{

                 "numbers": [

                          "+6496060841",

                          "+6496060842",

                          "+6496060843"

                 ]

   }

}

Sample Response

{

   "data":{

                 "success": {

                          "+6496060841": {

                                   "used_by": "",

                "id": "+6496060841"

                          },

                          "+6496060842": {

                                   "used_by": "",

                "id": "+6496060842"

                          }

                 },

                 "error": {

            "+6496060843": {

                "reason": "invalid_state_transition"

            }

        }

   }

}

 

You can also assign numbers to an account via bulk api:

  • v1/accounts/{account_id}/phone_numbers/collection/activate
  • Same request data as the others bulk apis.

SUB_PARAMETERS

These are provider specific properties that are added to enable some feature (via a provider module).  See below for sub-parameters

{

   "port":{

      "service_provider":"SPARK",

      "main_number":"+6468867900",

      "billing_name":"Conversant",

      "billing_account_id":"00001234",

      "billing_postal_code":"94105",

      "billing_street_address":"2 Fleet St",

      "billing_extended_address":"DEVONPORT",

      "billing_locality":"Auckland",

      "billing_region":"Auckland",

      "email":"admin@conversant.co.nz"

   },

   "failover":{

      "e164":"+6496060842",

      "sip":"sip:sales@conversant.co.nz"

   },

   "cnam":{

      "display_name":"Conversant",

      "inbound_lookup":true

   }

}

Sub-Parameters

port

port

service_provider

This is name of the company that current controls the number, such as SPARK, and is referred to as the losing carrier.

main_number

This property needs to be set to the number the losing carrier has on file as the billing number (BTN), check your bill for this information.

billing_name

This property needs to be set to the account name the losing carrier has on file.

billing_account_id

This property should be set to any account id the losing carrier has on file, check your bill for this information.

billing_postal_code

This property needs to be set to the postal code the losing carrier has on file.

billing_street_address

This property needs to be set to the street address the losing carrier has on file.

billing_extended_address

This property needs to be set to any suite or apartment number the losing carrier might have on file.

billing_locality

This property needs to be set to the locality the losing carrier has on file.

billing_region

This property needs to be set to the region the losing carrier has on file.

email

This is an option property regarding where porting emails should be sent, if it is not present the system will us the email address of the user submitting the request.

   "port":{

      "service_provider":"SPARK",

      "main_number":"+6468867900",

      "billing_name":"Conversant",

      "billing_account_id":"00001234",

      "billing_postal_code":"0123",

      "billing_street_address":"2 Fleet St",

      "billing_extended_address":"DEVONPORT",

      "billing_locality":"Auckland",

      "billing_region":"Auckland",

      "email":"admin@conversant.co.nz"

   }