Devices

URI

  • v1/accounts/{account_id}/devices

Property

Description

Validation

Modifiable

name

A friendly name

 

yes

sip

The #SIP Parameters

object

yes

caller_id

The #Caller ID Parameters

object

yes

caller_id_options

The #Caller ID Option Parameters

object

yes

media

The #Media Parameters

object

yes

ringtones

#Ringtone Parameters for distinctive ring

object

yes

owner_id

The ID of the owner (user) of this device

 

yes

 

Verb

Accepted

Returned

Description

GET

 

id, owner

Fetches a summary of devices

PUT

ANY

ALL

Creates a new device

 

  • Normal Response Code(s): 200
  • Error Response Code(s): 400, 401, 415, 500, 503, 504

 

You Send Us:

We Reply With: 

 

{

   "data":{

      "name":"Joe's Office Phone",

      "sip":{

         "realm":"customer",

         "method":"password",

         "username":"user_1234",

         "password":"1234"

      },

      "caller_id":{

         "external":{

            "number":"6491234567"

         }

      },

      "owner_id": "4152ed2b42"

   }

}

 

 

{

   "auth_token":"abc123",

   "status":"success",

   "data":[

      {

         "id":"xyz987",

         "name":"Joe's Office Phone"

      }

   ]

}

 

 

   

 

URI

  • v1/accounts/{account_id}/devices/{device_id}

Property

Description

Validation

Modifiable

name

A friendly name

 

yes

sip

The #SIP Parameters

object

yes

caller_id

The #Caller ID Parameters

array

yes

caller_id_options

The #Caller ID Option Parameters

object

yes

media

The #Media Parameters

object

yes

ringtones

#Ringtone Parameters for distinctive ring

object

yes

owner_id

The ID of the owner (user) of this device

 

yes

 

Verb

Accepted

Returned

Description

GET

 

ALL

Fetch the details of a device

POST

ANY

ALL

Update the parameters of a device

DELETE

 

 

Delete a device

  • Normal Response Code(s): 200, 201
  • Error Response Code(s): 400, 401, 404, 415, 500, 503, 504

Property

Description

Validation

Modifiable

realm

the SIP authentication realm

 

yes

method

Authentication method to identify the endpoint

"password" | "ip"

yes

username

SIP authentication username

 

yes

password

SIP authentication password

 

yes

invite_format

The format of the request URI on SIP Invite

["username"|"npan"|"1npan"|"e164"|"route"]

yes

custom_sip_headers

A JSON object where the properties represent SIP headers, and the attributes the value

 

yes

ip The IP address of the endpoint IPv4 address W.X.Y.Z yes

Property

Description

Validation

Modifiable

name

The name to provide as the caller id

 

yes

number

The number to provide as the caller id

 

yes

The property names of the caller-id objects represent the caller-id type. The 'internal' and 'external' callerid will be use when appropriate if no 'caller_id_options.type' overrides the type. When overridden any arbitrary value may be supplied. When caller-id is searched for it will begin by looking for a matching caller-id type on the definition that authenticated the call (in this case the device). It will then search for a matching type on the 'owner' definition, and last on the account definition. If the type of caller-id that is being searched for has not been located then the account caller-id will be rescanned for a match on the type of 'default'.

Property

Description

Validation

Modifiable

reformat

A regular expression that if matched internal caller id numbers are replaced by

 

yes

Caller-id option parameters are hierarchical following the same hunt order as caller-id parameters.

You need to escape backslashes in literal strings with an additional backslash in the regular expressions.

If the caller-id option "reformat" has multiple matching groups, then the group that creates the largest number of characters will be used.

Property

Description

Validation

Modifiable

progress_timeout

Time (seconds) to wait for media

 

yes

ignore_early_media

Do not pass early media from the callee to the caller

boolean

yes

bypass_media

When true the media will not flow through the switch

boolean

yes

codecs

A list of codecs this device can use, if empty it can use all available

array

yes

Property

Description

Validation

Modifiable

internal

The string to provide to the device via Alert-Info if the call originated on-net

 

yes

external

The string to provide to the device via Alert-Info if the call originated off-net

 

yes

  

The terms on-net and off-net are defined as follows:

  • on-net: A call that is originated by a endpoint defined within an account, such as a device
  • off-net: A call that is originated by an endpoint with no authorization or defined on a global level, such as a carrier resource

Property

Description

Validation

Modifiable

id

The device ID that should be run

required

yes

timeout

Maximum time to attempt to ring the device, defaults to 20 seconds

 

yes

can_call_self

When set to true if the caller is also the device it will process the call normally, by default it skips to the next node

boolean

yes

Example

{
   "module":"device",
   "data": {
      "id": "xyz987",
      "timeout": 30,
      "can_call_self": true
   },
   "children": {}
}

Property

Description

Validation

Modifiable

device_id

The device ID

 

no

registered

Status of the registration of the device

boolean

no

  • status, a read-only subresource of Device, lists the devices associated to the account and their status.
  • Currently only registration status is supported.
 
v1/accounts/{account_id}/devices/status

List all devices for an account

Method GET
URI v1/accounts/{account_id}/devices
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body
{
   "auth_token":"abc123",
   "status":"success",
   "data":[
      {
         "id":"xyz987",
         "name":"Joe's Office Phone"
      }
   ]
}
Response Headers 200 OK
Content-Type: application/json

 

Method PUT
URI v1/accounts/{account_id}/devices
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
{
   "data":{
      "name":"Joe's Office Phone",
      "sip":{
         "realm":"customer",
         "method":"password",
         "username":"user_1234",
         "password":"1234",
         "invite_format":"username"
         "custom_sip_headers": {"X-Example": "my-custom-sip-value"}
      },
      "caller_id":{
         "external":{
            "number":"6491234567"
         }
      },
      "media":{
         "progress_timeout":6,
         "ignore_early_mediat":false,
         "bypass_media":false,
         "codecs":[
            "PCMU"
         ]
      },
      "ringtones": {
         "external": "<http://localhost/ >;info=External",
         "internal": "<http://localhost/ >;info=Internal",
      },
      "owner_id": "4152ed2b42"
   }
}
Response Body  
Response Headers 201 OK
Location: v1/accounts/{account_id}/devices/{device_id}
Method GET
URI v1/accounts/{account_id}/devices/{device_id}
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body  
{
   "auth_token":"abc123",
   "status":"success",
   "data":{
      "name":"Joe's Office Phone",
      "sip":{
         "realm":"customer",
         "method":"password",
         "username":"user_1234",
         "password":"1234",
         "invite_format":"username",
         "custom_sip_headers": {"X-Example": "my-custom-sip-value"}
      },
      "caller_id":{
         "external":{
            "number":"6491234567"
         }
      },
      "media":{
         "progress_timeout":6,
         "ignore_early_media":false,
         "bypass_media":false,
         "codecs":[
            "PCMU"
         ]
      },
      "ringtones": {
         "external": "<http://localhost/ >;info=External",
         "internal": "<http://localhost/ >;info=Internal",
      },
      "owner_id": "4152ed2b42"
   }
}
Response Headers 201 OK
Location: v1/accounts/{account_id}/devices/{device_id}
Method POST
URI v1/accounts/{account_id}/devices/{device_id}
Request Headers X-Auth-Token: abc123
Accept: application/json
Content-Type: application/json
Request Body  
{
   "data":{
      "name":"Joe's Office Phone",
      "sip":{
         "realm":"customer",
         "method":"password",
         "username":"user_1234",
         "password":"1234",
         "invite_format":"username",
         "custom_sip_headers": {"X-Example": "my-custom-sip-value"}
      },
      "caller_id":{
         "external":{
            "number":"6491234567"
         },
         "internal":{
            "number":"1000",
            "name":"Joe"
         }
      },
      "media":{
         "progress_timeout":6,
         "ignore_early_mediat":false,
         "bypass_media":false,
         "codecs":[
            "PCMU"
         ]
      },
      "ringtones": {
         "external": "<http://localhost/ >;info=External",
         "internal": "<http://localhost/ >;info=Internal",
      },
      "owner_id": "4152ed2b42"
   }
}
Response Body  
{
   "auth_token":"abc123",
   "status":"success",
   "data":{
      "name":"Joe's Office Phone",
      "sip":{
         "realm":"customer",
         "method":"password",
         "username":"user_1234",
         "password":"1234",
         "invite_format":"username",
         "custom_sip_headers": {"X-Example": "my-custom-sip-value"}
      },
      "caller_id":{
         "external":{
            "number":"6491234567"
         },
         "internal":{
            "number":"1000",
            "name":"Joe"
         }
      },
      "media":{
         "progress_timeout":6,
         "ignore_early_mediat":false,
         "bypass_media":false,
         "codecs":[
            "PCMU"
         ]
      },
      "ringtones": {
         "external": "<http://localhost/ >;info=External",
         "internal": "<http://localhost/ >;info=Internal",
      },
      "owner_id": "4152ed2b42"
   }
}
Response Headers 200 OK
Method DELETE
URI v1/accounts/{account_id}/devices/{device_id}
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body
{
   "auth_token":"abc123",
   "status":"success",
   "data":[]
}
Response Headers 200 OK
Method GET
URI v1/accounts/{account_id}/devices/status
Request Headers X-Auth-Token: abc123
Accept: application/json
Request Body  
Response Body
{
   "auth_token":"abc123",
   "status":"success",
   "data":[
      {
         "device_id":"xyz987",
         "registered": true
      }
   ]
}
Response Headers 200 OK

The attached spreadsheet shows an example of how to create a landline device. Use the curl command in column L to create the device.

   

AttachmentSize
device_template.xls 27.5 KB