API for Users

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.

Get users
Create a user
Remove a user
Get user
Patch a user document
Change a user document
Get or create a vCard
Remove a user photo
Get photo
Create or change photo

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 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"
  }