All Collections
Getting Started
How to access our Condition Alerts over API
How to access our Condition Alerts over API

This article covers how the MotorCheck API allows other systems to connect to your MotorCheck account and check for condition alerts.

Shane avatar
Written by Shane
Updated over a week ago

MotorCheck users can access their account over our REST API which returns data in a JSON format using OAUTH for authentication purposes.

Listed below are details of each API call.

Endpoints for interacting with condition alerts on the MotorCheck Trade website.Β 

The API consists of four endpoints as follows.

1. OAUTH Token

Authorise a system to access your MotorCheck account using this endpoint https://trade-api.motorcheck.co.uk/api/v1/oauth/token. You'll need to pass across a client ID and secret which you'll generate from your MotorCheck account (contact us using the chat widget below for this). This returns a token which is used to authenticate the three API calls below.

Here's how the OAUTH call is constructed;

Headers

{
{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}
}

Sample Body

{
"grant_type": "client_credentials",
"client_id": "__your client id__",
"client_secret": "__your client secret__",
"scope": "report-search report-show report-create"
}

Sample Response

{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "bearer_token_string"
}

Please note that all endpoints require an Authorization header with the "Bearer {token}" value as received from the oauth/tokenendpoint above.

Finds all reports with a given VRM and provides the report's unique ID in order to query the report details. If no report exists and your API account has the correct permissions, you can generate a new report using the /report/create endpoint.

Headers

[
{"key":"Accept","value":"application/json"},
{"key":"Content-Type","value":"application/json"}
{"key":"Authorization","value":"Bearer bearer_token_string"},
]

Sample Body

{
"vrm": "__enter VRM here__"
}

Sample Response

"data": [

{
"report_id": "__unique report id__",
"vrm": "__VRM__",
"created_at": "2017-01-01 00:00:00"

},
{

"report_id": "__unique report id__",
"vrm": "__VRM__",
"created_at": "2017-01-01 00:00:00"

}

3. Condition Alert Report Show

Requires a valid report_id to be found from the ca-report/search endpoint.

This endpoint returns if there are condition alerts found on the report, the location and user that created the report, and the URLs to view and download the report.

Please note the the URLs provided may have an expiry time as shown in the response 'url_expiry'. If null the URLs have no expiry associated.

Headers

[
{"key":"Accept","value":"application/json"},
{"key":"Content-Type","value":"application/json"}
{"key":"Authorization","value":"Bearer bearer_token_string"},
]

Sample Body

{
"report_id": "__unique report id__"
}

Sample Response

{
"data": {
"request_history": {
"id": "__unique report id__","vrm": "__VRM__",
"location": "__location_id__","user": "__user_id__”,"created_at": "2019-10-02 14:45:01"
},
"condition_alerts": "Yes",
"url": "https://trade.motorcheck.co.uk/ca-report-show/long_obfuscated_string","pdf": "https://trade.motorcheck.co.uk/ca-report-download/long_obfuscated_string"
}

4. Condition Alert Report Create

Generates a new report for the given VRM.

If the report is successfully generated the provided response is the same as the ca-report/show endpoint.

Headers

[
{"key":"Accept","value":"application/json"},
{"key":"Content-Type","value":"application/json"}
{"key":"Authorization","value":"Bearer bearer_token_string"},
]

Sample Body

{
"vrm": "__enter VRM here__"
}

Sample Response (same as /ca-report/show endpoint)

{
"data": {
"request_history": {
"id": "__unique report id__","vrm": "__VRM__",
"location": "__location_id__","user": "__user_id__”,"created_at": "2019-10-02 14:45:01"
},
"condition_alerts": "Yes",
"url": "https://trade.motorcheck.co.uk/ca-report-show/long_obfuscated_string","pdf": "https://trade.motorcheck.co.uk/ca-report-download/long_obfuscated_string"
}

Errors

Token Errors

If invalid credentials are passed to the oauth / token endpoint, the following error will be provided.

{
"error": "invalid_client",
"message": "Client authentication failed"
}

If invalid scopes are provided the following error will be displayed

{
"error": "invalid_scope",
"message": "The requested scope is invalid, unknown, or malformed","hint": "Check the not-a-valid-scope scope"
}

Validation Errors

Validation errors will return a 422 error code and will contain an array of errors for each field with an error.

The example below is when a report or spec report search is run without passing any VRM.

{
"error": {
"code": "GEN-WRONG-ARGS","http_code": 422,"errors": {
"vrm": [
"The vrm field is required."
]
}

Credit Errors

When using either the /report/create or / spec-report/create endpoints, the account/location against which the report is being generated must have enough credit available to generate the report. This is not applicable to customers with arrears/fixed billing.If a PAYG account does not have enough credit the error will be:

{
"error": {
"message": "There is not enough credit for you to make this lookup. Please addmore credit, or contact your account administrator.",
"status_code": 402}
}

Not Found Errors

When using the report/show or spec-report/show endpoints, a specific report ID must be provided. When the report_id is not found the following error will be returned:

{
"error": {
"message": "Not found.",
"status_code": 404}
}

Did this answer your question?