User Manual

API

api_demo page at https://www.cuforms.org.uk/api_demo/api_call.php

Authentication

Authorisation is performed by sending the following HTTP Headers:

Key — This is the ID of your organisation (usually a 2 or 3 digit number)

Sign — POST data (?param=val&param1=val1) signed by a secret key (set on the Account Administration screen) according to the HMAC-SHA512 method

POST parameters are used to pass:

• nonce with increment integer. (>0)
• method name
• method parameters

Sent via POST on https://cuforms.org.uk/api

Responses are in JSON format (following the JSEND specification)

If the API call is successful, the response will be formatted like this:

{“status”:“success”,“data”:{<return>}}

If the API call is successful, the response will be formatted like this:

{“status”:“fail”,“data”:{<error message>}}

Methods

Method=FORM

Returns a single form, or all forms for a given form template

Parameters

env - live, uat or demo (default='live') article_id - form template ID form_id - form ID

• IF neither ID is present, API will return all forms relating to this org_id
• IF only article_id is present, API will return all forms for that form template
• IF both article_id and form_id are present, API will return all forms for that form template where form_id >= the passed ID
• IF only form_id is present, API will return just that form

Response

Sample response

{
  "status":"success",
  "data":{
    "forms":[
      {"article_id":"571",
      "article_form_id":"71",
      "article_form_timestamp":"2016-04-19 01:03:16",
      "article_form_ip_address":"99.999.999.999",
      "article_form_agent":"",
      "Bankruptcy":"Y",
      "person_title":"Mr",
      "person_first_names":"Blogs",
      "person_last_name":"Fred",
      "person_dob":"1992-04-24"}
    ]
  }
}

Method=ACTION

Returns audited actions on a single form, or all forms for a given form template, for a given period

Parameters

env - live, uat or demo (default='live') article_id - form template ID form_id - form ID action_id - audit action ID to start search action_timestamp - date and time (YYYY-MM-DD hh:mm:ss) to start search

• Logic for article_id and form_id as for method FORM
• IF action_id and action_timestamp are omitted, form_id must be present

Response

Sample response

{
  "status":"success",
  "data":{
    "forms":[
      {"article_id":"571",
      "article_form_id":"71",

  "status":"success",
  "data":{
    "actions":[
      {"article_id":"571",
      "form_id":"71",
      "action_id":"170",
      "form_timestamp":"2016-04-19 01:03:16",
      "action_timestamp":"2016-04-19 01:28:32",
      "action_type":"CHANGE"},
      {"article_id":"571",
      "form_id":"71",
      "action_id":"171",
      "form_timestamp":"2016-04-19 01:03:16",
      "action_timestamp":"2016-04-19 01:28:32",
      "action_type":"CHANGE"}
      ]
    }
  }
}

nb: Where fields are defined as belonging to the standard library (eg LIB=person_first_name), the library field name will be returned in the response, otherwise the description defined in the form builder will be used.

PHP Example (will query the cuForms demo system)

<?
function cuforms_api($method, array $req = array()) {
        // API settings
        $org_id = '14'; // your org_id
        $api_key = 'key_demo_14'; // your API-KEY set in Account Administration
 
        $req['method'] = $method;
        $mt = explode(' ', microtime());
        $req['nonce'] = $mt[1];
       
        // generate the POST data string
        $post_data = http_build_query($req, '', '&');
 
        $sign = hash_hmac("sha512", $post_data, $api_key);
 
        // generate the extra headers
        $headers = array(
                'Sign: '.$sign,
                'Key: '.$org_id,
        );
 
        // our curl handle (initialize if required)
        static $ch = null;
        if (is_null($ch)) {
                $ch = curl_init();
                curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
                curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; cuForms PHP client; '.php_uname('s').'; PHP/'.phpversion().')');
        }
        curl_setopt($ch, CURLOPT_URL, 'https://www.cuforms.org.uk/api/index.php');
        curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
 
        // run the query
        $res = curl_exec($ch);

        if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
        $dec = json_decode($res, true);
		
        if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
        return $dec;
}
 
$result = cuforms_api("FORM", array("env"=>"demo")); // All forms
//$result = cuforms_api("FORM", array("env"=>"demo","form_id" => "71")); // form_id=71
//$result = cuforms_api("FORM", array("env"=>"demo","article_id" => "571")); // all forms where article_id=571
//$result = cuforms_api("FORM", array("env"=>"demo","article_id" => "571","form_id" => "69")); // all forms where article_id=571 and form_id>=69

//$result = cuforms_api("ACTION", array("env"=>"demo","article_id" => "571","action_timestamp" => "2016-04-19 00:00:00")); // all action on article_id=571 since 1-April-2016
//$result = cuforms_api("ACTION", array("env"=>"demo","form_id" => "71","action_id" => "170")); // all action on article_id=571 since action_id=170
 
echo "<pre>".print_r($result, true)."</pre>";
?>