External References

Requesting Verilocation models with custom references

An ExternalReference is a string property on Vehicle, Driver and Geofence models within Verilocation, that can be set by a User and subsequently used as variable path parameters in GET endpoints to retrieve Vehicle, Driver and Geofence models by the assigned ExternalReference allowing Users to request models based on these custom reference points.

ExternalReferenceType

To assign an ExternalReference to any of the models, a User first needs to retrieve or create an ExternalReferenceType which is a representation of the third party that owns the reference.

e.g.

‘CompanyA’ consumes information over Verilocation's API and utilises ExternalReferences so they can refer to objects in GET calls to using reference points their native system understands, all ExternalReference’s attributed to an ExternalReferenceType called, for example, ‘companyARef’.

‘CompanyA’ has an insurer ‘ThirdPartyB’, that wants access to ‘CompanyA’s data to make assessments of Driver behaviour and the subsequent risk on an ongoing basis.

ThirdPartyB can create a second ExternalReferenceType called, for example, ‘thirdPartyBRef’ and assign their own ExternalReference identifiers to each driver using their unique ExternalReferenceType.

Both implementations can then reference the same driver via different reference strings.

ExternalReferenceType Creation

Creating a new ExternalReferenceType is achieved via the POST endpoint:

…/public/v1/externalreferences/types/{type}

Where {type} is a string representing the name of the ExternalReferenceType. From the earlier example this would be “companyARef” or “thirdPartyBRef”.

Successful addition of an ExternalReferenceType will return the Id of the new ExternalReferenceType, which needs to be included when applying an ExternalReference to any model.

All existingExternalReferenceType models can be recalled using the GET endpoint

…/public/v1/externalReferences

An ExternalReferenceType can not be updated once created. Should you need to update them for any reason, please contact support in the first instance.

Assigning an ExternalReference to a model

An individual ExternalReference can then be assigned to a Vehicle, Driver or Geofence via the below POST endpoints respectively.

Vehicles

Vehicles can be assigned a new ExternalReference via the POST endpoint

…/public/v1/externalReferences/vehicleExternalReference

Body Fields (* Required)

{
  * “externalReference”: string
  * “externalReferenceTypeId”: 0
  * “vehicleId”: 0
}

Drivers

Drivers can be assigned a new ExternalReference via the POST endpoint

…/public/v1/externalReferences/driverExternalReference

Body Fields (* Required)

{
  * “externalReference”: string
  * “externalReferenceTypeId”: 0
  * “driverId”: 0
}

Geofences

Geofences can be assigned a new ExternalReference via the POST endpoint

…/public/v1/externalReferences/geofenceExternalReference

Body Fields (* Required)

{
  * “externalReference”: string
  * “externalReferenceTypeId”: 0
  * “geofenceId”: 0
}

‘externalReference’ is the string that will be used to recall the model via the GET endpoints.

‘externalReferenceTypeId’ is the Id of the ExternalReferenceType that will associate the ExternalReference

‘vehicleId’ is the Verilocation Id of the Vehicle that is to be associated with the ExternalReference string

‘driverId' is the Verilocation Id of the Driver that is to be associated with the ExternalReference string

‘geofenceId’ is the Verilocation Id of the Geofence that is to be associated with the ExternalReference string

Recalling models based on ExternalReference

Once an ExternalReference has been associated with a model, they can be recalled from the following GET endpoints using the string reference:

Model	v1 Endpoint
Vehicles	…/public/v1/vehicles/ref/{externalReference}
Drivers	…/public/v1/drivers/ref/{externalReferenceId}
Geofences	…/public/v1/geofences/ref/{externalReference}

Known 'Gotchas'

• Currently when requesting a Vehicle, Driver or Geofence by ExternalReference, there is a known issue where we see the system returning the wrong model if two different ExternalReferenceType have identical ExternalReference strings that are associated with different models. As mitigation at point of writing, we are recommending that all ExternalReference strings are unique regardless of ExternalReferenceType.

• Currently there is no way to update an ExternalReference via API once it has been set. This can be achieved via the Verilocation GUI.