Calls to the API must be for genuine use and responses from the API must not be stored for the purpose of creating an offline copy of the information stored. Failure to comply with this requirement will infringe the API License.
API Usage
Note:All examples throughout this documentation use the CURL library from the command line. You MUST send correct headers. If you use CURL from the command line, shell script or via a library in the programming language of your choice then using CURL's authentication methods will automatically generate the right HTTP headers for your requests. You only need to be concerned about these if you are handling socket communications yourself or via a less sohpisticated library.
API Protocol
API requests are JSON. They are sent to the API using a HTTP connection over SSL using all four verbs (GET, PUT, POST and DELETE).
The JSON request data must be contained within the request body. The JSON must be well formed and valid. It must not contain any special characters. In the event that a special character needs to be sent to the API (perhaps as a name with accented characters) then that character should be replaced with the unicode conversion of that character. A list of unicode character codes can be found here: http://en.wikipedia.org/wiki/List_of_Unicode_characters.
Unicode characters must be in the format "\u####". As an example: è (unicode character U+00E8) would be converted to \u00e8 before being sent to the API.
Some requests are synchronous, that is, the API Client must send the request to the API and wait for a response. In the event of network issues beyond CheckMEND’s control (for example, a nework problem at the client API end) it may not be possible to make a connection so the API Client must include a timeout (we suggest 3 seconds) after which it will determine that the service is not available and should fall through to a default state suitable to the business processes of the relevant Organisation.
Some requests are asynchronous. These are typically requests that are computationally and data intensive such as PDF CheckMEND certificate generation. Reports also for example. Since these are human readable rather than machine readable, they are queued and processed sequentially to ensure that performance is not compromised. Asynchronous methods support callback URLs and will document a callback JSON response. Typically if an email address is given instead of or as well as a callback rather than a URL then the resulting file or report will be emailed to that address.
Please read the method documentation carefully. When using callbacks your systems must be able to receive the data and within 3 seconds provide a response acknowledging receipt. If that response is not received within 3 seconds or is in an invalid format then the requests will go to the back of the queue a maximum of 3 further times after which we will mark it as failed and cease trying to deliver it.
All examples are shown using Curl to send the request unless otherwise stated.
Security Requirements
All requests to this API must be made over HTTPS. Requests to HTTP will be redirected to HTTPS.
The minimum supported protocol for communicating to the API is TLSv1.2 (TLSv1.3 will be available soon). SSLv3, TLSv1.0 and TLSv1.1 are not supported. We recommend where possible you avoid specifying the TLS protocol version in your code and instead use the maximum version supported by your operating system. Where this is not possible, please specify TLSv1.2.
Authentication
Calls to the API are managed using HTTP authentication (Only "Basic" is currently supported). Every request must include the Authorisation HTTP header containing username and password. The username is your Account ID (previously known as Partner ID) and your password is a per-request, calculated signature hash.
Example
curl -H 'Accept: application/json' -H 'Content-Type: application/json' \
-u 123:XXXXXXXXXXXXXXXXXXXXXX \
-d '...JSON request object goes here...' https://gapi.checkmend.com/{method}
Your Account ID is given to you by Recipero Support when you have a license agreement in place with us. At the same time you will be given a secret key known only to you and us. This key is used to generate your signature hash.
How to generate your signature hash.
Once you have constructed your CheckMEND request you should append to it the end of the secret key you have been given and compute a hexadecimal SHA1 hash of the result.
Example
Secret Key: 234623ger787qws3423
Request Body: {"category":1}
The signature hash generation begins with the request body being appended to the secret key:-
234623ger787qws3423{"category":1}
An SHA1 hash is then calculated using the resulting string:
6b1fc03270e578a9765c364bd622e6dd293d4e8b
The Authorization header is then generated by combining the Account ID with the Signature Hash:
123:6b1fc03270e578a9765c364bd622e6dd293d4e8b
This itself is then Base64 encoded. This will be handled automatically if you are using a curl
client library within PHP, C# etc.
MTIzOjZiMWZjMDMyNzBlNTc4YTk3NjVjMzY0YmQ2MjJlNmRkMjkzZDRlOGI=
A complete authorisation header with the encoded credentials should look like this:
Authorization: Basic MTIzOjZiMWZjMDMyNzBlNTc4YTk3NjVjMzY0YmQ2MjJlNmRkMjkzZDRlOGI=
Below is an example of the full HTTP request:-
POST /duediligence/1/45523354232323424 HTTP/1.1
Authorization: Basic MTIzOjZiMWZjMDMyNzBlNTc4YTk3NjVjMzY0YmQ2MjJlNmRkMjkzZDRlOGI=
User-Agent: curl/7.21.3
Host: gapi.checkmend.com
Accept: application/json
Content-Type: application/json
Content-Length: 15
{"category": 8}
Since we know your secret key too, we calculate what it should be given the content you have sent us and if we agree then we can be sure that the sender of the message was aware of the secret key AND that the contents of the message have not been altered in transit. These are both important security considerations. Of course the whole transaction is encrypted using SSL anyway so content is not readily readable in transit but we must err on the side of security.
PHP Example
Below is a simplified example using PHP to generate the signature hash. Similar steps can be taken in other programming languages.
// Replace with your Account ID
$accountId = 123;
// Replace with your secret key
$secretKey = '234623ger787qws3423';
// Set up the request body
$requestData = ['category' => 1];
$requestBody = json_encode($requestData);
// This is your signature hash, which can be used as the Basic Auth Password with
// your chosen HTTP Client.
// Expected value for this example would be:
$signatureHash = sha1($secretKey . $requestBody);