Overview
Overview
This project contains an OpenAPI 3 specification for the Auto Rescue Solutions API for light roadside assistance dispatching.
The ARS API is a conventional JSON REST API. It is split into two servers – one server run by ARS, and one server run by the client.
The ARS server (“ARS API”) endpoints allow a client to create, retrieve, and cancel roadside service work orders (“WOs”). The client server (“client API”) endpoints allow ARS to push up-to-date information relating to roadside services and technician availability to the client.
Both servers and all endpoints are formally specified in the attached OpenAPI YAML documents.
ARS will provide an apiKey that will grant authentication to its clients.
ARS will require the base URL of the implementation of the client-api and an apiKey to authenticate
ARS API overview
See the ARS API specification documentation here.
Download Postman collection here
The ARS API is used to create and update roadside service requests. All endpoints take POST requests with the specified JSON objects in the body, and are authenticated using a header API key.
The root URL paths are:
Production: https://api.ars-janus.com/v1
Staging: https://staging-api.ars-janus.com/v1
API endpoints are described below.
| Endpoint | Description |
|---|---|
/requests |
For requesting the creation of a new roadside service. |
/approvals |
For assigning a billing identifier to a roadside service that has been accepted. |
/cancellations |
For cancelling a previously offered or accepted roadside service. |
/statuses |
For retrieving the current information about a roadside service. |
/goa |
Update roadside service status to GOA billing disposition |
/tow |
Update roadside service status to service unsuccessful |
Client API overview
See the client API specification documentation here.
Download Postman collection here
The client API is a separate HTTPS JSON REST API server, run by the client in order to receive updates from ARS about the status of WOs and technicians. Updates are pushed by ARS to the client server. The root URL and API keys are set by the client.
GOA requested and Tow requested are statuses that might be sent through the updates endpoint. If this happens, an invocation must be done to goa or tow endpoints accordingly.
The endpoints are:
| Endpoint | Description |
|---|---|
/updates |
State updates for WO information. |
/locations |
Real-time technician location and status information. |
/results |
Receive accept or decline information for offered roadside service. |
/uploads |
Receive check-in and check-out photos from technician. |
/etas |
Real-time on route WO eta information. |
Creating a new roadside service
Creating a new roadside service requires an asynchronous 3-step exchange:
- The client submits service information to ARS’
/requestsendpoint - ARS returns the result to the client’s
/resultendpoint - The client assigns a PO number to the accepted dispatch ID by posting it to ARS’
/approvalendpoint
If a client decides not to assign a PO number (e.g., rejecting the provided ETA), the dispatchId should be cancelled via the /cancellations endpoint. The roadside service will not be created and dispatched until a PO number is assigned by the client.
Status changes
Roadside service status updates are posted to the client /updates endpoint using one of a set of enumerated options. However, modifying the job status to a tow or GOA requires intervention on the part of the client, and these statuses have ARS endpoints used for confirmation (/tow and /goa).
A roadside service being changed to a ‘GOA’ by ARS requires a change to the billing disposition of a roadside service, which must be confirmed or declined by the client posting to the ARS /goa endpoint.
A change to a ‘tow’ status by ARS means that the customer may require an additional service from another provider in addition to any agreed changes to the billing disposition, which must likewise be confirmed by the client by posting a result to /tow.
Receiving location data
The ARS API will push location data for all available technicians to the client API once a minute. The data format is a JSON object containing a set of markets, identified by three-letter codes, keying an array of objects. Each object represents an active technician in that market, and includes their last reported GPS coordinates, vehicle information, service capabilities, and whether or not they are currently assigned to a roadside service.
Location data is posted once every 60 seconds to the /locations route on the client endpoint. Note that all current location and technician data is received every time the data is posted.