Overview

This quickstart guide will walk you through the essential steps to get started with the Take Control API using our interactive API Reference. You'll learn how to create a session, submit a support ticket, add a new technician, and create a device installer. Each step includes a practical example with explanations of the API call, its response, and key details.

Before You Start

Before diving into the API calls, ensure you have:

1. Registered for a N-Able Take Control account.
2. Obtained your API keys from the Dashboard
3. Tools for testing:
   • Postman: An easy tool for making API calls without coding.
   • API Reference: Visit our API Reference to see all available endpoints and try them live.

📘

Note

Remember to replace your_public_integration_key_here and your_private_integration_key_here with your actual integration keys when making these requests. Always use the correct key type (public or private) as specified in each example.

Step 1: Create a New Session

Creating a session is typically the first step in initiating a support interaction through Take Control. Call CreateNewSession to create a new support session, associating it with a specific department, technician, and customer. It sets up the initial parameters for the support interaction.

Example Request

curl --request POST \
     --url https://api.us0.swi-rc.com/rest/session \
     --header 'INTEGRATION-KEY: int-key-54321' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "department_id": "id_1234",
  "technician_username": "user123",
  "language": "en",
  "customer_name": "Sandy Smith",
  "customer_email": "[email protected]",
  "customer_number": "d4f%d$3"
}
'

Example Response

{
  "result": "SUCCESS",
  "details": {
    // Specific session details 
  },
  "errorDetails": null
}

Key response details

• The details object

Step 2: Create a Support Ticket

Creating a support ticket allows you to log and track customer issues even when immediate action isn't required. Call CreateSupportTicket to create a new support ticket in the system, recording the customer's information and the nature of their problem.

Example Request

POST /ticket
INTEGRATION-KEY: your_public_integration_key_here
Content-Type: application/json

{
  "ids": 1,
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "problem_description": "Unable to access network drives"
}

Example Response

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

Key response details

• ticket_number: A unique identifier for the created ticket, which can be used for future reference and tracking

Step 3: Create a New Technician

Adding a new technician to your Take Control environment allows you to expand your support team. Call CreateTechnician to create a new technician account in your Take Control system, setting up their basic profile information.

Example Request

POST /tech
INTEGRATION-KEY: your_private_integration_key_here
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "Jane Doe",
  "profile": "admin",
  "language": "en",
  "timezone": "America/New_York"
}

Example Response

{
  "result": "SUCCESS",
  "details": {
    // Specific details about the Technician Request
  },
  "errorDetails": null
}

Key response details

• The details object

Step 4: Create a New Device Installer

Creating a device installer allows you to set up new devices in your Take Control environment easily. To generate a device installer call CreateInstaller to set up Take Control on a specific device. It associates the device with a customer and sets parameters like the maximum number of installations and an expiration date for the installer link.

Example Request

POST /device/installer
INTEGRATION-KEY: your_private_integration_key_here
Content-Type: application/json

{
  "device_name": "Marketing Laptop",
  "device_type": 2,
  "group_id": 12619,
  "customer_name": "Jane Smith",
  "customer_email": "[email protected]",
  "max_installs": 1,
  "link_expiration_date": "2024-12-31 23:59:59"
}

Example Response

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

Key response details

• install_uniqueid: A unique identifier for this installer
• install_link: A URL that can be used to download and run the installer
• pin_number: A PIN that may be required during the installation process
• Device and customer information as confirmed by the system

Handling API Responses

When making API requests, it's essential to handle responses correctly:

• Check Status Codes: Ensure the request was successful by checking HTTP status codes (e.g., 200 for success).
• Parse JSON: Most APIs return data in JSON format. Use appropriate methods to parse JSON data in your programming language.

Error Handling

• Ensure your application can gracefully handle errors, such as network issues or invalid responses:
• Retry Logic: Implement retry logic for transient errors.
• Error Messages: Display user-friendly error messages.