DVLA Data Connector

The DVLA Data Connector provides access to the DVLA Vehicle Enquiry API. This Data Connector can be used to query vehicle registration numbers.

Constructor

DVLA(key) → {object}

We recommend that you create a Data Connector Configuration called "DVLA" via the Verj.io Runtime Environment's Administration Application.

A DVLA Data Connector is then available at connectors.verjio.dvla using that configuration.

If you are unable to do that, you may use this constructor to create a new DVLA Data Connector.

This constructor accepts an API key.

Parameters:

Name	Type	Description
key	`string`	DVLA API key.

Returns:

object

The DVLA Data Connector.

Members

authentication

A collection of functions for DVLA services that require authentication.

helpers

A collection of helper methods for formatting and querying API data.

Functions

authenticate.changeAPIKey() → {string}

Resets an API Key for a given username and password. A new API Key is returned if valid.

Properties:

Name	Type	Description
username	`string`	username of the user making the request
password	`string`	password for the user

Returns:

string

The new API Key

authenticate.changePassword()

Changes a third-party password for a user given valid credentials and new password. This will also update the connector's stored password

Properties:

Name	Type	Attributes	Description
newPassword	`string`		new password to be set
password	`string`	<optional>	current password for the user

authenticate.changePasswordByVerificationCode()

Changes a third-party password for a user given a valid verification code and new password. A verification code is sent via email in response to a call to requestNewPasswordVerificationCode. This will also update the connector's stored password

Properties:

Name	Type	Description
verificationCode	`string`	verification code from the email
newPassword	`string`	new password to be set

See:

authenticate.requestNewPasswordVerificationCode

authenticate.requestNewPasswordVerificationCode() → {string}

Requests a verification code that can be used to set a new password for the configured username and email address. A successful request will trigger an email with a verification code that can be passed into the changePasswordByVerificationCode function.

See:

authentication.changePasswordByVerificationCode

Returns:

string

A message if successful

authenticate() → {string}

Set the password to use for the configured username. Passwords must be changed every 90 days so this method allows you to set the latest password.

Properties:

Name	Type	Description
password	`string`

Returns:

string

an id token that can be used to access secure DVLA services.

authenticate() → {string}

Access to the DVLA APIs requires use of the Authentication API for user authentication and credential management. If no password is provided then the connector will use its stored password (provided by calling authentication.setConnectorPassword)

Properties:

Name	Type	Attributes	Description
password	`string`	<optional>

See:

authentication.setConnectorPassword

Returns:

string

an id token that can be used to access secure DVLA services.

getVehicleInfo(registrationNumber) → (nullable) {DVLA.VehicleInformation}

Retrieves vehicle information from the DVLA.

Parameters:

Name	Type	Description
registrationNumber	`string`	Vehicle Registration Number (VRN).

Returns:

DVLA.VehicleInformation

API response object containing vehicle information, or null if an error was encountered.

Example:

// Get the vehicle make and colour
try {
	var info = connectors.verjio.dvla.getVehicleInfo(fields.vehicleRegistrationNumber.value);
	fields.vehicleMake.value = info.make;
	fields.vehicleColour.value = info.colour;
}
catch (e) {
	if (e instanceof HttpNotFoundError) {
		event.owner.addErrorMessage('The Vehicle Registration Number you entered was not found.');
	}
}

handleError(response)

Checks an API response for errors. If an error is encountered, the appropriate Error is thrown.

Parameters:

Name	Type	Description
response	`object`	The response from a `services.rest` request.

Throws:

HttpAuthorisationError

Thrown when an incorrect API key is specified or the request exceeds rate limiting.
HttpNotFoundError

Thrown when the vehicle registration number is not recognised.
HttpServerError

Thrown when the API responsed with a server error (HTTP 502 and HTTP 504)
HttpRequestError

Thrown when the server could not process the request. Details are available in the error message.

Example:

try {
	connectors.verjio.dvla.getVehicleInfo(fields.vehicleRegistrationNumber.value);
}
catch (e) {
	if (e instanceof HttpAuthorisationError) {
	  // API key or rate-limiting error
	  log(e.getMessage())
	  event.owner.addErrorMessage('We are not able to retrieve vehicle information at this time.');
	} else if (e instanceof HttpNotFoundError) {
		event.owner.addErrorMessage('The vehicle registration number you entered was not found.');
	}
}

Type definitions

VehicleInformation

Vehicle information as returned by the DVLA API.

Properties:

Name	Type	Description
registrationNumber	`string`	Vehicle Registration Number (VRN)
taxStatus	`string`	Vehicle tax status, e.g. `Taxed`.
taxDueDate	`string`	Date the vehicle tax is due. Formated as `YYYY-MM-dd`.
motStatus	`string`	Vehicle MOT status, e.g. `Valid`.
make	`string`	Vehicle manufacturer, e.g. `FORD`.
yearOfManufacture	`number`	Year of manufacture.
engineCapacity	`number`	Engine capacity in cubic centimeters (cc).
co2Emissions	`number`	Carbon dioxide emissions in grams per kilometer (g/km)
fuelType	`string`	Fuel type, e.g. `PETROL`.
markedForExport	`boolean`	Has the vehicle been marked for export?
colour	`string`	Bodywork colour, e.g. `SILVER`.
typeApproval	`string`	Vehicle type approval. See Type Approval Categories.
dateOfLastV5CIssued	`string`	Date of the last vehicle log book (V5C) issue. Formated as `YYYY-MM-dd`.
motExpiryDate	`string`	Date the vehicle MOT expires. Formated as `YYYY-MM-dd`.
wheelplan	`string`	Details of vehicle axles.
monthOfFirstRegistration	`string`	Date of the vehicle registration. Formated as `YYYY-MM`.