Introduction
This guide explains how to use our APIs to perform testing prior to third-party integration and development. It is designed to help developers understand the available endpoints, authentication requirements, request/response structures, and expected behaviours before building a customer-facing interface.
User Configuration – In order to use the API users must be set up with the correct configurations beforehand. These will be arranged by r2c and then shared with the relevant team. Please see below, the requirements needed for each API.
Asset by Depot API
Credentials Required
The credentials required for this API are Account GUID and API Key.
Step by Step
These steps show an example of using the Asset by Depots API to retrieve key details per asset across the fleet list.
The parameteres required are:
- Endpoint URL – https://api.r2clive.com/REST/9/Asset/AssetsByDepot
- Depot (if filtering by specific sites)
- Account Guid
- API Key
Start by adding the URL and parameters to your third party app. Click ‘send’ to run the API. This example uses Postman. Below are a set of example reuslts retrieved by the API.
Example Response
Create Asset API
These guides describe the API’s on the R2C Platform, accessible through the Public API’s as a REST API. These API’s do not have Swagger documents, the body information is included below.
This API allows you to CREATE Assets within r2c using key/value pairs, utilising the POST method.
Parameters
The credentials required for this API are Account GUID and API Key.
Endpoints
Live – https://api.r2clive.com/rest/9/asset/CreateAsset
UAT- https://uat.r2clive.com/PublicApi/REST/9/Asset/CreateAsset
Body
The main data sent via the API is through the body section. This consists of a R2CPublicAsset structure using the below fields
| Name | Description |
| ExternalReference | This value is displayed in Portal but cannot be added or edited and is defined by the organisation Actor Role Id. |
| RegistrationNumber | The normal identifier for an Asset. Max 10 Characters. |
| VinOrChassis | The Vin or Chassis number of the asset. |
| AssetType | Example: Tractor, Trailer, Rigid etc. |
| Manufacturer | Example: Scania, DAF, Volvo etc. |
| FleetNumber | Fleet identifier, unique only to the customer’s account. Max 20 Characters. |
| Range | Example: P series, CF, FM etc. |
| Model | Example: P112, 530, 42T |
| ModelNumber | Free Text, Max 20 Characters. |
| Description | Free Text, Max 20 Characters. |
| RegDate | Optional Date, YYYY-MM-DD |
| ManufactureDate | Optional Date, YYYY-MM-DD |
| InServiceDate | Optional Date, YYYY-MM-DD |
| MOTExpiryDate | Optional Date, YYYY-MM-DD |
| TachoExpiryDate | Optional Date, YYYY-MM-DD |
| WarrantyExpiryDate | Optional Date YYYY-MM-DD |
| Workshop | Primary Repairer |
| WorkshopID | Site ID |
| TotalAssetCost | String numeric value |
| UsageUnit | Example: M, Km, H. |
| BodyType | Example: Artic, Box, Bin Lift etc. |
| Usage | Last Known Usage |
| ParentRegistrationNumber | Optional reg of parent asset. |
| ParentExternalReference | Optional external reference of parent asset. |
| GrossVehicleWeight | Decimal gross weight in tonnes |
| Transmission | Example: Automatic, Manual, Semi-Automatic. |
| Colour | Example: Black, Brown Red etc. |
| EmissionStandard | Example: Euro 6, FRD6 etc. |
| CustomDetails | Custom field name and value. See “Custom Details and Custom Updates” for more information. |
The API allow a collection of Management Roles to be assigned to the asset.
Note that the role name or code may be used in the “Role” parameter.
| Name | Code |
|---|---|
| Manufacturer | MNFER |
| Owner | OWNER |
| Operator | OPROR |
| Depot | DEPOT |
| Repair Agent | RPRAG |
| Workshop | WRKSH |
| Warranty Provider | WPROV |
| Repair and Maintenance | REMNT |
Custom Details
In the R2C platform, customers with the module enabled can create custom values for their assets. These values are only available to that specific customer and appear in a separate tab on the Assets screen.
There is an optional property “CustomDetails” which can be used to set a collection of key/value pairs that can be sent to the API. The key needs to relate to the name of the custom value, as it appears in the Portal screen above and the value needs to be valid for that Custom Detail, e.g. a number or a date.
Example JSON
Example Response
Update Asset API
These guides describe the API’s on the R2C Platform, accessible through the Public API’s as a REST API. These API’s do not have Swagger documents however the body information is included below.
This API allows you to UPDATE Assets within r2c by matching key/value pairs, utilising the POST method.
Parameters
The credentials required for this API are Account GUID and API Key.
Endpoints
Live – https://api.r2clive.com/rest/9/asset/UpdateAsset
UAT – https://uat.r2clive.com/PublicApi/REST/9/Asset/UpdateAsset
Body
The main data sent via the API is through the body section. This consists of a R2CPublicAsset structure using the below fields
Match
This is a collection of key/value pairs that are used to match the existing Asset that you want to update.
| Name | Description |
|---|---|
| ExternalReference | The external reference given by the customer when they created the Asset in the API. |
| VinOrChassis | The Vin or Chassis number of the asset. |
| RegistrationNumber | The Registration Number of the asset. |
Updates
A collection of key/value pairs, each specifying a property name and the required value to be updated on the asset record fields in portal.
| Name | Description |
|---|---|
| ExternalReference | A unique reference number for the account using the API. |
| VinOrChassis | The Vin or Chassis number of the asset. |
| FleetNumber | The customer’s fleet number for the asset. Max 20 Characters. |
| RegistrationNumber | The normal identifier for an Asset. Max 10 Characters. |
| Description | ? Free Text, Max 20 Characters. |
| RegDate | Optional Date, YYYY-MM-DD |
| InServiceDate | Optional Date, YYYY-MM-DD |
| ManufactureDate | Optional Date, YYYY-MM-DD |
| Manufacturer | Example: Scania, DAF, Volvo etc. |
| WarrantyExpiryDate | Optional Date, YYYY-MM-DD |
| AssetType | Example: Tractor, Trailer, Rigid etc. |
| BodyType | Example: Artic, Box, Bin Lift etc. |
| InspectionInterval | - |
| UsageUnit | Example: M, Km, H. |
| Workshop | Primary Repairer |
| WorkshopID | ? SITE ID |
| TotalAssetCost | ? String numeric value |
| Usage | Last Known Usage |
| MOTExpiryDate | Optional Date, YYYY-MM-DD |
| TachoExpiryDate | Optional Date, YYYY-MM-DD |
| ParentRegistrationNumber | Optional reg of parent asset. |
| ParentExternalReference | Optional external reference of parent asset |
| GrossVehicleWeight | Decimal gross weight in tonnes |
| Transmission | Example: Automatic, Manual, Semi-Automatic. |
| Colour | Example: Black, Brown Red etc. |
| EmissionStandard | Example: Euro 6, FRD6 etc. |
| ContractLeaseCompany | Free Text |
| ContractLeaseNumber | Free Text |
| ContractLeaseType | Example: 3 Year Rental, 5 Year Finance, Hired etc. |
| ContractStartDate | Optional Date YYYY-MM-DD |
| ContractEndDate | Optional Date YYYY-MM-DD |
| ContractMileage | Optional max mileage |
| ContractExcessMileageCharge | Optional excess mileage |
| ManufacturerRangeModel | The preferred method of setting the manufacturer, range and model. The three are separated by “|” like this: "Manu|Range|Model" |
| Model Number | Free Text, Max 20 Characters. |
| AxleConfig | Axel configuration as Position, Steer & WheelCount. |
| Management Role | Management details as Role & reference.* See available roles below |
| Custom Details | Custom field name and value. *See Custom Details for more information. |
Management Roles
The API allow a collection of Management Roles to be assigned to the asset.
Note that the role name or code may be used in the “Role” parameter.
| Name | Code |
|---|---|
| Manufacturer | MNFER |
| Owner | OWNER |
| Operator | OPROR |
| Depot | DEPOT |
| Repair Agent | RPRAG |
| Workshop | WRKSH |
| Warranty Provider | WPROV |
| Repair and Maintenance | REMNT |
Custom Details
In the R2C platform, customers with the module enabled can create custom values for their assets. These values are only available to that specific customer and appear in a separate tab on the Assets screen.
There is an optional property “CustomUpdates” which can be used to set a collection of key/value pairs that can be sent to the API. The key needs to relate to the name of the custom value, as it appears in the Portal screen above and the value needs to be valid for that Custom Detail, e.g. a number or a date.
Example JSON
Example Response
Jobsheet API
Credentials Required
The credentials required for this API are outlined in the table below. Some of the required details can be found in your r2c portal account, while others are initially configured by r2c and shared with you during the setup process.
Step by step
These steps show an example of using the Jobsheet API to retrieve key jobsheet details and update worklines.
The steps required are:
- Credentials
- Token Generation
- Authorisation of Token on Swagger docs prior to using an API.
Parameters
| Parameter | Notes | |
|---|---|---|
| Swagger site URL | https://r2clive.com/api/Jobsheet/2/swagger/index.html | Default URL, to access the API |
| End point URL | https://www.r2clive.com/identity/connect/token | Default URL, replace 'www'. With UAT. Depending on Environment. |
| Account | Account name as per portal | - |
| Site ID | Account site ID that is used to login to portal. | - |
| Username | Login credentials for portal | Provided by r2c upon account configuration |
| Password | Login credentials for portal | Provided by r2c upon account configuration |
| grant_type | 'password' | This parameter remains the same for all accounts |
| client_id | Provided by r2c upon account configuration | - |
| client_secret | Provided by r2c upon account configuration | - |
| Scope | Account type identifier. If your account type is a workshop use = openid and if an R&M = r2c_organisation_api | This paramamter changes based on account type. |
API Error Messages and Resolutions
No jobsheet related to the jobExternalId
What does this mean?
The platform could not find a job matching the jobExternalId provided in your request.
How can I resolve this?
This typically means the job has not yet been created or taken over within the platform, so it cannot be updated.
Please try creating the job using the UpdateJobToPlanned API method. If the job creation request is unsuccessful, the response should provide more information about why the job could not be created.
If you continue to experience issues, please provide the request and response details to our support team for further investigation.
Jobsheet found with invalid status ('Completed'). Update not possible.
What does this mean?
A matching jobsheet was found for the asset within the permitted date range, but the jobsheet has already been completed.
How can I resolve this?
Once a jobsheet has reached a Completed status, it cannot be taken over or updated via the API.
This usually occurs when the job was manually created and completed through the portal. Any further changes would need to be managed outside of the API process.
No Asset External Reference found
What does this mean?
The platform was unable to find an asset with an external reference matching the one provided in your request.
How can I resolve this?
Please verify that the asset external reference provided is correct and matches the value stored within the R2C platform.
If there is no reference in R2C, or the reference is correct but the issue persists, please contact our support team so the asset record can be reviewed and updated if necessary.
Job bookedDate has to be within 21 days of today
What does this mean?
The booked date associated with the job falls outside the supported date range of 21 days from today’s date.
How can I resolve this?
This can occur when the API attempts to match a historical job rather than the intended current job.
We recommend creating the job using the UpdateJobToPlanned API method. If the job cannot be created, please review the response returned by the API, as it should provide additional information about the cause of the issue.
No tasks found using form Mapping provided
The platform could not find any valid task mappings based on the information provided in the request.
A jobsheet cannot be created without at least one valid task.
How can I resolve this?
Please:
- Verify that the task information in your request is correct.
- Confirm that the task has been mapped correctly within the platform.
- Provide the correct mapping information if it is not already configured.
Alternatively, the jobsheet can be created manually through the portal.
Job bookedDate can not be before today
What does this mean?
The platform could not find any valid task mappings based on the information provided in the request.
A jobsheet cannot be created without at least one valid task.
How can I resolve this?
Please:
- Verify that the task information in your request is correct.
- Confirm that the task has been mapped correctly within the platform.
- Provide the correct mapping information if it is not already configured.
Alternatively, the jobsheet can be created manually through the portal.
Nullable object must have a value
What does this mean?
This is an unexpected system error that can occur during the job takeover process when required information is missing from an existing job record.
How can I resolve this?
Please review any planned jobs for the affected asset around the requested booked date in R2C and check for any obvious missing information.
If the issue cannot be identified, please contact our support team and provide the request details so that the issue can be investigated further.
Jobsheet extended API – to retrieve jobsheet details.
Jobsheet Post Tasks – to add worklines to jobsheets.
Jobsheet Post Parts- to add parts to existing worklines on jobsheets.
Jobsheet Patch Parts- to update part quantities on existing worklines
