UISP - CRM: API Usage
Overview
This article explains the purpose of the API for the UISP CRM module and demonstrates its usage with a simple example script.
- This article focuses on the CRM module that is included in UISP.
- The API is intended to be used by advanced users who possess the tools and scripting knowledge necessary to develop and execute their own API scripts.
- For those who do not wish to develop their own scripts, we recommend using the available plugins instead. More information on CRM plugins can be found in the UISP CRM - Plugins article and on GitHub.
Table of Contents
Using the API
The UISP CRM module provides an API to import, retrieve, or update any data stored in the UISP CRM database. The API can be used to:
Batch imports of large data
For example, importing thousands of clients at once.Batch exports
For example, exporting invoices and payments.Update existing entities
For example, change any invoicing attribute for all clients.Control
The API also enables you to manage the shaping or suspending of any vendor's devices.
API Information and Documentation
- API doc for the stable version of UISP CRM module can be found at unmscrm.docs.apiary.io
- API doc for the beta version of the UISP CRM module can be found at ucrmbeta.docs.apiary.io
- The API documentation for the UISP Network module is available at the https://hostname/api-docs/ address on each console.
Script authentication tokens can be generated in the Settings > Users > API tokens section.
Example Script
Below is a PHP example script that demonstrates how to update all the clients in the CRM module. In the script, a simple class called UcrmApiAccess is used which handles the connection and commands processing. You don't need to change this class.
1. First, all the clients are retrieved from CRM.
2. Then, each client is processed one by one. In this case, there are 4 invoicing attributes set to null for each client.
3. Use the script to modify whatever you need, such as updating client addresses or setting a default tax for a subset of your clients.
4. To use this script with your CRM instance, change the API_URL and APP_KEY constants to your values. The values can be found in the CRM > System > Security > App keys section.
<?php
class UcrmApiAccess
{
const API_URL = 'https://unms.ui.com/api/v1.0';
const APP_KEY = '5YbpCSto7ffl/P/veJ/GK3U7K7zH6ZoHil7j5dorerSN8o+rlJJq6X/uFGZQF2WL';
/**
* @param string $url
* @param string $method
* @param array $post
*
* @return array|null
*/
public static function doRequest($url, $method = 'GET', $post = [])
{
$method = strtoupper($method);
$ch = curl_init();
curl_setopt(
$ch,
CURLOPT_URL,
sprintf(
'%s/%s',
self::API_URL,
$url
)
);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt(
$ch,
CURLOPT_HTTPHEADER,
[
'Content-Type: application/json',
sprintf('X-Auth-App-Key: %s', self::APP_KEY),
]
);
if ($method === 'POST') {
curl_setopt($ch, CURLOPT_POST, true);
} elseif ($method !== 'GET') {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
}
if (! empty($post)) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post));
}
$response = curl_exec($ch);
if (curl_errno($ch) !== 0) {
echo sprintf('Curl error: %s', curl_error($ch)) . PHP_EOL;
}
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
echo sprintf('API error: %s', $response) . PHP_EOL;
$response = false;
}
curl_close($ch);
return $response !== false ? json_decode($response, true) : null;
}
}
// Setting unlimited time limit (updating lots of clients can take a long time).
set_time_limit(0);
if (php_sapi_name() !== 'cli') {
echo '<pre>';
}
// Get collection of all Clients.
$clients = UcrmApiAccess::doRequest('clients') ?: [];
echo sprintf('Found %d clients.', count($clients)) . PHP_EOL;
// Go through all Clients and update them.
// In this case we are updating all invoice options to use system defaults.
foreach ($clients as $client) {
$response = UcrmApiAccess::doRequest(
sprintf('clients/%d', $client['id']),
'PATCH',
[
'sendInvoiceByPost' => null,
'invoiceMaturityDays' => null,
'stopServiceDue' => null,
'stopServiceDueDays' => null,
]
);
if ($response !== null) {
echo sprintf('Client ID %d successfully updated.', $client['id']) . PHP_EOL;
} else {
echo sprintf('There was an error in updating client ID %d.', $client['id']) . PHP_EOL;
}
}
echo 'Done.' . PHP_EOL;