×

UNMS - CRM: API Usage

Overview

This article explains the purpose of the API for the UNMS CRM module and demonstrates its usage with a simple example script.

NOTES & REQUIREMENTS:
  • This article focuses on the CRM module that is included in UNMS.
  • Join the UNMS discussion on the Ubiquiti Communityand interact with other experts that are active on forum.
  • 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 on in the UNMS CRM - Plugins article and on GitHub.

Table of Contents

  1. Using the API
  2. API Information and Documentation
  3. Example Script
  4. Related Articles

Using the API

Back to Top

The UNMS CRM module provides an API to import, retrieve or update any data stored in the UNMS 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

Back to Top

  • API doc for the stable version of UNMS CRM module can be found at unmscrm.docs.apiary.io
  • API doc for the beta version of UNMS CRM module can be found at ucrmbeta.docs.apiary.io
  • API doc for UCRM v2 can be found at ucrm.docs.apiary.io
  • The API documentation for the UNMS Network module is available at the https://hostname/api-docs/ address on each controller.

Script authentication tokens can be generated in the  settings.png  Settings > Users > API tokens section.

Example Script

Back to Top

Below is a PHP example script which 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;

Related Articles

Back to Top

UNMS - CRM: Plugins

UNMS - How to Upgrade from UCRM to UNMS

Was this article helpful?
0 out of 1 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community
Can't find what you're looking for?