FIVE CRM API v2
Please see the following link to this information on a PDF document - http://fivecrm.com/downloads/apitechnicalreferencev2.pdf
This API endpoint is available to all FIVE CRM system types.
Base API endpoint url is as follows: <path to FIVE CRM installation>/api2.php (e.g. https://europeX.fivecrm.com/12345/api2.php)
All data returned from this API endpoint will be in JSON format.
Global Parameters
All methods on this API endpoint require the following parameters.
Parameter | Description | Data Type | Parameter Type (GET/POST) | Required |
mode | The API mode to use. This must be one of the available API modes detailed in the 'API Modes' section. | string | GET or POST | Yes |
hash | A valid API authentication hash (used to authenticate the request). | String | GET or POST | Yes |
API Modes
As mentioned above this API endpoint requires you to specify an API mode to use. This API mode can be one of the following.
API Mode Name | Description |
getPrivacyDetails | Used to retrieve privacy details from the system based on search criteria provided. E.g. get all privacy details where the account name is equal to 'FIVE CRM'. |
Global Error Messages
The following error messages can be returned by any of the API modes.
Message | Description |
System has expired | The system has expired, i.e. is no longer being paid for. |
No API mode specified | An empty 'mode' parameter was provided. |
Unknown API mode specified | An unknown API mode was specified. Valid API modes are listed in the API modes section. |
Example Return data
{
"STATUS": "error",
"ERROR": "No API mode specified"
}
API Mode - getPrivacyDetails
This API mode endpoint can be used to retrieve privacy details for particular contacts based on the criteria specified.
Request Data
Below are the available parameters which can be provided. These are in addition to the global parameters. 'area' is the only required field which must be provided as part of the request, however at least one of the optional parameters must be provided. Multiple optional parameters can be provided on the same request. When providing multiple optional parameters, the parameters will be combined and the search will be performed based on a Contact who matches all of the criteria.
Parameter | Description | Data Type | Parameter Type (GET/POST) | Required |
area | The database area | String | GET | Yes |
contName | A contact's name | String | GET | No, however at least one of the optional parameters must be provided. |
contEmail | A contact's email address | String | GET | No, however at least one of the optional parameters must be provided. |
contExternalContactId | A contact's external id | String | GET | No, however at least one of the optional parameters must be provided. |
contTelephone | A contact's telephone OR mobile number | String | GET | No, however at least one of the optional parameters must be provided. |
accCompany | A company/account name | String | GET | No, however at least one of the optional parameters must be provided. |
accExtLeadId | An account's external lead id | String | GET | No, however at least one of the optional parameters must be provided. |
accExtAccountId | An account's external account id | String | GET | No, however at least one of the optional parameters must be provided. |
accPostcode | An account's postcode | String | GET | No, however at least one of the optional parameters must be provided. |
Successful Request Return Data
If the request is successful then the returned data will follow the structure below.
Field | Parent | Description | Data Type |
STATUS | N/A | Whether or not the request was successful. 'success' when the request was successful. | string |
CONTACTS | N/A | An array of arrays of those contact who match the search criteria. | array |
ID | CONTACTS | The contact's system id. This is used to be able to differentiate between contacts. | string |
ACCOUNT | CONTACTS | The account number the contact belongs to. | string |
PRIVACY DETAILS | CONTACTS | An array of arrays of the privacy details for the contact. | string |
LAWFUL_TYPE | PRIVACY_DETAILS | The lawful type for the privacy detail. | array |
START_DATE | PRIVACY_DETAILS | The date when the privacy detail starts. All dates and times are in UTC. | string |
END_DATE | PRIVACY_DETAILS | The date when the privacy detail ends. All dates and times are in UTC. | string |
ADDITIONAL_INFO | PRIVACY_DETAILS | Any additional information provided for the privacy detail. | string |
WITHDRAWN_DATE | PRIVACY_DETAILS | The date when the privacy detail was withdrawn. In scenarios where the privacy detail is not withdrawn this will be empty. All dates and times are in UTC. | string |
PROCESSING_DETAILS | PRIVACY_DETAILS | An array of processing details for the privacy details. These are the channel and categories which have been selected in the privacy detail. The index of the array will be the category within each category will be the channels selected for that particular category. Each selected category will have its own array of channels selected. | array |
Example Return Data
{
"STATUS": "success",
"CONTACTS": [
{
"ID": "1",
"ACCOUNT": "1",
"PRIVACY_DETAILS": [
{
"LAWFUL_TYPE": "Consent",
"START_DATE": "2017-09-06 21:00:00",
"END_DATE": "2017-09-15 20:59:59",
"ADDITIONAL_INFO": "",
"WITHDRAWN_DATE": "2017-09-15 20:59:59",
"PROCESSING_DETAILS": {
"Car Insurance": [
"Email Tracking",
"Emails",
"Phone"
],
"Home Insurance": [
"Phone"
]
}
}
]
}
]
}
Failed Request Return Data
Field | Parent | Description | Data Type |
STATUS | N/A | Whether or not the request was successful. 'Error' when the request was unsuccessful. | string |
ERROR | N/A | An error message explaining why the request was unsuccessful. This can be one of the error messages listed below. | string |
Example Return Data
{
"STATUS": "error",
"ERROR": "The specified database area does not exist"
}
Error Messages
Below are the specific error messages which con be returned by this API mode endpoint.
Please note that any global error messages can also be returned.
Message | Description |
Unauthorised | The provided API authentication hash did not match any known hash in the system. |
No database area has been specified | No 'area' parameter was specified in the request. |
The specified database area does not exist | The 'area' parameter specified was not a valid database area. |
At least one search criteria must be specified | No optional parameters were provided with the request. |
Unable to locate any matching contacts | No contacts could be found matching the specified search criteria. |
An unexpected error occurred during contact acquisition | There was an internal API error when trying to retrieve the Privacy Details. |
Code Examples
Javascript (with jQuery)
$(function() {
$.ajax(
{
url: 'yourSystemUrl/api2.php?' +
'mode=' + encodeURIComponent('getPrivacyDetails') +
'&area=' + encodeURIComponent('001') +
'&contName=' + encodeURIComponent('Test Contact Name') +
'&companyName=' + encodeURIComponent('Test Company Name'),
data: {
hash: '86ab15zaf95c3431ac68e115f515g1a0'
},
type: 'POST',
dataType: 'json',
success: function(response) {
//Manage the returned data.
}
}
);
});
PHP
<?php
$baseUrl = 'yourSystemUrl/api2.php';
$getRequestData = array(
'mode' => 'getPrivacyDetails',
'area' => '001',
'contEmail' => 'test@example.com'
);
$postRequestData = array(
'hash' => '86ab15zaf95c3431ac68e115f515g1a0',
);
$url = $baseUrl . '?' . http_build_query($getRequestData);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt(
$curl,
CURLOPT_POSTFIELDS,
http_build_query($postRequestData)
);
$response = curl_exec($curl);
curl_close($curl);
$decodedResponse = json_decode($response, true);
//Manage the response using $decodedResponse