Sections

• Overview
• API Usage
• Errors

Endpoints

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.

Certificate API Calls

Request Certificate

POST /certificate/{certid}

Purpose

To request a certificate from a due diligence check. This method is asynchronous and will not return the certificate immediately. Instead, you supply the method with a callback URL or an email address (or both) and the certificate will be sent to them once the request has been processed.

Inputs

• certid - The valid ID of a due diligence check.

And one or both of the following:-

• url - A callback URL which you would like us to send the certificate to. We will use a curl HTTP POST to transmit the file data and wait for a 200 OK HTTP response header. If we do not receive a response then we will retry a maximum of 3 times. If we receive a response but it is not a 200 OK, then we will give up. The request will be considered handled but marked as a failure.
• email - If you provide us with an email address then we will send the certificate attached to the email. The duediligenceid will be contained in subject line of the email. Once an email is sent the mail servers will attempt to deliver it for a upto 24 hours. If the email fails, it will not be retried.

Example Request

POST /certificate/{certid} HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "url": "...a valid callback url...",
    "email": "...a valid email address..."
}

Output

On receipt of a valid request we will respond with a 202 Accepted. This confirms that we have successfully queued your request. If there is a problem, a JSON object containing an errors array will be returned. For details on the errors array please read the Errors page.

Example Response (To initial request)

Response on Success:

HTTP/1.1 202 Accepted
Content-Type: application/json 

Response to Invalid duediligenceid:

HTTP/1.1 404 Not Found
Content-Type: application/json 

{
    "errors":
    [
        {
            "id": 404,
            "message": "The duediligenceid supplied was invalid."
        }
    ]
}

Once the request has been processed we will send the certificate in PDF format to the corresponding callback location provided in the original request (either URL, email or both). The URL will receive a base64 encoded PDF as the body. With the response we will also send two headers containing the certificate ID and the amount of time this response has been retried.

Headers:-

• X-GAPI-CERTIFICATE-ID - The certificate ID of the requested certificate.
• X-GAPI-RETRIES - The amount of times the response has been retried.

Example Response

Response via URL:

POST {suppliedurl} HTTP/1.1
Accept: application/json
Content-Type: application/pdf
X-GAPI-CERTIFICATE-ID: 123456123456123
X-GAPI-RETRIES: 2

...base64 encoded certificate in pdf format...

Response via Email:

To: {suppliedemailaddress}
Subject: CheckMEND Certificate:123456123456123
Content-Type: multipart/mixed; boundary="=-vTlWP+RFInNhCclNPwUi"


--=-vTlWP+RFInNhCclNPwUi
Content-Type: multipart/mixed; boundary="=-yeT5m+1VtJLbYen0uT5D"


--=-yeT5m+1VtJLbYen0uT5D
Content-Transfer-Encoding: 8bit
Content-Type: text/plain



--=-yeT5m+1VtJLbYen0uT5D--

--=-vTlWP+RFInNhCclNPwUi
Content-Disposition: attachment; filename="123456123456123.pdf"
Content-Type: application/pdf
Content-Transfer-Encoding: base64

...base64 encoded certificate in pdf format...

--=-vTlWP+RFInNhCclNPwUi--