Employee

Interact with employees, set do not disturb, send message and list all employees.

Properties
Get all employees
Get a single employee by ID
Update an employee by ID
Returns the currently authenticated employee
Update the currently authenticated employee
Send a text message to an employee

Employee properties

Name	Description
admin	{"admin":true} Whether this employee is a company administrator.
cloak_reception	If present, the phone number associated with this reception is used as the from-number when this employee places calls. See the Reception documentation.
company_id	{"company_id":1} Company ID.
dnd_timeout_at	{"dnd_timeout_at":"2014-10-10T02:48:48+02:00"} If and when the current `do_not_disturb` setting expires. ISO8601 timestamp If do not disturb is enabled, a timestamp indicates when it will be disabled. If do not disturb is already disabled, this has no effect. null If timeout is not set, do not disturb does not expire and must be switched off manually through the API or the web interface.
do_not_disturb	{"do_not_disturb":true} When enabled this employee will not receive any calls through main number/receptions or employee groups the employee is part of.
employee_group_ids	{"employee_group_ids":[1,2,3]} ID’s of the employee groups this employee is part of.
features	{"features":["mobile","live_call","integrations"]} Array of features available to this employee, depending on presence of mobile number and level of switch subscription. mobile Mobile number. switch Switch subscription. live_call Access to live call features. integrations Access to integrations. Switch Premium-only. wallboard Access to reception wallboard. Switch Premium-only. contact_notes Access to contact notes. Switch Premium-only.)
id	{"id":1} Employee ID.
live_presence	{"live_presence":"available"} The current presence status of the employee. available The employee does not have any active calls. busy The employee has one or more active calls. do_not_disturb The employee has do not disturb enabled. unknown Either the employee has live presence privacy turned on, or the employee does not have any active calls through Relatel, but may have active calls to/from their non-Relatel mobile which we do not know about.
name	{"name":"John Smith"} Employee name.
number	{"number":"4571999999"} Employee’s phone number.
speed_dial	{"speed_dial":{"digit":1}} The digit that is used to transfer calls to this employee.

Get all employees

Returns an array of all employees.

Request

GET /api/v2/employees

Response

Status: 200 OK

{
  "employees": [
    {
      "admin": true,
      "cloak_reception": null,
      "company_id": 1,
      "dnd_timeout_at": "2013-12-16T17:12:26+01:00",
      "do_not_disturb": true,
      "employee_group_ids": [
        1,
        2
      ],
      "features": [
        "mobile",
        "switch",
        "live_call"
      ],
      "id": 1,
      "live_presence": "available",
      "name": "Michael Medarbejder",
      "number": "4571999917",
      "speed_dial": {
        "digit": 17
      }
    }
  ]
}

Get a single employee by ID

Returns the employee with the specified ID.

Request

GET /api/v2/employees/:id

Response

Status: 200 OK

{
  "employee": {
    "admin": true,
    "cloak_reception": null,
    "company_id": 1,
    "dnd_timeout_at": "2013-12-16T17:12:26+01:00",
    "do_not_disturb": true,
    "employee_group_ids": [
      1,
      2
    ],
    "features": [
      "mobile",
      "switch",
      "live_call"
    ],
    "id": 1,
    "live_presence": "available",
    "name": "Michael Medarbejder",
    "number": "4571999917",
    "speed_dial": {
      "digit": 17
    }
  }
}

Update an employee by ID

Updates an employee by ID. Only administrators can update other employees.

Properties

Name	Description
cloak_reception_id	{"cloak_reception_id":1} Set the reception whose number should be used when placing calls. Required product: Switch and Mobile
dnd_timeout_at	{"dnd_timeout_at":"2014-10-10T02:48:48+02:00"} When to expire do not disturb. Required product: Switch
do_not_disturb	{"do_not_disturb":true} Enable/disable do not disturb. Required product: Switch
number	{"number":true} Change the phone number. Not applicable for employees with Relatel mobile subscriptions. Required product: Switch

Request

PUT /api/v2/employees/1

{
  "employee": {
    "cloak_reception_id": null,
    "do_not_disturb": true,
    "dnd_timeout_at": "2013-12-16T17:12:26+01:00",
    "number": "4560708896"
  }
}

Response

Status: 200 OK

{
  "employee": {
    "admin": true,
    "cloak_reception": null,
    "company_id": 1,
    "dnd_timeout_at": "2013-12-16T17:12:26+01:00",
    "do_not_disturb": true,
    "employee_group_ids": [
      1,
      2
    ],
    "features": [
      "mobile",
      "switch",
      "live_call"
    ],
    "id": 1,
    "live_presence": "available",
    "name": "Michael Medarbejder",
    "number": "4571999917",
    "speed_dial": {
      "digit": 17
    }
  }
}

Returns the currently authenticated employee

Returns the currently authenticated employee.

Request

GET /api/v2/employee

Response

Status: 200 OK

{
  "employee": {
    "admin": true,
    "cloak_reception": null,
    "company_id": 1,
    "dnd_timeout_at": "2013-12-16T17:12:26+01:00",
    "do_not_disturb": true,
    "employee_group_ids": [
      1,
      2
    ],
    "features": [
      "mobile",
      "switch",
      "live_call"
    ],
    "id": 1,
    "live_presence": "available",
    "name": "Michael Medarbejder",
    "number": "4571999917",
    "speed_dial": {
      "digit": 17
    }
  }
}

Update the currently authenticated employee

Updates the currently authenticated employee.

Properties

Name	Description
cloak_reception_id	{"cloak_reception_id":1} Set the reception whose number should be used when placing calls. Required product: Switch and Mobile
dnd_timeout_at	{"dnd_timeout_at":"2014-10-10T02:48:48+02:00"} When to expire do not disturb. Required product: Switch
do_not_disturb	{"do_not_disturb":true} Enable/disable do not disturb. Required product: Switch
number	{"number":true} Change the phone number. Not applicable for employees with Relatel mobile subscriptions. Required product: Switch

Request

PUT /api/v2/employee

{
  "employee": {
    "cloak_reception_id": null,
    "do_not_disturb": true,
    "dnd_timeout_at": "2013-12-16T17:12:26+01:00"
  }
}

Response

Status: 200 OK

{
  "employee": {
    "admin": true,
    "cloak_reception": null,
    "company_id": 1,
    "dnd_timeout_at": "2013-12-16T17:12:26+01:00",
    "do_not_disturb": true,
    "employee_group_ids": [
      1,
      2
    ],
    "features": [
      "mobile",
      "switch",
      "live_call"
    ],
    "id": 1,
    "live_presence": "available",
    "name": "Michael Medarbejder",
    "number": "4571999917",
    "speed_dial": {
      "digit": 17
    }
  }
}

Send a text message to an employee

Send an SMS message to the given employee. The sender will be shown as either the authenticated employee’s number or name.

Beware: these are cheap, but not free. Take a look at the pricelist - look for Web SMS.

This feature is not available for companies in trial.

Properties

Name	Description
message	{"message":{"body":"Hello, world."}} The content of the SMS.

Request

POST /api/v2/employees/:id/message

{
  "message": {
    "body": "Hello, world."
  }
}

Response

Status: 200 OK

{
  "sent": 1
}