Beam Management API

Overview

This API allows you to programmatically do most tasks that can be done through the site administration web application:

List users, devices, user groups, and device groups
Invite new users
Rename devices and groups
Change group membership
Grant temporary device group access to users

API URIs

The root URI of the API is at https://suitabletech.com/admin-api/1/. The most current API version is version 1. Future API versions will have separate root URIs.

The URIs of all API resources are constructed by appending the resource path to the root URI. For example, the full users resource URI is https://suitabletech.com/admin-api/1/users/.

API Key Authentication

In order to make API calls securely, you must first generate an API key:

From the Beam Management app, go to the Organization Settings page by clicking the gear icon in the upper-right corner.
Enter a name for the API key, and click “Create New API Key”

The page will display your new API key. It will look something like:

APIKEY:zBlGa0mxS1jL:UQDEl8DwRyetgeOeEZLb1BJNbDWTo8dZk1SwrfZy3Jax

It is important to copy this key and store it somewhere securely. Suitable Technologies does not store the private portion of your API key on our servers. If you lose your API key, just delete the old one and generate a new one.

For the remainder of this documentation, we will assume that you are loading your stored API key into an environment variable named APIKEY. For example, to do this in bash, you would add:

APIKEY="APIKEY:zBlGa0mxS1jL:UQDEl8DwRyetgeOeEZLb1BJNbDWTo8dZk1SwrfZy3Jax"

to the top of your script.

Making API Calls

We provide a REST-ful interface for accessing the API.

Data can be retrieved by calling GET at the appropriate resource URI, and can be updated by calling PUT, PATCH, or POST at the appropriate resource URI. NOTE: PATCH updates only the fields you specify, whereas PUT will replace the resource so unspecified fields will revert to their defaults.
The input can be sent using form-encoded, JSON-encoded, or YAML-encoded data.
The response can be returned as JSON or YAML. JSON is the default response format. For YAML, append a ?format=yaml query parameter to the resource URI.
Authorization is always done by setting the HTTP Authorization header to your API key.
All requests must be made over HTTPS.
For operations that return lists, e.g. users in a user group, special set operations add_ and remove_ are supported. For example: add_users and remove_users.

To verify your API key is working, you can GET the info resource using curl:

curl https://suitabletech.com/admin-api/1/info/ -H Authorization:$APIKEY

Collections and Pagination

When making GET requests to resources that represent a collection of objects, such as /users/, you may supply the optional query string parameters limit and offset. limit will limit the number of results returned, and offset will begin the list of returned results at the specified index. Using these two parameters, you can page through a large collection by making API calls similar to the following:

GET /admin-api/1/users/?limit=10
GET /admin-api/1/users/?limit=10&offset=10
GET /admin-api/1/users/?limit=10&offset=20
...

Responses from resources that represent a collection of objects have two top-level attributes: meta and objects. meta is an object that contains metadata about the list of objects included in the response. objects is the list of requested objects.

The meta object includes the following fields:

limit: The maximum number of objects that this response was limited to. If a limit query string parameter was supplied, this will reflect that. Otherwise responses will be limited by a default of 20 objects.
offset: Any offset that was supplied as a query string parameter. If none was supplied, this will be 0.
next: A URI representing the next page of results, with limit and offset calculated for you. If you are on the last page of results, this will be null.
previous: A URI representing the previos page of results, with limit and offset calculated for you. If you are on the first page of results, this will be null.
total_count: The total number of objects in this collection.

Info ¶

This resource provides top-level information about the API key and its associated organization.

Info ¶

The info resource includes the following fields:

Field	Type	Description
`key`	string	The name of the API key being used
`organization`	string	The name of the organization associated with this API key
`user`	dictionary	Only used for OAuth2-based authentication (not supported at this time)

Get Organization Info
GET`/info/`

Python example

r = requests.get('https://suitabletech.com/admin-api/1/info/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/info/' -H Authorization:$APIKEY

Example URI

GET /info/

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "key": "My Example API Key",
  "organization": "My Organization",
  "user": null
}

Users ¶

The users resource provides information about the users in your organization.

Users contain the followimg fields:

Field	Type	Description
`email_address`	string	The user’s email address
`first_name`	string	The user’s first name
`last_name`	string	The user’s last name
`is_admin`	boolean	Whether or not the user is an administrator of the organization
`is_temporary`	boolean	Read-only. Whether the user has only been granted temporary access.
`profile_image`	dictionary	Unused for now, but will eventually contain profile image data.
`last_login`	string	The date and time of the user’s last login, in YYYY:MM😄DTHH:MM:SS format

Users List ¶

Get Users
GET`/users/`

Get a list of users. By default, this will include temporary users (those who have been granted temporary access to one or more device groups, but have not been added to the organization). Pass ?include_temporary=false to omit temporary users.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/users/?limit=10', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/users/?limit=10' -H Authorization:$APIKEY

Example URI

GET /users/

URI Parameters

HideShow

include_temporary: boolean (optional) Default: true
Whether to include temporary users

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "meta": {
    "limit": 10,
    "next": "/admin-api/1/users/?limit=10&offset=10",
    "offset": 0,
    "previous": null,
    "total_count": 60
  },
  "objects": [
    {
      "email_address": "dufour@org3.net",
      "first_name": "Santos",
      "is_admin": true,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Dufour",
      "profile_image": null
    },
    {
      "email_address": "jamar@org3.net",
      "first_name": "Usha",
      "is_admin": true,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Jamar",
      "profile_image": null
    },
    {
      "email_address": "burbach@org3.net",
      "first_name": "Louetta",
      "is_admin": true,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Burbach",
      "profile_image": null
    },
    {
      "email_address": "steinbeck@org3.net",
      "first_name": "Marcelino",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Steinbeck",
      "profile_image": null
    },
    {
      "email_address": "coulston@org3.net",
      "first_name": "Arica",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Coulston",
      "profile_image": null
    },
    {
      "email_address": "haak@org3.net",
      "first_name": "Terina",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Haak",
      "profile_image": null
    },
    {
      "email_address": "armour@org3.net",
      "first_name": "Vanessa",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Armour",
      "profile_image": null
    },
    {
      "email_address": "shoaf@org3.net",
      "first_name": "Betty",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Shoaf",
      "profile_image": null
    },
    {
      "email_address": "blea@org3.net",
      "first_name": "Katerine",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Blea",
      "profile_image": null
    },
    {
      "email_address": "kolodziej@org3.net",
      "first_name": "Susanna",
      "is_admin": false,
      "is_temporary": false,
      "last_login": "2014-07-09T18:07:50",
      "last_name": "Kolodziej",
      "profile_image": null
    }
  ]
}

User ¶

Get a User
GET`/users/{email}/`

Get a single user.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/users/dufour@org3.net/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/users/dufour@org3.net/' -H Authorization:$APIKEY

Example URI

GET /users/joe.user@example.com/

URI Parameters

HideShow

email: string (required) Example: joe.user@example.com
The email address of the user

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "email_address": "dufour@org3.net",
  "first_name": "Santos",
  "is_admin": true,
  "is_temporary": false,
  "last_name": "Dufour",
  "profile_image": null,
  "last_login": "2014-07-09T18:07:50"
}

Response 404

Patch a User
PATCH`/users/{email}/`

Patch a user. At this time, the only field available for patching is is_admin.

Python example

data = {
    'is_admin': false
}
r = requests.patch('https://suitabletech.com/admin-api/1/users/dufour@org3.net/', headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F is_admin='false' 'https://suitabletech.com/admin-api/1/users/dufuor@org3.net/' -H Authorization:$APIKEY

Example URI

PATCH /users/joe.user@example.com/

URI Parameters

HideShow

email: string (required) Example: joe.user@example.com
The email address of the user

Response 202

Response 404

Inviting Users ¶

To add users to your organization, you send them an invitation. When you invite a user, we’ll send them an email message notifying them that they are now part of your organization. If the user doesn’t have an account in our system, the email message will include a link to set their password and provide other details, such as their name.

Invitations have the following fields:

Field	Type	Default	Description
`email_address`	string	(required)	The user’s email address
`first_name`	string	‘’	The user’s first name
`last_name`	string	‘’	The user’s last name
`device_groups`	list	[]	List of device group IDs to add the new user as a member
`from_name`	string	(required)	Name to use in the invitation email
`message`	string	Here is your invitation to create a Beam account. Now you’ll be able to Beam in to our site from anywhere!	Message to send to new users
`cc`	list	[]	List of email addresses to send CC’d copies of the invitation email

Invite a User ¶

Invite a User
POST`/invite/`

Invite a user to your organization.

Python example

data = {
  'email_address': 'smith@org3.net',
  'first_name': 'Joe',
  'last_name': 'Smith',
  'from_name': 'John Johnson',
  'device_groups': [10],
}
r = requests.post('https://suitabletech.com/admin-api/1/invite/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST https://suitabletech.com/admin-api/1/invite/ -F email_address="smith@org3.net" -F first_name=Joe -F last_name=Smith -F device_groups=10 -F from_name="John Johnson" -H Authorization:$APIKEY

Example URI

POST /invite/

URI Parameters

HideShow

send_mail: boolean (optional) Default: true Example: false
Send mail to invited user

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "first_name": "Joe", 
  "from_name": "John Johnson", 
  "cc": [], 
  "last_name": "Smith", 
  "device_groups": [10], 
  "message": "Here is your invitation to create a Beam account. Now you'll be able to Beam in to our site from anywhere!", 
  "email_address": "smith@org3.net", 
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'from_name' field has no data and doesn't allow a default or null value."
}

Devices ¶

The devices resource provides information about the devices (Beams) in your organization.

Devices contain the following fields:

Field	Type	Default	Description
`id`	string	read-only	The unique identifier of the device
`name`	string	(required)	The device’s name
`tags`	list	[]	A list of tag strings associated with the device
`time_zone`	string	America/Pacific	The time zone that the device is in
`location`	string	“”	The device’s location
`device_group`	integer	(required)	The ID of the device group that the device is in
`state`	dictionary	read-only	The device’s current state.
`last_call`	dictionary	read-only	The last completed call on this device.
`profile_image`	dictionary	read-only	Unused for now, but will eventually contain profile image data.

Device List ¶

Get Devices
GET`/devices/`

Get a list of all devices.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/devices/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/devices/' -H Authorization:$APIKEY

Example URI

GET /devices/

URI Parameters

HideShow

device_group

integer (optional) Example: 6

Filter the results by device group ID

inline

string (optional) Example: device_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "meta": {
    "previous": null, 
    "total_count": 3, 
    "offset": 0, 
    "limit": 1000, 
    "next": null
  }, 
  "objects": [
    {
      "name": "Beam 1", 
      "tags": [
        "Sales", 
        "Marketing"
      ], 
      "time_zone": "America/Los_Angeles", 
      "device_group": "4", 
      "location": "Downstairs", 
      "profile_image": null,
      "state": null,
      "last_call": null,
      "id": "beam1234567"
    }, 
    {
      "name": "Home Beam", 
      "tags": [
        "Mom's House"
      ], 
      "time_zone": "America/New_York", 
      "device_group": "5", 
      "location": "Home", 
      "profile_image": null,
      "state": {
        "call_state": "STATE_AVAILABLE",
        "batt_percent": 85,
        "batt_charging": true,
        "pilot": "",
        "reported_at": "2014-02-28T19:55:31+00:00"
      },
      "last_call": {
        "call_end": "2014-03-09T20:19:24+00:00",
        "call_start": "2014-03-09T18:39:12+00:00",
        "pilot": "dufour@org3.net"
      },
      "id": "beam1234568"
    }, 
    {
      "name": "Beam 2", 
      "tags": [], 
      "time_zone": "America/Los_Angeles", 
      "device_group": "6", 
      "location": "Building 1", 
      "profile_image": null,
      "state": {
        "call_state": "STATE_IN_CALL",
        "batt_percent": 78,
        "batt_charging": false,
        "pilot": "steinbeck@org3.net",
        "reported_at": "2014-02-28T19:55:31+00:00"
      },
      "last_call": null,
      "id": "beam1234569"
    }, 
  ]
}

Device ¶

Get a Device
GET`/devices/{id}/`

Get a single device.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/devices/beam1234567/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/devices/beam1234567/' -H Authorization:$APIKEY

Example URI

GET /devices/beam12345678/

URI Parameters

HideShow

id

string (required) Example: beam12345678

The ID of the device

inline

string (optional) Example: device_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "name": "Beam 1",
  "tags": [
    "Sales",
    "Marketing"
  ],
  "time_zone": "America/Los_Angeles",
  "device_group": "4",
  "location": "Downstairs",
  "profile_image": null,
  "state": null,
  "last_call": null,
  "id": "beam1234567"
}

Response 404

Patch a Device
PATCH`/devices/{id}/`

Patch individual fields on a device.

Python example

data = {
  'name': 'Beam 123',
  'tags': ['Sales', 'Marketing'],
}
r = requests.patch('https://suitabletech.com/admin-api/1/devices/beam1234567/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F add_tags='Sales' -F add_tags='Marketing' -F name='Beam 123' 'https://suitabletech.com/admin-api/1/devices/beam1234567/' -H Authorization:$APIKEY

Example URI

PATCH /devices/beam12345678/

URI Parameters

HideShow

id: string (required) Example: beam12345678
The ID of the device

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Response 404

Update a Device
PUT`/devices/{id}/`

Replace all fields on a device. Unspecified fields will be set to their default values.

Python example

data = {
  'name': 'Beam 123',
  'device_group': 6,
  'time_zone': 'America/Los_Angeles',
}
r = requests.put('https://suitabletech.com/admin-api/1/devices/beam1234567/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PUT -F name='Beam 123' -F device_group=6 -F time_zone='America/Los_Angeles' 'https://suitabletech.com/admin-api/1/devices/beam1234567/' -H Authorization:$APIKEY

Example URI

PUT /devices/beam12345678/

URI Parameters

HideShow

id: string (required) Example: beam12345678
The ID of the device

Response 204

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Response 404

Device Groups ¶

This resource provides information about the device groups in your organization. Every organization has one or more device groups, and every device belongs to exactly one device group.

Device groups have the following fields:

Field	Type	Default	Description
`id`	integer	(read-only)	The device group’s unique identifier
`name`	string	(required)	The name of the device group
`devices`	list	[]	A list of device IDs in the device group
`notify_admins_battery`	boolean	true	Whether or not administrators will be notified for battery events, such as when the device is left off the charger
`notify_last_pilot`	boolean	true	Whether or not the last pilot will be notified if they left a device off the charger
`answer_users`	list	[]	A list of users who may accept calls to devices in this group
`allowed_auth`	list	[‘a’]	A list of allowed authentication schemes. `'a'` is all authorization models, and should be sufficient for most uses.

Device Group List ¶

Get Device Groups
GET`/device-groups/`

Get a list of all device groups.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/device-groups/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/device-groups/' -H Authorization:$APIKEY

Example URI

GET /device-groups/

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "meta": {
    "previous": null, 
    "total_count": 3, 
    "offset": 0, 
    "limit": 1000, 
    "next": null
  }, 
  "objects": [
    {
      "allowed_auth": [
        "a"
      ],
      "name": "Sales Group", 
      "id": "10",
      "devices": [
        "beam1234567",
        "beam1234568",
      ],
      "notify_last_pilot": true,
      "notify_users": [
        "shoaf@org3.net",
        "blea@org3.net",
      ],
      "answer_users": [
        "shoaf@org3.net",
      ],
    }, 
    {
      "allowed_auth": [
        "a"
      ],
      "name": "Marketing Group", 
      "id": "11",
      "devices": [
        "beam9234567",
        "beam9234568",
      ],
      "notify_last_pilot": true,
      "notify_users": [
        "shoaf@org3.net",
        "blea@org3.net",
      ],
      "answer_users": [
      ],
    }, 
    {
      "allowed_auth": [
        "a"
      ],
      "name": "Development Group", 
      "id": "12",
      "devices": [
        "beam8234567",
        "beam8234568",
      ],
      "notify_last_pilot": false,
      "notify_users": [
        "shoaf@org3.net",
        "blea@org3.net",
      ],
      "answer_users": [
      ],
    }, 
  ]
}

Create a Device Group
POST`/device-groups/`

Create a new device group.

Python example

data = {
  'name': 'Sales Group',
  'notify_last_pilot': True,
  'devices': ['beam1234567', 'beam1234568'],
}
r = requests.post('https://suitabletech.com/admin-api/1/device-groups/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST -F name='Sales Group' -F devices=beam1234567 -F devices=beam1234568 -F notify_last_pilot=True 'https://suitabletech.com/admin-api/1/device-groups/' -H Authorization:$APIKEY

Example URI

POST /device-groups/

Response 201

HideShow

Headers

Location: https://suitabletech.com/admin-api/1/device-groups/123/

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Device Group ¶

Get a Device Group
GET`/device-groups/{id}/`

Get a single device group.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/device-groups/10/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/device-groups/10/' -H Authorization:$APIKEY

Example URI

GET /device-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "allowed_auth": [
    "a"
  ],
  "name": "Sales Group",
  "id": "10",
  "devices": [
    "beam1234567",
    "beam1234568",
  ],
  "notify_last_pilot": true,
  "notify_users": [
    "shoaf@org3.net",
    "blea@org3.net",
  ],
  "answer_users": [
  ],
}

Response 404

Patch a Device Group
PATCH`/device-groups/{id}/`

Patch individual fields on a device group.

Python example

data = {
  'name': 'New Sales Group',
}
r = requests.patch('https://suitabletech.com/admin-api/1/device-groups/10/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F name='New Sales Group' 'https://suitabletech.com/admin-api/1/device-groups/10/' -H Authorization:$APIKEY

Example URI

PATCH /device-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Response 404

Update a Device Group
PUT`/device-groups/{id}/`

Replace all fields on a device group. Unspecified fields will be set to their default values.

Python example

data = {
  'name': 'New Sales Group',
  'devices': ['beam1234567'],
}
r = requests.put('https://suitabletech.com/admin-api/1/device-groups/10/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PUT -F name='New Sales Group' -F devices='beam1234567' 'https://suitabletech.com/admin-api/1/device-groups/10/' -H Authorization:$APIKEY

Example URI

PUT /device-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group

Response 204

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Response 404

Delete a Device Group
DELETE`/device-groups/{id}/`

Delete a device group.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/device-groups/10/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/device-groups/10/' -H Authorization:$APIKEY

Example URI

DELETE /device-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group

Response 204

Response 404

User Groups ¶

Users in an organization can be organized into groups. A user may be a member of no groups or multiple groups. This resource provides information about the user groups in your organization.

A user group has the following fields:

Field	Type	Default	Description
`id`	integer	(read-only)	The user group’s unique identifier
`name`	string	(required)	The user group’s name
`users`	list	[]	A list of usernames in this group

User Group List ¶

Get User Groups
GET`/user-groups/`

Get a list of all user groups.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/user-groups/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/user-groups/' -H Authorization:$APIKEY

Example URI

GET /user-groups/

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "meta": {
    "previous": null, 
    "total_count": 1, 
    "offset": 0, 
    "limit": 1000, 
    "next": null
  }, 
  "objects": [
    {
      "name": "Developers", 
      "id": "1",
      "users": [
        "steinbeck@org3.net",
        "burbach@org3.net",
      ]
    }
  ]
}

Create a user Group
POST`/user-groups/`

Create a new user group.

Python example

data = {
  'name': 'Developers',
  'users': ['steinbeck@org3.net', 'burbach@org3.net'],
}
r = requests.post('https://suitabletech.com/admin-api/1/user-groups/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST -F name='Sales Group' -F devices=beam1234567 -F devices=beam1234568 -F notify_last_pilot=True 'https://suitabletech.com/admin-api/1/user-groups/' -H Authorization:$APIKEY

Example URI

POST /user-groups/

Response 201

HideShow

Headers

Location: https://suitabletech.com/admin-api/1/user-groups/123/

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

User Group ¶

Get a User Group
GET`/user-groups/{id}/`

Get a single user group.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/user-groups/1/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/user-groups/1/' -H Authorization:$APIKEY

Example URI

GET /user-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the user group

Response 200

HideShow

Body

{
  "name": "Developers", 
  "id": "1",
  "users": [
    "steinbeck@org3.net",
    "burbach@org3.net",
  ]
}

Response 404

Patch a User Group
PATCH`/user-groups/{id}/`

Patch individual fields on a user group.

Python example

data = {
  'name': 'Developers User Group',
}
r = requests.patch('https://suitabletech.com/admin-api/1/user-groups/1/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F name='Developers User Group' 'https://suitabletech.com/admin-api/1/user-groups/1/' -H Authorization:$APIKEY

Example URI

PATCH /user-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the user group

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Response 404

Update a User Group
PUT`/user-groups/{id}/`

Update all fields on a user group. Unspecified fields will be set to their default values.

Python example

data = {
  'name': 'Developers User Group',
  'users': ['steinbeck@org3.net'],
}
r = requests.put('https://suitabletech.com/admin-api/1/user-groups/1/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PUT -F name='Developers User Group' -F users='steinbeck@org3.net' 'https://suitabletech.com/admin-api/1/user-groups/1/' -H Authorization:$APIKEY

Example URI

PUT /user-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the user group

Response 204

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'name' field has no data and doesn't allow a default or null value."
}

Response 404

Delete a User Group
DELETE`/user-groups/{id}/`

Delete a user group. The individual users will NOT be deleted.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/user-groups/1/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/user-groups/1/' -H Authorization:$APIKEY

Example URI

DELETE /user-groups/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the user group

Response 204

Response 404

Device Group Memberships ¶

Device group memberships indicate which users or user groups are members of a device group. This resource provides information about the device group memberships in your organization.

Device group memberships have the following fields:

Field	Type	Default	Description
`id`	integer	n/a	The unique identifier for the device group membership
`device_group`	integer	(required)	The ID of the device group that this user or user group is a member of.
`user`	integer	null	The ID of the user who is a member.
`user_group`	integer	null	The ID of the user group who is a member.
`access_times`	list	[]	A list of access times that apply specifically to this membership. This list is read-only; to modify access times, see Access Times.

Either user or user_group must be specified, but not both.

Device Group Membership List ¶

Get Device Group Memberships
GET`/device-group-memberships/`

Get a list of device group memberships.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/device-group-memberships/?inline=user,user_group', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/device-group-memberships/?inline=user,user_group' -H Authorization:$APIKEY

Example URI

GET /device-group-memberships/

URI Parameters

HideShow

inline

string (optional) Example: user,user_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: user user_group device_group access_times

device_group

integer (optional) Example: 14

Filter the results by device group ID.

user

string (optional) Example: sam@example.org

Filter the results by user.

user_group

integer (optional) Example: 123

Filter the results by user group.

Response 200

HideShow

Body

{
  "meta": {
    "limit": 1000,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "access_times": [],
      "device_group": 1,
      "id": 15,
      "user": null,
      "user_group": {
        "name": "Developers", 
        "id": "1",
        "users": [
          "steinbeck@org3.net",
          "burbach@org3.net",
        ],
      }, 
    },
    {
      "access_times": [],
      "device_group": 1,
      "id": 14,
      "user": {
        "email_address": "haak@org3.net",
        "first_name": "Terina",
        "is_admin": false,
        "last_name": "Haak",
        "profile_image": null
      },
      "user_group": null,
    }
  ]
}

Create a Device Group Membership
POST`/device-group-memberships/`

Add a user or user group as a member of a device group.

Python example

data = {
    "device_group": 1,
    "user": "haak@org3.net"
}
r = requests.post('https://suitabletech.com/admin-api/1/device-group-memberships/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST -F device_group='1' -F user='haak@org3.net' 'https://suitabletech.com/admin-api/1/device-group-memberships/' -H Authorization:$APIKEY

Example URI

POST /device-group-memberships/

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "device_group": 1,
  "user": "haak@org3.net"
}

Response 201

HideShow

Headers

Location: https://suitabletech.com/admin-api/1/device-group-memberships/87/

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "There is no user group with ID 10 in this organization."
}

Create Multiple
PATCH`/device-group-memberships/`

Create many device group memberships with one API call.

Python example

data = {
    'objects': [
        {
            'device_group': 1,
            'user': 'haak@org3.net'
        },
        {
            'device_group': 1,
            'user_group': 10
        }
    ]
}
r = requests.patch('https://suitabletech.com/admin-api/1/device-group-memberships/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -d '{"objects": [{"device_group": 1, "user": "haak@org3.net"}, {"device_group": 1, "user_group": 10}]}' 'https://suitabletech.com/admin-api/1/device-group-memberships/' -H Authorization:$APIKEY

Example URI

PATCH /device-group-memberships/

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "objects": [
    {
      "device_group": 1,
      "user": "haak@org3.net"
    },
    {
      "device_group": 1,
      "user_group": 10
    }
  ]
}

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "There is no user group with ID 10 in this organization."
}

Device Group Membership ¶

Get a Device Group Membership
GET`/device-group-memberships/{id}/`

Get a single device group membership.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/device-group-memberships/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/device-group-memberships/' -H Authorization:$APIKEY

Example URI

GET /device-group-memberships/123/

URI Parameters

HideShow

id

integer (required) Example: 123

The ID of the device group membership

inline

string (optional) Example: user,user_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: user user_group device_group access_times

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 14,
  "device_group": 1,
  "user": "haak@org3.net",
  "user_group": null,
  "access_times": [876, 987],
}

Response 404

Patch a Device Group Membership
PATCH`/device-group-memberships/{id}/`

Patch individual fields on a device group membership.

Python example

data = {
    "user": "steinbeck@org3.net"
}
r = requests.patch('https://suitabletech.com/admin-api/1/device-group-memberships/10/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F user='steinbeck@org3.net' 'https://suitabletech.com/admin-api/1/device-group-memberships/10/'

Example URI

PATCH /device-group-memberships/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group membership

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "user": "steinbeck@org3.net"
}

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "'user': That user doesn't exist."
}

Response 404

Update a Device Group Membership
PUT`/device-group-memberships/{id}/`

Replace all fields on a device group membership. Unspecified fields will be set to their default values.

Python example

data = {
    "device_group": 1,
    "user": "haak@org3.net",
    "user_group": null
}
r = requests.put('https://suitabletech.com/admin-api/1/device-group-memberships/10/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PUT -F user='haak@org3.net' -F device_group='1' 'https://suitabletech.com/admin-api/1/device-group-memberships/10/' -H Authorization:$APIKEY

Example URI

PUT /device-group-memberships/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group membership

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "device_group": 1,
  "user": "haak@org3.net",
  "user_group": null
}

Response 204

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "'user': That user doesn't exist."
}

Response 404

Delete a Device Group Membership
DELETE`/device-group-memberships/{id}/`

Delete a device group membership. This removes the user or user group from the device group.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/device-group-memberships/10/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/device-group-memberships/' -H Authorization:$APIKEY

Example URI

DELETE /device-group-memberships/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the device group membership

Response 204

Response 404

Access Times ¶

An access time specifies which days and times a member of a device group may call its devices.

Access times can be combined additively to create more fine-grained access times for a membership. For example, a device group membership could have two access times: One could specify Monday - Friday 9:00 AM through 5:00 PM, while another could specify all day Saturday and Sunday.

Access times have the following fields:

Field	Type	Default	Description
`id`	integer	n/a	The access time’s unique identifier
`device_group_membership`	integer	(required)	The ID of the device group membership to which this access time applies
`sunday`	boolean	true	Whether users can call devices on Sunday
`monday`	boolean	true	Whether users can call devices on Monday
`tuesday`	boolean	true	Whether users can call devices on Tuesday
`wednesday`	boolean	true	Whether users can call devices on Wednesday
`thusday`	boolean	true	Whether users can call devices on Thursday
`friday`	boolean	true	Whether users can call devices on Friday
`saturday`	boolean	true	Whether users can call devices on Saturday
`start_time`	string	null	The beginning of the access time period in 24-hour HH:MM:SS format
`end_time`	string	null	The end of the access time period in 24-hour HH:MM:SS format
`answer_required`	boolean	false	Whether or not calls during this time period must be accepted on the receiving side

If start_time and end_time are omitted, the access time allows calling during the entire day (12:00 AM to 11:59 PM)

Access Time List ¶

Get Access Times
GET`/access-times/`

Get all access times in the organization.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/access-times/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/access-times/' -H Authorization:$APIKEY

Example URI

GET /access-times/

URI Parameters

HideShow

inline

string (optional) Example: device_group_membership

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group_membership

device_group_membership

integer (optional) Example: 14

Filter the results by device group membership ID.

Response 200

HideShow

Body

{
  "meta": {
    "limit": 1000,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 3
  },
  "objects": [
    {
      "device_group_membership": 28,
      "end_time": "16:30:00",
      "friday": false,
      "id": 25,
      "monday": true,
      "saturday": false,
      "start_time": "09:00:00",
      "sunday": false,
      "thursday": false,
      "tuesday": false,
      "wednesday": false
    },
    {
      "device_group_membership": 28,
      "end_time": null,
      "friday": false,
      "id": 33,
      "monday": false,
      "saturday": false,
      "start_time": null,
      "sunday": true,
      "thursday": false,
      "tuesday": false,
      "wednesday": false
    },
    {
      "device_group_membership": 28,
      "end_time": "09:30:00",
      "friday": false,
      "id": 40,
      "monday": false,
      "saturday": false,
      "start_time": "07:00:00",
      "sunday": true,
      "thursday": false,
      "tuesday": true,
      "wednesday": false
    }
  ]
}

Create an Access Time
POST`/access-times/`

Create an access time.

Python example

data = {
    "device_group_membership": 24,
    "end_time": "17:00:00",
    "friday": true,
    "monday": true,
    "saturday": false,
    "start_time": "09:00:00",
    "sunday": false,
    "thursday": true,
    "tuesday": true,
    "wednesday": true
} 
r = requests.post('https://suitabletech.com/admin-api/1/access-times/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST -F device_group_membership='24' -F start_time='09:00:00' -F end_time='17:00:00' 'https://suitabletech.com/admin-api/1/access-times/' -H Authorization:$APIKEY

Example URI

POST /access-times/

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "device_group_membership": 24,
  "end_time": "17:00:00",
  "friday": true,
  "monday": true,
  "saturday": false,
  "start_time": "09:00:00",
  "sunday": false,
  "thursday": true,
  "tuesday": true,
  "wednesday": true
}

Response 201

HideShow

Headers

Location: https://suitabletech.com/admin-api/1/access-times/41/

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Device group membership with id 24 does not exist."
}

Access Time ¶

Get an Access Time
GET`/access-times/{id}/`

Get a single access time.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/access-times/123/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/access-times/123/' -H Authorization:$APIKEY

Example URI

GET /access-times/123/

URI Parameters

HideShow

id

integer (required) Example: 123

The ID of the access time

inline

string (optional) Example: device_group_membership

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group_membership

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "device_group_membership": 24,
  "end_time": "17:00:00",
  "friday": true,
  "id": 41,
  "monday": true,
  "saturday": false,
  "start_time": "09:00:00",
  "sunday": false,
  "thursday": true,
  "tuesday": true,
  "wednesday": true
}

Response 404

Update an Access Time
PUT`/access-times/{id}/`

Replace all fields on an access time. Unspecified fields will be reset to their default values.

Python example

data = {
    "device_group_membership": 24,
    "friday": true,
    "monday": true,
    "saturday": false,
    "sunday": false,
    "thursday": true,
    "tuesday": true,
    "wednesday": true
}
r = requests.put('https://suitabletech.com/admin-api/1/access-times/123/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PUT device_group_membership='24' -F sunday='false' -F saturday='false' 'https://suitabletech.com/admin-api/1/access-times/123/' -H Authorization:$APIKEY

Example URI

PUT /access-times/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the access time

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "device_group_membership": 24,
  "friday": true,
  "monday": true,
  "saturday": false,
  "sunday": false,
  "thursday": true,
  "tuesday": true,
  "wednesday": true
}

Response 204

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Device group membership with id 24 does not exist"
}

Response 404

Delete an Access Time
DELETE`/access-times/{id}/`

Delete a single default access time.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/access-times/123/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/access-times/123/' -H Authorization:$APIKEY

Example URI

DELETE /access-times/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the access time

Response 204

Response 404

Default Access Times ¶

Default access times apply to every member of a device group, and determine which days and times users can call devices in the device group.

Default access times can be combined additively to create more fine-grained access times for a group. For example, a device group could have two default access times: One could specify Monday - Friday 9:00 AM through 5:00 PM, while another could specify all day Saturday and Sunday.

Default access times have the following fields:

Field	Type	Default	Description
`id`	integer	n/a	The access time’s unique identifier
`device_group`	integer	(required)	The ID of the device group to which this access time applies
`sunday`	boolean	true	Whether users can call devices on Sunday
`monday`	boolean	true	Whether users can call devices on Monday
`tuesday`	boolean	true	Whether users can call devices on Tuesday
`wednesday`	boolean	true	Whether users can call devices on Wednesday
`thusday`	boolean	true	Whether users can call devices on Thursday
`friday`	boolean	true	Whether users can call devices on Friday
`saturday`	boolean	true	Whether users can call devices on Saturday
`start_time`	string	null	The beginning of the access time period in 24-hour HH:MM:SS format
`end_time`	string	null	The end of the access time period in 24-hour HH:MM:SS format
`answer_required`	boolean	false	Whether or not calls during this time period must be accepted on the receiving side

If start_time and end_time are omitted, the access time allows calling during the entire day (12:00 AM to 11:59 PM)

Default Access Time List ¶

Get Default Access Times
GET`/default-access-times/`

Get all default access times in the organization.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/default-access-times/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/default-access-times/' -H Authorization:$APIKEY

Example URI

GET /default-access-times/

URI Parameters

HideShow

inline

string (optional) Example: device_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group

device_group

integer (optional) Example: 14

Filter the results by device group ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "meta": {
    "limit": 1000,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "device_group": 1,
      "end_time": null,
      "friday": false,
      "id": 1,
      "monday": false,
      "saturday": true,
      "start_time": null,
      "sunday": true,
      "thursday": false,
      "tuesday": false,
      "wednesday": false
    },
    {
      "device_group": 1,
      "end_time": "17:00:00",
      "friday": true,
      "id": 8,
      "monday": true,
      "saturday": false,
      "start_time": "09:00:00",
      "sunday": false,
      "thursday": true,
      "tuesday": true,
      "wednesday": true
    }
  ]
}

Create a Default Access Time
POST`/default-access-times/`

Create a default access time.

Python example

data = {
    "device_group": 10,
    "end_time": "17:00:00",
    "friday": true,
    "monday": true,
    "saturday": false,
    "start_time": "09:00:00",
    "sunday": false,
    "thursday": true,
    "tuesday": true,
    "wednesday": true
} 
r = requests.post('https://suitabletech.com/admin-api/1/default-access-times/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST -F device_group='10' -F start_time='09:00:00' -F end_time='17:00:00' 'https://suitabletech.com/admin-api/1/default-access-times/' -H Authorization:$APIKEY

Example URI

POST /default-access-times/

Request

HideShow

Headers

Content-Type: application/json
Authorization: $APIKEY

Body

{
  "device_group": 1,
  "end_time": "17:00:00",
  "friday": true,
  "monday": true,
  "saturday": false,
  "start_time": "09:00:00",
  "sunday": false,
  "thursday": true,
  "tuesday": true,
  "wednesday": true
}

Response 201

HideShow

Headers

Location: https://suitabletech.com/admin-api/1/default-access-times/10/

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Device group with id 10 does not exist."
}

Default Access Time ¶

Get a Default Access Time
GET`/default-access-times/{id}/`

Get a single default access time.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/default-access-times/123/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/default-access-times/123/' -H Authorization:$APIKEY

Example URI

GET /default-access-times/123/

URI Parameters

HideShow

id

integer (required) Example: 123

The ID of the default access time

inline

string (optional) Example: device_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "device_group": 1,
  "end_time": "17:00:00",
  "friday": true,
  "id": 8,
  "monday": true,
  "saturday": false,
  "start_time": "09:00:00",
  "sunday": false,
  "thursday": true,
  "tuesday": true,
  "wednesday": true
}

Response 404

Delete a Default Access Time
DELETE`/default-access-times/{id}/`

Delete a single default access time.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/default-access-times/123/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/default-access-times/123/' -H Authorization:$APIKEY

Example URI

DELETE /default-access-times/123/

URI Parameters

HideShow

id

integer (required) Example: 123

The ID of the default access time

inline

string (optional) Example: device_group

Comma-separated list of fields you would like to be expanded inline in the response.

Choices: device_group

Response 204

Response 404

Temporary Access ¶

Temporary access times allow users to call devices between two specific points in time. You can grant users temporary access to devices without adding them as permanent members of your organization. This resource provides information about users with temporary access to your devices.

Temporary access times have the following fields:

Field	Type	Default	Description
`email_address`	string	(required)	The user’s email address
`first_name`	string	‘’	The user’s first name
`last_name`	string	‘’	The user’s last name
`device_group`	integer	(required)	The ID of the device group to which you’d like to grant access
`start`	string	(required)	The start date and time in YYYY-MM-DDTHH:MM:SS format
`end`	string	(required)	The end date and time in YYYY-MM-DDTHH:MM:SS format
`answer_required`	boolean	false	Whether or not calls by this user must be accepted on the receiving side

Temporary Access Time List ¶

Get Temporary Access Times
GET`/temporary-access/`

Get a list of temporary access times.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/temporary-access/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/temporary-access/' -H Authorization:$APIKEY

Example URI

GET /temporary-access/

Response 200

HideShow

Body

{
  "meta": {
    "limit": 1000,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 3
  },
  "objects": [
    {
      "answer_required": true,
      "device_group": 1,
      "email_address": "joe@org3.net",
      "end": "2014-04-24T12:00:00",
      "first_name": "Joe",
      "last_name": "Smith",
      "start": "2014-04-24T11:00:00"
    },
    {
      "answer_required": false,
      "device_group": 2,
      "email_address": "jaden@org3.net",
      "end": "2014-04-24T13:00:00",
      "first_name": "Jaden",
      "last_name": "Smith",
      "start": "2014-04-24T12:00:00"
    },
    {
      "answer_required": false,
      "device_group": 2,
      "email_address": "will@org3.net",
      "end": "2014-04-24T13:00:00",
      "first_name": "Will",
      "last_name": "Smith",
      "start": "2014-04-24T12:00:00"
    }
  ]
}

Grant temporary access
POST`/temporary-access/`

Grant temporary access to a device group.

Python example

data = {
  'answer_required': True,
  'email_address': 'smith@org3.net',
  'first_name': 'Joe',
  'last_name': 'Smith',
  'device_group': 10,
  'start': '2013-12-31T11:59:50',
  'end': '2014-01-01T00:10:00',
}
r = requests.post('https://suitabletech.com/admin-api/1/temporary-access/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST https://suitabletech.com/admin-api/1/temporary-access/ -F email_address=smith@org3.net -F first_name=Joe -F last_name=Smith -F device_group=10 -F start='2013-12-31T11:59:50' -F end='2014-01-01T00:10:00' -F answer_required=true -H Authorization:$APIKEY

Example URI

POST /temporary-access/

URI Parameters

HideShow

send_mail: boolean (optional) Default: true Example: false
Send mail to invited user

Response 201

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "There is no device group with ID 10 in this organization."
}

Temporary Access Time ¶

Get a Temporary Access Time
GET`/temporary-access/{id}/`

Get a single temporary access time.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/temporary-access/123/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/temporary-access/123/' -H Authorization:$APIKEY

Example URI

GET /temporary-access/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the temporary access time

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "answer_required": true,
  "device_group": 1,
  "email_address": "joe@org3.net",
  "end": "2014-04-24T12:00:00",
  "first_name": "Joe",
  "last_name": "Smith",
  "start": "2014-04-24T11:00:00"
}

Response 404

Patch a Temporary Access Time
PATCH`/temporary-access/{id}/`

Patch individual fields on a temporary access time.

Python example

data = {
  "end": "2014-04-24T13:00:00",
}
r = requests.patch('https://suitabletech.com/admin-api/1/temporary-access/123/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F end="2014-04-24T13:00:00" 'https://suitabletech.com/admin-api/1/temporary-access/123/' -H Authorization:$APIKEY

Example URI

PATCH /temporary-access/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the temporary access time

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'end' field has no data and doesn't allow a default or null value."
}

Response 404

Update a Temporary Access Time
PUT`/temporary-access/{id}/`

Replace all fields on a temporary access time. Unspecified fields will be set to their default values.

Python example

data = {
  "answer_required": False,
  "device_group": 1,
  "email_address": "joe@org3.net",
  "end": "2014-04-24T13:00:00",
  "first_name": "Joe",
  "last_name": "Smith",
  "start": "2014-04-24T11:00:00"
}
r = requests.put('https://suitabletech.com/admin-api/1/temporary-access/123/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PUT https://suitabletech.com/admin-api/1/temporary-access/ -F email_address=smith@org3.net -F first_name=Joe -F last_name=Smith -F device_group=10 -F start='2013-12-31T11:59:50' -F end='2014-01-01T00:10:00' -F answer_required=true -H Authorization:$APIKEY

Example URI

PUT /temporary-access/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the temporary access time

Response 204

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "The 'end' field has no data and doesn't allow a default or null value."
}

Response 404

Delete a Temporary Access Time
DELETE`/temporary-access/{id}/`

Delete a single temporary access time.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/temporary-access/123/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/temporary-access/123/' -H Authorization:$APIKEY

Example URI

DELETE /temporary-access/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the temporary access time

Response 204

Response 404

API Keys ¶

API keys are used to authenticate you when using the API, and are uniquely identified by their name parameter. Through the API you can delete existing keys, or create new ones.

API keys have the following fields:

Field	Type	Default	Description
`name`	string	(required)	A unique name provided when key was created
`prefix`	string	‘’	The public prefix of the key
`api_key`	string	‘’	The full API key, only shown when the key is first created

API Keys List ¶

Get API Keys
GET`/api-keys/`

Get a list of API keys.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/api-keys/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/api-keys/' -H Authorization:$APIKEY

Example URI

GET /api-keys/

Response 200

HideShow

Body

{
  "meta": {
    "limit": 1000,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "name": "default",
      "prefix": "APIKEY:nd0pWLoCy0gU"
    },
    {
      "name": "dev",
      "prefix": "APIKEY:DPhUV2KZm3Fp"
    }
  ]
}

Create an API Key
POST`/api-keys/`

Creates a new API key. The api_key parameter is returned in the response body, and should be stored securely.

Python example

data = {
  'name': 'production'
}
r = requests.post('https://suitabletech.com/admin-api/1/api-keys/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST https://suitabletech.com/admin-api/1/temporary-access/ -F name=production -H Authorization:$APIKEY

Example URI

POST /api-keys/

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "api_key": "APIKEY:htyZcGYpPnZp:n0d8M01Mg8Ze9cCiG0WRP6CvP++BKm69xehxkleSZPB/",
  "name": "default",
  "prefix": "APIKEY:htyZcGYpPnZp"
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "name: An API Key with that name already exists."
}

API Key ¶

Delete an API Key
DELETE`/api-keys/`

Delete an API key.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/api-keys/default/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/api-keys/default/' -H Authorization:$APIKEY

Example URI

DELETE /api-keys/

Response 204

Response 404

Access Time Templates ¶

Access time templates allow you to create pre-defined access time rules, which can be easily applied to device group memberships in your organization. Through the API you can create, edit, delete, and apply access time templates.

Access time templates can contain multiple access time template items, which can be combined additively to create more fine-grained access times for a template. For example, a template could have two access time templates: One could specify Monday - Friday 9:00 AM through 5:00 PM, while another could specify all day Saturday and Sunday.

Access time templates have the following fields:

Field	Type	Default	Description
`id`	integer	n/a	The access time template’s unique identifier
`name`	string	‘’	A name that identifies this access time template
`access_time_template_items`	list	[]	A list of access time template items (described below)

Access time template items have the following fields:

Field	Type	Default	Description
`id`	integer	n/a	The access time template items’s unique identifier
`sunday`	boolean	true	Whether users can call devices on Sunday
`monday`	boolean	true	Whether users can call devices on Monday
`tuesday`	boolean	true	Whether users can call devices on Tuesday
`wednesday`	boolean	true	Whether users can call devices on Wednesday
`thusday`	boolean	true	Whether users can call devices on Thursday
`friday`	boolean	true	Whether users can call devices on Friday
`saturday`	boolean	true	Whether users can call devices on Saturday
`start_time`	string	null	The beginning of the access time period in 24-hour HH:MM:SS format
`end_time`	string	null	The end of the access time period in 24-hour HH:MM:SS format
`answer_required`	boolean	false	Whether or not calls during this time period must be accepted on the receiving side

If start_time and end_time are omitted, the access time allows calling during the entire day (12:00 AM to 11:59 PM)

Access Time Templates List ¶

Get Access Time Templates
GET`/access-time-templates/`

Get a list of access time templates.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/access-time-templates/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/access-time-templates/' -H Authorization:$APIKEY

Example URI

GET /access-time-templates/

Response 200

HideShow

Body

{
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 1
  },
  "objects": [
    {
      "access_time_template_items": [
        {
          "access_time_template": "/admin-api/1/access-time-templates/1/",
          "answer_required": false,
          "end_time": null,
          "friday": false,
          "id": 1,
          "monday": false,
          "resource_uri": "",
          "saturday": true,
          "start_time": null,
          "sunday": false,
          "thursday": false,
          "tuesday": false,
          "wednesday": false
        },
        {
          "access_time_template": "/admin-api/1/access-time-templates/1/",
          "answer_required": false,
          "end_time": "17:00:00",
          "friday": true,
          "id": 2,
          "monday": true,
          "resource_uri": "",
          "saturday": false,
          "start_time": "09:00:00",
          "sunday": false,
          "thursday": true,
          "tuesday": true,
          "wednesday": true
        }
      ],
      "id": 1,
      "name": "Workdays and Saturday",
      "resource_uri": "/admin-api/1/access-time-templates/1/"
    }
  ]
}

Create an Access Time Template
POST`/access-time-templates/`

Creates a new access time template.

Python example

data = {
    'access_time_template_items': [
        {
            'answer_required': False,
            'end_time': None,
            'friday': False,
            'monday': True,
            'saturday': False,
            'start_time': None,
            'sunday': True,
            'thursday': False,
            'tuesday': False,
            'wednesday': False,
        },
    ],
    'name': "Workdays",
}

r = requests.post('https://suitabletech.com/admin-api/1/access-time-templates/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST https://suitabletech.com/admin-api/1/access-time-templates/ -d '{"access_time_template_items": [{"answer_required": false, "end_time": null, "friday": false, "monday": true, "saturday": false, "start_time": null, "sunday": true, "thursday": false, "tuesday": false, "wednesday": false}], "name": "Workdays"}' -H Authorization:$APIKEY -H "Content-Type: application/json"

Example URI

POST /access-time-templates/

Response 201

HideShow

Headers

Location: https://suitabletech.com/admin-api/1/access-time-templates/123/

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Access time template with name 'Workdays' already exists"
}

Access Time Template ¶

Get an Access Time Template
GET`/access-time-templates/{id}/`

Get a single access time template.

Python example

r = requests.get('https://suitabletech.com/admin-api/1/access-time-templates/10/', headers={'Authorization':APIKEY})

cURL example

curl -X GET 'https://suitabletech.com/admin-api/1/users/10/' -H Authorization:$APIKEY

Example URI

GET /access-time-templates/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the access time template

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "access_time_template_items": [
    {
      "access_time_template": "/admin-api/1/access-time-templates/1/",
      "answer_required": false,
      "end_time": null,
      "friday": false,
      "id": 1,
      "monday": false,
      "resource_uri": "",
      "saturday": true,
      "start_time": null,
      "sunday": false,
      "thursday": false,
      "tuesday": false,
      "wednesday": false
    },
    {
      "access_time_template": "/admin-api/1/access-time-templates/1/",
      "answer_required": false,
      "end_time": "17:00:00",
      "friday": true,
      "id": 2,
      "monday": true,
      "resource_uri": "",
      "saturday": false,
      "start_time": "09:00:00",
      "sunday": false,
      "thursday": true,
      "tuesday": true,
      "wednesday": true
    }
  ],
  "id": 1,
  "name": "Workdays and Saturday",
  "resource_uri": "/admin-api/1/access-time-templates/1/"
}

Response 404

Patch an Access Time Template
PATCH`/access-time-templates/{id}/`

Patch individual fields on an access time template.

Python example

data = {
  'name': 'Workday',
}
r = requests.patch('https://suitabletech.com/admin-api/1/access-time-templates/1/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X PATCH -F name='Workday' 'https://suitabletech.com/admin-api/1/access-time-templates/1/' -H Authorization:$APIKEY

Example URI

PATCH /access-time-templates/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the access time template

Response 202

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Access time template with name 'Workdays' already exists"
}

Response 404

Delete an Access Time Template
DELETE`/access-time-templates/{id}/`

Delete an access time template.

Python example

r = requests.delete('https://suitabletech.com/admin-api/1/access-time-templates/10/', headers={'Authorization':APIKEY})

cURL example

curl -X DELETE 'https://suitabletech.com/admin-api/1/access-time-templates/10/' -H Authorization:$APIKEY

Example URI

DELETE /access-time-templates/123/

URI Parameters

HideShow

id: integer (required) Example: 123
The ID of the access time template

Response 204

Response 404

Apply Access Time Template ¶

Apply Access Time Template
POST`/apply-access-time-templates/`

Apply an access time template to a specific device group membership.

Python example

data = {
  'access_time_template': 10,
  'device_group_membership': 20,
}
r = requests.post('https://suitabletech.com/admin-api/1/apply-access-time-template/', data=data, headers={'Authorization':APIKEY})

cURL example

curl -X POST https://suitabletech.com/admin-api/1/apply-access-time-template/ -F access_time_template=10 -F device_group_membership=20 -H Authorization:$APIKEY

Example URI

POST /apply-access-time-templates/

URI Parameters

HideShow

access_time_template: integer (required) Example: 6
The ID of the access time template
device_group_membership: integer (required) Example: 6
The ID of the device group membership

Response 201

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Device group membership with id '10' does not exist."
}

Overview ¶

API URIs ¶

API Key Authentication ¶

Making API Calls ¶

Collections and Pagination ¶

Info ¶

Info ¶

Get Organization InfoGET/info/

Example URI

Headers

Body

Users ¶

Users List ¶

Get UsersGET/users/

Example URI

Headers

Body

User ¶

Get a UserGET/users/{email}/

Example URI

Headers

Body

Patch a UserPATCH/users/{email}/

Example URI

Inviting Users ¶

Invite a User ¶

Invite a UserPOST/invite/

Example URI

Headers

Body

Headers

Body

Devices ¶

Device List ¶

Get DevicesGET/devices/

Example URI

Headers

Body

Device ¶

Get a DeviceGET/devices/{id}/

Example URI

Headers

Body

Patch a DevicePATCH/devices/{id}/

Example URI

Headers

Body

Update a DevicePUT/devices/{id}/

Example URI

Headers

Body

Device Groups ¶

Device Group List ¶

Get Device GroupsGET/device-groups/

Example URI

Headers

Body

Create a Device GroupPOST/device-groups/

Example URI

Headers

Headers

Body

Device Group ¶

Get a Device GroupGET/device-groups/{id}/

Example URI

Headers

Body

Patch a Device GroupPATCH/device-groups/{id}/

Example URI

Headers

Body

Update a Device GroupPUT/device-groups/{id}/

Example URI

Headers

Body

Delete a Device GroupDELETE/device-groups/{id}/

Example URI

User Groups ¶

User Group List ¶

Get User GroupsGET/user-groups/

Overview

API URIs

API Key Authentication

Making API Calls

Collections and Pagination

Get Organization Info
GET`/info/`

Get Users
GET`/users/`

Get a User
GET`/users/{email}/`

Patch a User
PATCH`/users/{email}/`

Invite a User
POST`/invite/`

Get Devices
GET`/devices/`

Get a Device
GET`/devices/{id}/`

Patch a Device
PATCH`/devices/{id}/`

Update a Device
PUT`/devices/{id}/`

Get Device Groups
GET`/device-groups/`

Create a Device Group
POST`/device-groups/`

Get a Device Group
GET`/device-groups/{id}/`

Patch a Device Group
PATCH`/device-groups/{id}/`

Update a Device Group
PUT`/device-groups/{id}/`

Delete a Device Group
DELETE`/device-groups/{id}/`

Get User Groups
GET`/user-groups/`

Create a user Group
POST`/user-groups/`

Get a User Group
GET`/user-groups/{id}/`

Patch a User Group
PATCH`/user-groups/{id}/`

Update a User Group
PUT`/user-groups/{id}/`

Delete a User Group
DELETE`/user-groups/{id}/`

Get Device Group Memberships
GET`/device-group-memberships/`

Create a Device Group Membership
POST`/device-group-memberships/`

Create Multiple
PATCH`/device-group-memberships/`

Get a Device Group Membership
GET`/device-group-memberships/{id}/`

Patch a Device Group Membership
PATCH`/device-group-memberships/{id}/`

Update a Device Group Membership
PUT`/device-group-memberships/{id}/`

Delete a Device Group Membership
DELETE`/device-group-memberships/{id}/`

Get Access Times
GET`/access-times/`

Create an Access Time
POST`/access-times/`