Overview

This guide walks you through managing technician resources in the Take Control platform. The Technician API allows you to create, manage, and update technician accounts. In this guide, you'll learn how to:

1. Create a single technician account
2. Create multiple technician accounts in bulk
3. Modify technician account status

Create Technician

To add a new technician to the Take Control system, use the Create Technician endpoint. This allows you to set up a new technician with their basic information, preferred language, and timezone settings.

Required Parameters:

• email: The technician's email address (serves as username)
• name: The technician's full name

Optional Parameters:

• profile: The technician's role (e.g., "admin")
• language: Preferred interface language (e.g., "de" for German)
• timezone: The technician's timezone (e.g., "Europe/Lisbon")

Request

POST /tech
Authorization: INTEGRATION-KEY your-private-key
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "John Doe",
  "profile": "admin",
  "language": "de",
  "timezone": "Europe/Lisbon"
}

This request creates a new technician account for John Doe with administrator privileges, German language preference, and European/Lisbon timezone setting.

Response

A successful creation returns a 200 status code along with confirmation details:

{
  "result": "SUCCESS",
  "details": {},
  "errorDetails": null
}

Create Multiple Technicians

For efficiently onboarding multiple technicians at once, use the Bulk Create endpoint. This endpoint accepts an array of technician objects with the same parameters as individual creation.

Request

POST /tech/bulk
Authorization: INTEGRATION-KEY your-private-key
Content-Type: application/json

[
  {
    "email": "[email protected]",
    "name": "Tech One",
    "profile": "admin",
    "language": "en"
  },
  {
    "email": "[email protected]",
    "name": "Tech Two",
    "profile": "support",
    "language": "fr"
  }
]

This request creates two technician accounts:

1. Tech One: Administrator with English language preference
2. Tech Two: Support role with French language preference

Response

The response includes creation status for each technician:

{
  "result": "SUCCESS",
  "details": {
    "technicians": {
      "[email protected]": {
        "result": "SUCCESS"
      },
      "[email protected]": {
        "result": "SUCCESS"
      }
    }
  }
}

Modify Technician Status

To update an existing technician's account status (enable/disable), use the Modify Technician endpoint.

Required Parameters:

• techUsername: The technician's email address
• status: New account status ("enabled" or "disabled")

Request

PUT /tech/{techUsername}
Authorization: INTEGRATION-KEY your-private-key
Content-Type: application/json

{
  "status": "disabled"
}

This request disables the specified technician's account, preventing them from accessing the system while maintaining their account configuration.

Response

{
  "result": "SUCCESS",
  "details": {},
  "errorDetails": null
}

Error Handling

The API uses standard HTTP status codes and includes detailed error information:

• 400 Bad Request: Invalid parameters or format

  JSON

  {
    "status": 400,
    "message": "Invalid request: Email must not be empty"
  }
  

• 403 Forbidden: Invalid integration key

  JSON

  {
    "status": 403,
    "message": "Invalid integration key"
  }
  

• 409 Conflict: Email already exists

  JSON

  {
    "status": 409,
    "message": "Email already exists"
  }
  

• 429 Too Many Requests: Rate limit exceeded

  JSON

  {
    "status": 429,
    "message": "Too many requests"
  }