Global property history reporting and due-diligence API

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.

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 Partner ID and your password is your 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 Partner ID is given to you by CheckMEND 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": 8}


The signature hash generation begins with the request body being appended to the secret key:-

234623ger787qws3423{"category": 8}


An SHA1 hash is then calculated using the resulting string:

ff6023602695580743f84feb8f2750de89e0d3d6


The Authorization header is then generated by combining the Partner ID with the Signature Hash:

1:ff6023602695580743f84feb8f2750de89e0d3d6


This itself is then Base64 encoded. This will be handled automatically if you are using a curl client library within PHP, C# etc.

MTpmZjYwMjM2MDI2OTU1ODA3NDNmODRmZWI4ZjI3NTBkZTg5ZTBkM2Q2


A complete authorisation header with the encoded credentials should look like this:

Authorization: Basic MTpmZjYwMjM2MDI2OTU1ODA3NDNmODRmZWI4ZjI3NTBkZTg5ZTBkM2Q2


Below is an example of the full HTTP request:-


POST /duediligence/1/45523354232323424 HTTP/1.1
Authorization: Basic MTpmZjYwMjM2MDI2OTU1ODA3NDNmODRmZWI4ZjI3NTBkZTg5ZTBkM2Q2
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.