Overview

The Device API endpoints allow you to manage device installers and device groups within Take Control. This guide walks you through each endpoint with examples for creating device installers, managing device groups, and organizing your device hierarchy.

API Methods

Create Device Installer

Creates a new device installer with specific configuration settings including device name, type, and group assignment.

Required Parameters:

• device_name: Name for the device
• device_type: Type of device (integer 0-4)
• group_id: ID of the group to associate the device with

Optional Parameters:

• customer_name: Name of the customer
• customer_email: Customer's email address
• customer_number: Customer's reference number
• max_installs: Maximum number of allowed installations
• link_expiration_date: When the installer link expires

Request Example

POST https://api.us0.swi-rc.com/rest/device/installer
Authorization: Bearer <YOUR_INTEGRATION_KEY>
Content-Type: application/json

{
  "device_name": "My Laptop",
  "device_type": 2,
  "group_id": 1453,
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "max_installs": 10,
  "link_expiration_date": "2048-12-31 23:59:59"
}

This request creates a new device installer for a laptop, assigning it to group 1453. The installer will be limited to 10 installations and will expire at the end of 2048. It includes customer information for tracking purposes.

Response

{
  "result": "SUCCESS",
  "details": {
    "install_uniqueid": "bc-11395c7cf44ed-us1-LLRsQ4wS7DmHfgJV7cOz4v6J-a-15",
    "computer_name": "My Laptop",
    "install_link": "https://startcontrol.swi-rc.com/s/yPQH",
    "pin_number": 103298443,
    "c_name": "John Doe",
    "c_email": "[email protected]"
  }
}

List Device Groups

Retrieves a list of all device groups and their hierarchy information.

Optional Query Parameters:

• pageNumber: Page number for pagination (starts at 1)
• pageSize: Number of items per page
• sortBy: Field to sort by
• sortOrder: Sort direction (ASC/DESC)

Request Example

GET https://api.us0.swi-rc.com/rest/device/group
Authorization: Bearer <YOUR_INTEGRATION_KEY>

This request retrieves all device groups with default pagination settings.

Response

{
  "result": "SUCCESS",
  "details": [
    {
      "id": 12604,
      "idgroup_pai": 0,
      "groupname": "My Main Group"
    }
  ]
}

Create Device Group

Creates a new device group within your organization hierarchy.

Required Parameters:

• parent_group_id: ID of the parent group
• group_name: Name for the new group

Request Example

POST https://api.us0.swi-rc.com/rest/device/group
Authorization: Bearer <YOUR_INTEGRATION_KEY>
Content-Type: application/json

{
  "parent_group_id": 0,
  "group_name": "My Main Group"
}

This request creates a new top-level device group (parent_group_id: 0) named "My Main Group".

Response

{
  "result": "SUCCESS",
  "details": 12619
}

The response includes the ID of the newly created group.

Edit Device Group

Modifies an existing device group's name or parent group.

Required Parameters:

Either parent_group_id or group_name (or both) must be provided:

• parent_group_id: New parent group ID
• group_name: New name for the group

Request Example

PUT https://api.us0.swi-rc.com/rest/device/group/{groupId}
Authorization: Bearer <YOUR_INTEGRATION_KEY>
Content-Type: application/json

{
  "parent_group_id": 12604,
  "group_name": "Updated Group Name"
}

This request moves the group to a new parent (12604) and updates its name.

Response

{
  "result": "SUCCESS",
  "details": 12619
}

Delete Device Group

Removes a device group from your organization.

Request Example

DELETE https://api.us0.swi-rc.com/rest/device/group/{groupId}
Authorization: Bearer <YOUR_INTEGRATION_KEY>

This request permanently deletes the specified device group.

Response

{
  "result": "SUCCESS",
  "details": 12619
}

Error Responses

All endpoints may return the following error responses:

{
  "result": "ERROR",
  "errorDetails": {
    "errorCode": 400,
    "errorMsg": "Invalid request parameters"
  }
}

Common error codes:

• 400: Invalid request
• 403: Invalid integration key
• 429: Too many requests
• 500: Internal server error