Users API

In the Users API, you can assign multiple devices to a user or put the user in a callflow, and all devices will ring.

API calls

Click on each call to view the endpoint, method, and request example.

Parameters

The table shows the possible parameters available for users requests.

Key Description Type Options/Min/Max/Default
first_name Required. The first name of the user. string (1..128)
last_name Required. The last name of the user. string (1..128)
call_forward.direct_calls_only Determines if the calls that are not directly sent to the device should be forwarded. boolean The default is false.
call_forward.enabled Determines if call forwarding should be used. boolean The default is false.
call_forward.failover Enables the call-forwarding parameters if the device is offline. boolean
call_forward.ignore_early_media The option to determine if early media from the call forwarded number should ignored. boolean The default is true.
call_forward.keep_caller_id Determines if the caller id is kept when the call is forwarded, if not the devices caller ID is used. boolean The default is true.
call_forward.number The number to forward calls to. string (0..35)
call_forward.require_keypress Determines if the callee is prompted to press 1 to accept the call. boolean The default is true.
call_forward.substitute Determines if the call forwarding replaces the device. boolean The default is true.
call_forward The device call forward parameters. object
call_recording Endpoint recording settings #/definitions/call_recording
call_restriction Device level call restrictions for each available number classification. object
call_waiting Parameters for server-side call waiting. #/definitions/call_waiting
caller_id The device caller ID parameters. #/definitions/caller_id
caller_id_options.outbound_privacy Determines what appears as caller id for offnet outbound calls. string full: hides name and number,
caller_id_options Custom properties for configuring caller ID. object
contact_list.exclude Indicates if the device should be excluded from the contact list. boolean
contact_list Contact list parameters. object
dial_plan A list of rules used to modify dialed numbers. #/definitions/dialplans
directories Provides the mappings for what directory the user is a part of (the key), and what callflow (the value) to invoke if the user is selected by the caller. object
do_not_disturb.enabled Is do-not-disturb (DND) enabled for this user? boolean
do_not_disturb The DND parameters. object
email The email of the user string (3..254)
enabled Determines if the user is currently enabled. boolean The default is true.
feature_level The user level for assigning feature sets string
flags.[] string
flags Flags set by external applications array, string
formatters Schema for request formatters object
hotdesk.enabled Determines if the user has hotdesking enabled boolean
hotdesk.id The users hotdesk id string (0..15)
hotdesk.keep_logged_in_elsewhere Determines if user should be able to login to multiple phones simultaneously. boolean
hotdesk.pin The users hotdesk pin number. string (4..15)
hotdesk.require_pin Determines if user requires a pin to change the hotdesk state. boolean
hotdesk The user hotdesk parameters. object
language The language for this user. string
media Configure audio/video/etc media options for this user. #/definitions/endpoint.media
metaflows The device metaflow parameters. #/definitions/metaflows
music_on_hold.media_id The ID of a media object that should be used as the music on hold. string (0..128)
music_on_hold The music on hold parameters used if not a property of the device owner. object
password The GUI login password. string
presence_id Static presence ID (used instead of SIP username). string
priv_level The privilege level of the user. string user, admin. The default is user
profile User's profile data #/definitions/profile
pronounced_name.media_id The ID of a media object that should be used as the music on hold. string (0..128)
pronounced_name Name pronounced by user to introduce himself to conference members. object
require_password_update UI flag that the user should update their password. boolean
ringtones.external The alert info SIP header added when the call is from internal sources. string (0..256)
ringtones.internal The alert info SIP header added when the call is from external sources. string( 0..256)
ringtones Ringtone Parameters object
timezone The user's timezone. string
username The GUI login username. string (1..256) alpha-numeric, dashes, at symbol, periods, plusses, and underscores allowed.
verified Determines if the user has been verified. boolean
vm_to_email_enabled Determines if the user would like voicemails emailed to them. boolean The default is true.
voicemail.notify.callback Schema for a callback options #/definitions/notify.callback
voicemail.notify object
voicemail object

Call recording endpoint parameters

Key Description Type
any Settings for any calls to/from the endpoint. #/definitions/call_recording.source
inbound Settings for inbound calls to the endpoint. #/definitions/call_recording.source
outbound Settings for outbound calls from the endpoint . #/definitions/call_recording.source

Call recording parameters

Key Description Type
enabled Indicates if recording is enabled. boolean
format Indicates the format to store the recording on disk. string (mp3, wav)
record_min_sec The minimum length, in seconds, for the recording to be considered successful. Otherwise it is deleted integer
record_on_answer Indicates if recording should start on answer. boolean
record_on_bridge Indicates if recording should start on bridge. boolean
record_sample_rate Specifies the sampling rate to use on the recording. integer
time_limit Time limit, in seconds, for the recording. integer
url The URL to use when sending the recording for storage. string

Call recording source settings

Key Description Type
any settings for calls from any network #/definitions/call_recording.parameters
offnet settings for calls from offnet networks #/definitions/call_recording.parameters
onnet settings for calls from onnet networks #/definitions/call_recording.parameters

Call waiting parameters

Key Description Type
`enabled. Determines if server side call waiting is enabled/disabled boolean

Caller ID parameters

Key Description Type
asserted.name The asserted identity name for the object type . string(0..35)
asserted.number The asserted identity number for the object type. string(0..35)
asserted.realm The asserted identity realm for the object type. string()
asserted Used to convey the proven identity of the originator of a request within a trusted network. object
emergency.name The caller ID name for the object type. string(0..35)
emergency.number The caller ID number for the object type. string(0..35)
emergency The caller ID used when a resource is flagged as 'emergency'. object
external.name The caller ID name for the object type. string(0..35)
external.number The caller ID number for the object type. string(0..35)
external The default caller ID used when dialing external numbers. object
internal.name The caller ID name for the object type. string(0..35)
internal.number The caller ID number for the object type. string(0..35)
internal The default caller ID used when dialing internal extensions. object

Dialplan parameters

Permit local dialing by converting the dialed number to a routable form

Key Description Type
system.[] string
system List of system dial plans array, string

Endpoint media settings

Schema for endpoint media options.

Key Description Type
audio.codecs.[] Specific audio codecs. string
audio.codecs A list of audio codecs the endpoint supports. array, string OPUS, CELT@32000h, G7221@32000h, G7221@16000h, G722, speex@32000h, speex@16000h, PCMU, PCMA,G729,GSM, CELT@48000h,CELT@64000h, G722_16, G722_32, CELT_48, CELT_64, Speex, speex
audio The audio media parameters object
bypass_media Default bypass media mode. boolean
encryption.enforce_security Is encryption enabled? boolean
encryption.methods.[] string('zrtp'
encryption.methods Supported Encryption Types array(string('zrtp'
encryption Encryption Parameters object
fax_option Is T.38 Supported? boolean
ignore_early_media timeout to apply to the endpoint (seconds) integer
video.codecs.[] string('H261'
video.codecs A list of video codecs the endpoint supports array(string('H261'
`video The video media parameters object

Formatter parameters

Key Description Type
^[[:alnum:]_]+$ Key to match in the route request JSON. array(#/definitions/formatters.format_options)

Formatters format options parameters

Key Description Type
direction Only apply the formatter on the relevant request direction string('inbound'
match_invite_format Applicable on fields with SIP URIs. Will format the username portion to match the invite format of the outbound request. boolean
prefix Prepends value against the result of a successful regex match. string
regex Matches against the value, with optional capture group. string
strip If set to true, the field will be stripped from the payload. boolean
suffix Appends value against the result of a successful regex match. string
value Replaces the current value with the static value defined. string

Metaflow parameters

Key Description Type
children./.+/ A metaflow node defines a module to execute, data to provide to that module, and one or more children to branch to. #/definitions/metaflow
children Children metaflows. object
data The data/arguments of the metaflow module. object
`module. Required. The name of the metaflow module to execute at this node string(1..64) true

Metaflow actions

Key Description Type
binding_digit Indicates which DTMF will trigger the collection and analysis of the subsequent DTMF sequence. The default is *. string('1' , '2' , '3', '4' , '5' , '6' , '7' , '8' , '9' , '0' , '*' , '#')
digit_timeout Specifies how long to wait between DTMF presses before processing the collected sequence (milliseconds). integer() false
listen_on Defines which leg(s) of the call to listen for DTMF. string both, self, peer
numbers./^[0-9]+$/ A metaflow node defines a module to execute, data to provide to that module, and one or more children to branch to. #/definitions/metaflow
numbers A list of static numbers with their flows. object
patterns./.+/ A metaflow node defines a module to execute, data to provide to that module, and one or more children to branch to. #/definitions/metaflow
patterns A list of patterns with their flows. object

Callback parameters

Key Description Type
`attempts. How many attempts without answer will system do. integer
disabled Determines if the system will call to callback number. boolean
interval_s How long will system wait between call back notification attempts. integer
number Number for callback notifications about new messages. string
schedule Schedules interval between callbacks. array(integer())
`timeout_s. How long will system wait for answer to callback integer

Profile parameters

Key Description Type
addresses.[].address To specify the address. string
addresses.[].types To specify types of the address. array
addresses To specify the components of the addresses. array(object)
assistant To specify the user's assistant. string
birthday To specify the birth date of the user. string
nicknames.[] stringfalse
note To specify supplemental information or a comment that is associated with the user. string
role To specify the function or part played in a particular situation by the user. string
sort-string To specify the family name or given name text to be used for national-language-specific sorting of the FN and N types. string
title To specify the position or job of the user string

Get users

Returns a list of users on the account.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/users

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "email": "user1@account_realm.com",
            "features": [
                "caller_id",
                "vm_to_email"
            ],
            "first_name": "User",
            "id": "{USER_ID}",
            "last_name": "One",
            "priv_level": "admin",
            "timezone": "America/Los_Angeles",
            "username": "user1@account_realm.com"
        },
        {
            "email": "user2@account_realm.com",
            "features": [
                "caller_id",
                "vm_to_email"
            ],
            "first_name": "User",
            "id": "{USER_ID}",
            "last_name": "Two",
            "priv_level": "user",
            "timezone": "America/Los_Angeles",
            "username": "user2@account_realm.com"
        }
    ],
    "page_size": 2,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Create a user

Creates a user.

Method and endpoint

  PUT /v2/accounts/{ACCOUNT_ID}/users

Request

  curl -v -X PUT \
      -H "X-Auth-Token: {AUTH_TOKEN} \
      -H "Content-Type: application/json" \
      -d '{"data":{"first_name":"User", "last_name":"Three"}}' \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {
          "call_restriction": {},
          "caller_id": {},
          "contact_list": {},
          "dial_plan": {},
          "enabled": true,
          "first_name": "User",
          "hotdesk": {
              "enabled": false,
              "keep_logged_in_elsewhere": false,
              "require_pin": false
          },
          "id": "{USER_ID}",
          "last_name": "Three",
          "media": {
              "audio": {
                  "codecs": [
                      "PCMU"
                  ]
              },
              "encryption": {
                  "enforce_security": false,
                  "methods": []
              },
              "video": {
                  "codecs": []
              }
          },
          "music_on_hold": {},
          "priv_level": "user",
          "profile": {},
          "require_password_update": false,
          "ringtones": {},
          "verified": false,
          "vm_to_email_enabled": true
      },
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }

Remove a user

Returns the current JSON object of the now-deleted user.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {
          "call_restriction": {},
          "caller_id": {},
          "contact_list": {},
          "dial_plan": {},
          "enabled": false,
          "first_name": "User",
          "hotdesk": {
              "enabled": false,
              "keep_logged_in_elsewhere": false,
              "require_pin": false
          },
          "id": "{USER_ID}",
          "last_name": "Three",
          "media": {
              "audio": {
                  "codecs": [
                      "PCMU"
                  ]
              },
              "encryption": {
                  "enforce_security": false,
                  "methods": []
              },
              "video": {
                  "codecs": []
              }
          },
          "music_on_hold": {},
          "priv_level": "user",
          "profile": {},
          "require_password_update": false,
          "ringtones": {},
          "verified": false,
          "vm_to_email_enabled": true
      },
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }

Get user

Returns details of a specific user.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN} \
      http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {
          "call_restriction": {},
          "caller_id": {},
          "contact_list": {},
          "dial_plan": {},
          "enabled": true,
          "first_name": "User",
          "hotdesk": {
              "enabled": false,
              "keep_logged_in_elsewhere": false,
              "require_pin": false
          },
          "id": "{USER_ID}",
          "last_name": "Three",
          "media": {
              "audio": {
                  "codecs": [
                      "PCMU"
                  ]
              },
              "encryption": {
                  "enforce_security": false,
                  "methods": []
              },
              "video": {
                  "codecs": []
              }
          },
          "music_on_hold": {},
          "priv_level": "user",
          "profile": {},
          "require_password_update": false,
          "ringtones": {},
          "verified": false,
          "vm_to_email_enabled": true
      },
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }

Patch a user document

Partially updates user details.

Method and endpoint

PATCH /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Request curl -v -X PATCH \ -H "X-Auth-Token: {AUTH_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"data":{"enabled":false}}' \ http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {
          "call_restriction": {},
          "caller_id": {},
          "contact_list": {},
          "dial_plan": {},
          "enabled": false,
          "first_name": "User",
          "hotdesk": {
              "enabled": false,
              "keep_logged_in_elsewhere": false,
              "require_pin": false
          },
          "id": "{USER_ID}",
          "last_name": "Three",
          "media": {
              "audio": {
                  "codecs": [
                      "PCMU"
                  ]
              },
              "encryption": {
                  "enforce_security": false,
                  "methods": []
              },
              "video": {
                  "codecs": []
              }
          },
          "music_on_hold": {},
          "priv_level": "user",
          "profile": {},
          "require_password_update": false,
          "ringtones": {},
          "verified": false,
          "vm_to_email_enabled": true
      },
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }

Change a user document

Changes the user details. You must post the full user document in the request body.

Method and endpoint

  POST /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"first_name":"User","last_name":"Three","call_restriction":{},"caller_id":{},"contact_list":{},"dial_plan":{},"enabled":false,"hotdesk":{"enabled":false,"keep_logged_in_elsewhere":false,"require_pin":false},"media":{"audio":{"codecs":["PCMU"]},"encryption":{"enforce_security":false,"methods":[]},"video":{"codecs":[]}},"music_on_hold":{},"priv_level":"user","profile":{},"require_password_update":false,"ringtones":{},"verified":false,"vm_to_email_enabled":true}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "call_restriction": {},
        "caller_id": {},
        "contact_list": {},
        "dial_plan": {},
        "enabled": false,
        "first_name": "User",
        "hotdesk": {
            "enabled": false,
            "keep_logged_in_elsewhere": false,
            "require_pin": false
        },
        "id": "{USER_ID}",
        "last_name": "Three",
        "media": {
            "audio": {
                "codecs": [
                    "PCMU"
                ]
            },
            "encryption": {
                "enforce_security": false,
                "methods": []
            },
            "video": {
                "codecs": []
            }
        },
        "music_on_hold": {},
        "priv_level": "user",
        "profile": {},
        "require_password_update": false,
        "ringtones": {},
        "verified": false,
        "vm_to_email_enabled": true
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Get or create a vCard

vCard is a file format typically used in emails as a form of business card.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/vcard

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    -H "Accept: text/x-vcard"
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/vcard

Response

  BEGIN:VCARD
  VERSION:3.0
  FN:User Three
  N:Three;User
  END:VCARD

Remove a user photo

Removes the user photo from the account.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN} \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

Get photo

Returns the user photo.

NOTE: Set the Accept header to either application/base64 or application/octet-stream to retrieve the picture's contents. If the result is successful, you can pipe the response into a file.

Method and endpoint

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

Request

curl -v -X GET \
    -H "Accept: application/base64" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo
[binary data]

Create or change photo

Creates or updates a user photo. Use application/octet-stream as the content type.

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

Request

curl -v -X POST \
    -H "Content-Type: application/octet-stream" \
    --data-binary @/path/to/image.jpg \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/photo

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": {},
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }