Employee

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

  1. Properties
  2. Get all employees
  3. Get a single employee by ID
  4. Update an employee by ID
  5. Returns the currently authenticated employee
  6. Update the currently authenticated employee
  7. 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. Switch Plus-only.
integrations
Access to integrations. Switch Plus-only.
wallboard
Access to reception wallboard. Switch Plus-only.
contact_notes
Access to contact notes. Switch Plus-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 Firmafon, but may have active calls to/from their non-Firmafon 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 Firmafon 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 Firmafon 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
}