MotorCheck Trade (UK) Customer API

This Postman collection demonstrates how to connect to a MotorCheck account and perform actions such as retrieving a MotorCheck, Specification or Condition Alert Report that has already been run or create a brand new one as required.

The API may be accessed via the following environments:
Production URL: https://trade-api.motorcheck.co.uk/

For Technical Support contact: techsupport@motorspecs.co.uk
For Sales contact: sales@motorcheck.co.uk

POSTOAuth Token

https://trade-api.motorcheck.co.uk/api/v1/oauth/token

To connect to your MotorCheck account via API you'll first need to fetch an Authentication Token via an OAuth call. You can then use this token to make calls to your MotorCheck account and the services you have been activated for.

The Authentication Token will be provided in the API respnse along with an expiry of the token expressed in seconds. In the example below the token expires in 31622400 seconds (366 days) which is the default setting for all tokens. A new authentication token can be fetched at any time. Since the "Expiry" of the token can vary it is advisable not to hardcode the expiry but rather refresh it periodically before it expires.

You can create as many API accounts as you like on your MotorCheck account. Each one is given its own "client_id" and "client_secret" which you use in the OAUTH call. The payload below shows how to connect over this call and receive your Authentication token.

HEADERS

Content-Type

application/json

Bodyraw

{
    "grant_type": "client_credentials",
    "client_id": "678611664",
    "client_secret": "secret_here",
    "scope": "report-search report-show report-create spec-report-search spec-report-show spec-report-create ca-report-search ca-report-show ca-report-create"
}

Example Request

curl

curl --location 'https://trade-api.motorcheck.co.uk/api/v1/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "912136463",
    "client_secret": "xXxynP6xvlDUztnx8MBzMjZGcLjt9ti0ozcxXx"
}'

200 OK

Example Response

json

{
  "token_type": "Bearer",
  "expires_in": 912136463,
  "access_token": "xXxvlDUztnx8MBzMjZGcLjt9ti0ozcRxXx"
}

Date

Mon, 06 Jan 2020 21:47:07 GMT

Content-Type

application/json; charset=UTF-8

Transfer-Encoding

chunked

Connection

keep-alive

Server

nginx/1.17.3

Vary

Accept-Encoding

pragma

no-cache

Cache-Control

no-store, private

X-RateLimit-Limit

X-RateLimit-Remaining

X-XSS-Protection

1; mode=block

X-Content-Type-Options

nosniff

Content-Encoding

gzip

POSTIdentity Lookup

https://trade-api.motorcheck.co.uk/api/v1/identity-lookup/create

The MotorCheck Identity Service returns information such as Make, Model, Variant etc. for the VRM presented. The current mileage is an optional value that can be included if you intend subsequently retrieving a mileage linked valuation.

The data response is separated into three nodes;

dvla

mvris

combined

1. dvla

The DVLA node returns data from the DVLA database.

It can be useful to note here how the DVLA use the 'Model' field to describe a combination of both the 'Model' and 'Variant' for the vehicle

Plain Text

"model": "GOLF SE BLUEMOTION TECH TDI",

whereas the mvris response (the next node) seperates these into two fields.

Plain Text

"model": "GOLF",
"vehicleDesc": "GOLF SE BLUEMOTION TECH TDI",

Tip - If you need information on when the vehicle was bought or sold you'll find it in the dvla secion under the 'keepers' node.

2. mvris

The MVRIS node returns data from the SMMT databsae. The SMMT data is updated every 24 hours so if your looking for a vehicle that was registered very recently you'll find it here.

3. combined

The combined node contains data from both of the above. It uses a combination of the dvla and mvris data to describe a vehilce by Make, Model and Version as well as included a standardised list of the more common features such as Transmission, Fuel, Body, etc.

Fields

The possible fields that can be sent in the body of the call.

Field	Description	Required
country	an abbreviation for the country	No
registration	Vehicle Registration Number	Yes
currentMiles	Current odometer in miles	No
vin	Vehicle Identification Number	No

Status Codes

The standard response codes that can be returned.

Code	Description
406	Not Acceptable
415	Unsupported Media Type
201	Created
400	Client Error
422	Unprocessable Entity

HEADERS

application/json

Authorization

Bearer [bearer token here]

Content-Type

application/json

Bodyraw

{
  "vrm": "KD16XOB"
}

Example Request

curl

curl --location 'https://trade-api.motorcheck.co.uk/api/v1/identity-lookup/create' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [bearer token here]' \
--header 'Content-Type: application/json' \
--data '{
  "vrm": "KD16XOB"
}'

200 OK

Example Response

json

{
  "id": null,
  "registration": "KD16XOB",
  "regCurrent": null,
  "regMessage": null,
  "vehicle": {
    "vinMatch": null,
    "vinMatchMessage": null,
    "dvla": {
      "make": "FORD",
      "model": "KUGA TITANIUM TDCI 4X4 AUTO",
      "regDate": "2016-08-31",
      "v5cDate": "2022-10-03",
      "vin": "WF0AXXWPMAGK48743",
      "colour": "WHITE",
      "source": "UK",
      "exported": 0,
      "exportedDate": null,
      "imported": 0,
      "importedNi": 0,
      "importedDate": null,
      "scrapped": 0,
      "scrappedDate": null,
      "unscrapped": 0,
      "body": "HATCHBACK",
      "bodyClass": "CAR",
      "seatingCapacity": 5,
      "wheelplan": "2 AXLE RIGID BODY",
      "co2": 134,
      "cc": 1997,
      "engineNumber": "GK48743",
      "engineCode": "2.0 TDCI 180PS-A",
      "fuel": "DIESEL",
      "maxPower": 132,
      "maxTechMass": 2230,
      "powerToWeight": null,
      "trailerBraked": 2100,
      "trailerUnbraked": 750,
      "grossWeight": 2230
    },
    "keepers": {
      "numberOfPrevious": 5,
      "startDate": "2022-10-03",
      "previousAcquire": "2020-06-09",
      "previousDispose": "2022-10-03"
    },
    "mvris": {
      "make": "FORD",
      "model": "KUGA",
      "vehicleDesc": "KUGA TITANIUM TDCI 4X4 AUTO",
      "fuel": "DIESEL",
      "modelVariantName": "TITANIUM TDCI",
      "engineSize": 2,
      "cc": 1997,
      "bhpCount": 177,
      "doorCount": 5,
      "bodyDesc": "HATCHBACK",
      "cabType": "NA",
      "gearboxType": "AUTOMATIC",
      "numberOfAxles": 2,
      "mvrisCode": null,
      "smmtMarketSectorLine": null,
      "vehicleSeries": "C520",
      "vehicleOrigin": "SPAIN",
      "gearsCount": 6,
      "driveType": "4X4",
      "visibilityDate": "2014-09-01",
      "setupDate": "2014-09-01",
      "terminationDate": null,
      "grossCombinedWeight": null,
      "vehicleGrossWeight": null,
      "unladenWeight": null,
      "bodyShapeRoofHeight": "NA",
      "driveAxle": "ALL - SELECTED",
      "vehicleHeight": 1689,
      "kerbWeight": 1716,
      "vehicleLength": 4524,
      "seatCount": 5,
      "powerDelivery": "NORMAL",
      "rigidArtic": "RIGID",
      "typeApprovalCategory": "M1",
      "wheelbaseLength": "SHORT WHEELBASE",
      "vehicleWidth": 2077,
      "primaryFuel": "Y",
      "powerKw": 132,
      "rpmPower": 3500,
      "torqueLb": 295.2,
      "torqueNm": 400,
      "rpmTorque": 2000,
      "vehicleCo2": 140,
      "urbanColdMpg": 46.3,
      "extraUrbanMpg": 56.5,
      "combinedMpg": 52.3,
      "urbanColdLkm": 6.1,
      "extraUrbanLkm": 5,
      "combinedLkm": 5.4,
      "maxSpeedMph": 124,
      "maxSpeedKph": 200,
      "accelerationMph": 10,
      "accelerationKph": 10,
      "engineDescription": "2.0 TDCI 180PS-A",
      "engineLocation": "FRONT",
      "engineMake": "FORD",
      "euroStatus": 6,
      "bore": 85,
      "stroke": 88,
      "fuelDelivery": "TURBO",
      "cylinderArrangement": "INLINE",
      "cylinderCount": 4,
      "valveCount": 4,
      "valveGear": "DOHC",
      "dtpModelCode": null,
      "dtpMakeCode": null,
      "mvrisModelCode": null,
      "mvrisMakeCode": null,
      "importNonEU": null,
      "regDate": "2016-08-31"
    },
    "combined": {
      "id": null,
      "registration": "KD16XOB",
      "currentMiles": 90000,
      "annualMiles": 12202,
      "make": "FORD",
      "model": "KUGA",
      "transmission": "AUTOMATIC",
      "version": "KUGA TITANIUM TDCI 4X4 AUTO",
      "fuel": "DIESEL",
      "body": "HATCHBACK",
      "colour": "WHITE",
      "doors": 5,
      "cc": 1997,
      "origin": "UK",
      "powerBHP": 177,
      "powerKW": 132,
      "regDate": "2016-08-31",
      "dvlaCo2": 134,
      "mvrisCo2": 140,
      "manufDate": "2016-08-31",
      "imported": false,
      "updatedAt": "2024-01-17 09:43:12"
    }
  }
}

Date

Wed, 17 Jan 2024 09:43:12 GMT

Content-Type

application/json

Transfer-Encoding

chunked

Connection

keep-alive

Server

nginx

Vary

Accept-Encoding

Cache-Control

no-cache, private

X-RateLimit-Limit

X-RateLimit-Remaining

Set-Cookie

motorcheck_session=ad5J2Y1gdcif8bVp9XJjrryI1DRkYG260zPMXfDR; expires=Fri, 16-Feb-2024 09:43:12 GMT; Max-Age=2592000; path=/; httponly

X-XSS-Protection

1; mode=block

X-Content-Type-Options

nosniff

Content-Encoding

gzip

POSTHistory Report Search

https://trade-api.motorcheck.co.uk/api/v1/report/search

Use the Report Search endpoint to find any MotorCheck History Reports your account has Previously Run against a specific VRM or across a specified Date Range.

The response will provide you with the reports unique ID(s) so that you can view them using the Report Show endpoint. If you'd like to keep your application in sync with all the reports that a user has carried out on MotorCheck you can do so by leaving the VRM field blank and using the "fromDate" and "toDate" ranges instead.

The VRM field is required if there is no "fromDate" or "toDate" set. If a "fromDate" or "toDate" is set it is not required.

If the "fromDate" is set the API response will return all reports created from that date.

If the "toDate" is set it will return reports created up to that date.

If both the "fromDate" and "toDate" is set then the API will return all reports created between those dates.

If all three are set then it shows reports created for that VRM between those dates.

If no report exists and your API account has the correct permissions, you can go ahead and generate a New Report using the Report Create endpoint.

HEADERS

application/json

Authorization

Bearer [bearer token here]

Content-Type

application/json

Bodyraw

{
  "vrm": "",
  "fromDate": "2024-08-01",
  "toDate": "2024-08-20"
}

Example Request

curl

curl --location 'https://trade-api.motorcheck.co.uk/api/v1/report/search' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [bearer token here]' \
--header 'Content-Type: application/json' \
--data '{
  "vrm": "KD16XOB"
}'

200 OK

Example Response

json

{
  "data": [
    {
      "report_id": "PKWJLCP",
      "vrm": "KD16XOB",
      "created_at": "2019-12-05 19:56:30"
    },
    {
      "report_id": "O4M0ZC2",
      "vrm": "KD16XOB",
      "created_at": "2019-04-30 16:59:43"
    }
  ]
}

Date

Mon, 06 Jan 2020 21:49:30 GMT

Content-Type

application/json

Transfer-Encoding

chunked

Connection

keep-alive

Server

nginx/1.17.3

Vary

Accept-Encoding

Cache-Control

no-cache, private

X-RateLimit-Limit

X-RateLimit-Remaining

Set-Cookie

motorcheck_session=eyJpdiI6Ilh5ZkFYVlNHdVluSTRJeThDSGx2NUE9PSIsInZhbHVlIjoiQUoxSjdqbk9Vc1phZHpKc21ET1l6ZlJydGNIQ2FzeHRtN2R4eWx3MXROcStpa2pSYzBTR0VIc1dyTVlESnRXWiIsIm1hYyI6IjA1N2VkNWI5ZmQ5MDZiZDQxYjAxMWYwYTBjNWUwNzJjNzE4ZGY0MmE2NWRiZTk4NmE2N2M5ZTEwZDdkMTYzZjQifQ%3D%3D; expires=Wed, 05-Feb-2020 21:49:30 GMT; Max-Age=2592000; path=/; httponly

X-XSS-Protection

1; mode=block

X-Content-Type-Options

nosniff

Content-Encoding

gzip

POSTHistory Report Show

https://trade-api.motorcheck.co.uk/api/v1/report/show

This endpoint requires a valid report_id which you'll find using the Report Search endpoint.

A successful call will return details of the major headings found on the history report, the location and user that created it and a variety of URLs from which you can download the full report and the printable PDF(s).

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

application/json

Authorization

Bearer [bearer token here]

Content-Type

application/json

Bodyraw

{
  "report_id": "PKWJLCP"
}

Example Request

curl

curl --location 'https://trade-api.motorcheck.co.uk/api/v1/report/show' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [bearer token here]' \
--header 'Content-Type: application/json' \
--data '{
  "report_id": "PKWJLCP"
}'

200 OK

Example Response

json

{
  "data": {
    "id": "PKWJLCP",
    "vrm": "KD16XOB",
    "location": "JCT600 - Vauxhall Castleford",
    "user": "Shane Teskey",
    "created_at": "2019-12-05 19:56:30",
    "issues": {
      "finance": {
        "flag": false,
        "message": "No finance agreement recorded"
      },
      "mileage": {
        "flag": false,
        "message": "No mileage discrepancies"
      },
      "atRisk": {
        "flag": false,
        "message": "No risk marker recorded"
      },
      "writeOff": {
        "flag": false,
        "message": "No write-off recorded"
      },
      "conditionAlerts": {
        "flag": true,
        "message": "There are condition alerts"
      },
      "scrapped": {
        "flag": false,
        "message": "Not scrapped, no VIC recorded"
      },
      "stolen": {
        "flag": false,
        "message": "No stolen record"
      },
      "keepers": {
        "flag": true,
        "message": "More keepers than average"
      },
      "plateChange": {
        "flag": false,
        "message": "No  issues recorded."
      },
      "colourChanges": {
        "flag": false,
        "message": "No  issues recorded."
      },
      "motHistory": {
        "flag": false,
        "message": "No  issues recorded."
      },
      "taxAndSorn": {
        "flag": false,
        "message": "No  issues recorded."
      },
      "originAndUse": {
        "flag": false,
        "message": "No  issues recorded."
      }
    },
    "url": "https://trade.motorcheck.co.uk/report-show/eyJpdiI6IlY5V2w3NmN2b0c1T1BwRklyU2xrRFE9PSIsInZhbHVlIjoiZnNwaDVSaG03YjBTS2NpdE1mUWE4VkhjY3RxNVZLVWFjXC80TjUySnJkdFM4KzgyS3YwdUZiTFZleUNUNGw4MWZZbUtPOG1NQzNxMzZoM1pvZXY3YVdDS2VSaTBiT21JMzJYc0ZRZmphdjBySVNrV2I3NW1ldmdwVTR1dEhWekdSSHFMaHo1V256XC9BTVJPcFVxUXpHbzVkV2V5ckxDa05nT090SFFCM0pRelk9IiwibWFjIjoiOWFmZmM1YjM0NWMzMmEyYjBlZjdiMmU2NTdkYjNjY2IwNmQ5NTY5NzQ4ZWI2MjkzNDFhZDQ4MTY3OGY2ZTFhMSJ9",
    "pdf": "https://trade.motorcheck.co.uk/report-download/eyJpdiI6ImZyS2s2bEhFbzhnMnVJNWNxWFBTaHc9PSIsInZhbHVlIjoiTTIydm53SDhibFhVQ0JYa21OaGxFQytCZlFZM0Q5T2I0a3o1YzRXazdLcmwwem5FWEVtQ092K2tWM1Q5OFFjS3MwaUp3NlBuVzBCXC81NlZqek9SQzdnemJWN1wvNWdVQUwxWkVmZG9HbEhZcjR2NUt3WDVOdWdmRk93SWllZ01DSWYwOUlzVmdxS2FURGVFbU5BZ1g3QVo2UGdrSWVJNjgxQ2EyaUtkT2ZEcXd5Vmltc3VUUGhISnZJcGtMQlp3NXIiLCJtYWMiOiJhZDMzYWM5ZTc4NDhkOTQwMjdlZDZlY2JlY2I0N2IwMjNkNmMwYWUwOTUzZDAxZmVmZWZjMDgzOTMzZGYyYWFjIn0=",
    "silent_sales_pdf": "https://trade.motorcheck.co.uk/report-download/eyJpdiI6IkRsaWI5K1hEbjdGUitRc0JyTUpwM3c9PSIsInZhbHVlIjoiQ1ZpeEJqaHd4bEpMMU5KSnppTFVLRUhqbDRvMVBnTUp1eDFsMUI2aWRhbFBMcGYrUEhQWFBmWndYeGtya1pFOWs1ZUlxY0VXZVluWkhoMFp4RDdUUUdtSVdyZFlsN01neVNXVWRYUDVQakoyemNCeFFjZVZiVjFLRmhzWXdWTGZWV0E1MlhFcE54MHB1a1NiY2U4WktRM3N4TzVcL0w4WW5KNU8yQXpaNlJEK3Y2SGhFMk5mTW8wTVh2VDAyUk1SWiIsIm1hYyI6ImQyM2RkN2FiNWEzNzIzNzI2ZDEwM2FkM2EyZTU2YTY5YWYxZjIzODVkMzE1MGVmNzQxMWVmNzdhYTIzMmZkODYifQ==",
    "environmental_pdf": "https://trade.motorcheck.co.uk/report-download/eyJpdiI6Ijl6ZHhCZm9JR1wvR3oydldZdHhOUDZnPT0iLCJ2YWx1ZSI6Ikt0ZlROOHpLTitYU0o2ZkdiRmQxOVJrY1R4SHgwUXhOblVmS1FRZkhQMHZVVjMrNkhDY05SSXBsdExtT3NuRGpqc011bWVMaXBxZ3IyQ2trK3NsZVF5akVNRzAzaEhUWlkxRlpacVJiZStoSFhNOWtJbXpmb2NwZkcxdFhMTm82WkZRaDNJcXBUWmEwdExEcFdKMFdZZ3JOXC84QUpVZDVHZ2doeUR0QzdFdE41T1NFTksrQ0NsNlpLVjVScUhNaXYiLCJtYWMiOiI1ZjE2OThmZmQ5Zjc1OGFiN2UxMTZmMGMwNjU4MmUzMTVkODM4YTRjZGYwMDIzZDYyNDViYzY5Yzg3ZGY1ZTQ1In0=",
    "certificate_pdf": null
  }
}

Date

Mon, 06 Jan 2020 21:50:17 GMT

Content-Type

application/json

Transfer-Encoding

chunked

Connection

keep-alive

Server

nginx/1.17.3

Vary

Accept-Encoding

Cache-Control

no-cache, private

X-RateLimit-Limit

X-RateLimit-Remaining

Set-Cookie

motorcheck_session=eyJpdiI6InhLOW9UalhmWE1RdGgxY3NSMlVmT0E9PSIsInZhbHVlIjoiQzFLMk5URDVkd3A4SUY3ZGlDc295U3ExQlZ6aU1FOFR6emJFeDBRdUZEQm9zY09Ra1BEM1wvZDhnN2hRUjdIdHQiLCJtYWMiOiIwYjVmMWVlNTMwMjgzNTI5Mzc5OWUzMTM5MmZjNTljOTkwNGRjM2IxMjQ4ZGIxZjRjYmQ1Y2QwZWQ1YzY3MzBkIn0%3D; expires=Wed, 05-Feb-2020 21:50:17 GMT; Max-Age=2592000; path=/; httponly

X-XSS-Protection

1; mode=block

X-Content-Type-Options

nosniff

Content-Encoding

gzip