Roadster Inc.
API docs by Redocly

Roadster API Documentation (1.1.0)

Download OpenAPI specification:Download

Dealer Support: dealersupport@roadster.com URL: https://roadster.com/contact Terms of Service

Introduction

Access to Roadster APIs is limited to current dealer, manufacturer, or data partners. We support a limited set of endpoints that allow our partners to access certain features of the Roadster platform for use externally or to pass us data required to better integrate our systems into the dealer's software ecosystem.

This initial API documentation has been produced to help introduce our partners to our data and experience endpoints. For additional questions, please contact our support teams at dealersupport@roadster.com

All requests should be made using HTTPS, production API endpoint https://api.roadster.com/v1

Authentication

API key based endpoints

Authentication method depends on the endpoint being used. In general, you should have been provided an API key that you will use in the HTTP header of each of your calls. For applications that will be passing us customer records as part of the user interface, you will instead encrypt the data to AES-256-CBC standards using a cipher key provided by Roadster.

The HTTP authorization header should look like this:

Authorization: Bearer <token>

You must replace <token> with the API key that Roadster provided to you.

In the case when we are calling back your endpoint, we will use the same mechanism and include your API key in our HTTP request Authorization header so that you can authorize our webhooks/callbacks ensuring that key is present on all callback requests.

Browser-based data passing

Passing data to Roadster via the browser is possible using encrypted query parameters. Encryption to AES-256-CBC standards is required using an encryption key provided to you by Roadster. All parameters should be encrypted before passing them via the URL query string.

Dealers

Active Dealers

You can get a list of active dealers for your account. The response will only include dealers which are provisioned for your API credentials. Access to dealers is provisioned by Roadster support.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Dealer Configuration

Get configuration details of a specific dealer provisioned for your account. This includes fee setups, markups and rate details.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "name": "Hyundai Demo",
  • "dpid": "hyundaidemo",
  • "address": "5300 Wible Rd",
  • "city": "Bakersfield",
  • "state": "CA",
  • "zip_code": 93313,
  • "phone": "310-949-1234",
  • "status": "Demo",
  • "partner_id": "CA317",
  • "store_host": "https://hyundaidemo.roadster.com",
  • "configuration": {
    }
}

Customers

Create Customer

You can create a new customer in the Roadster Express Strorefront for a specified dealer using a POST to the /customers endpoint. The response will include the unique identifier of the customer as well as a unique URL to the specified piece of inventory on the dealer's site which will automatically store the provided customer as active in the session.

A request to the create customer endpoint will create a customer and respond with a redirect url that can be used to redirect the customer to a landing page on the corresponding dealer site with account active in the session and pricing unlocked. In the case that the customer exists, the response will still be success but the duplicate parameter will also be true.

Authorizations:
api_key
Request Body schema: application/json

Request Payload

required
object (User)

The customer data

object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

object (VehicleRequest)

Customer's vehicle preference which will also be the resulting landing page of the returned URL.

object (Payment)

The preferred payment information.

Array of objects (Plans)

Service and protection plans that are to be included as returned from the GET service and protection plans endpoint.

Array of objects (Accessories)

List of accessories selected by the customer.

object (Analytics)

Values to be appended to the URL query in the response for analytics purposes

checkout
boolean

If true, the url in the response will direct the consumer to the checkout flow rather than the VDP for the dealer's Express Store

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "dealer": {
    },
  • "vehicle": {
    },
  • "payment": {
    },
  • "plans": [
    ],
  • "accessories": [
    ],
  • "analytics": {
    },
  • "checkout": false
}

Response samples

Content type
application/json
{}

Update Customer

Use this endpoint to assign an agent or update the agent assigned to a customer.

Authorizations:
api_key
query Parameters
id
required
integer

The Roadster customer lead ID

Request Body schema: application/json

Request Payload

object (Agent)

The assigned sales agent

object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

Responses

Request samples

Content type
application/json
{
  • "agent": {
    },
  • "dealer": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "customer": {
    }
}

Browser-based Create Customer

This browser-based URL request format allows partners to securely pass customer data into the Roadster platform using URL query parameters. The customer data is then used to create an account on the dealer's Express Storefront and bypass any price locks that may be enabled for that dealership. The request also results in lead submission consistent with the lead routing rules the dealership has setup for "Unlock Inquiry" lead types.

Sample URL, replace express.<dpid>.com with the hostname for the dealership you are referring to.

https://express.<dpid>.com/{vin}?mem=[encrypted_parameters]

The mem query parameter should contain the encrypted URL query string of the customer's contact information that you are referring to the dealership. This contact information can include any of the following key / value pairs:

Parameter Required Description
fname no The first name of the customer.
lname no The last name of the customer.
email yes The email address of the customer (used as the unique identifier for each dealership).
phone no The phone number of the customer
custid no A unique identifier from the attribution source (only used for reporting purposes).

These parameters should be placed in a standard URL query string and URL encoded before encryption. E.g. fname%3DTesting%26lname%3DBot%26email%3Dtesting%40roadster.com%26phone%3D800-505-1000

path Parameters
vin
required
string

The vehicle identification number of the requested details landing page.

query Parameters
mem
required
string

The customer's encrypted contact information (see detail below).

Responses

Request samples 

require 'openssl'
require 'base64'

def aes256_cbc_encrypt(key, data)
    key = Digest::SHA256.digest(key) if(key.kind_of?(String) && 32 != key.bytesize)
    aes = OpenSSL::Cipher.new('AES-256-CBC')
    aes.encrypt
    aes.key = key
    iv = aes.random_iv
    return aes.update(data) + aes.final, iv
end

def generate_link(vin, key = "your_encryption_key")
    data = {fname: 'Testing', lname: 'Bot', email: 'testing@example.com', phone: '800-505-1000'}

    block, iv = aes256_cbc_encrypt key, data.to_query
    mem_token = Base64.encode64(iv + block)
    escaped_token = CGI.escape mem_token
    url = "/express/" + vin + "?mem=" + escaped_token
end

Response samples

Content type
application/json
{}

Trade Valuations

Create or Update Trade Valuation

Creates or updates an existing trade in offer using the customer's email address, dealership and vehicle VIN as the unique identifier. If the customer already has a trade offer, this endpoint will update that offer. If the offer doesn't exist, it will create a new one.

Authorizations:
api_key
Request Body schema: application/json

Request Payload

dpid
required
string non-empty

The unique identifier of that dealership on the Roadster platform.

email
required
string (Email) non-empty

The customer's email

vin
required
string non-empty

The vehicle identification number.

value
required
integer non-empty

The value of the trade.

year
integer

The year of the trade.

make
string

The make of the trade.

model
string

The model of the trade.

trim
string

The trim of the trade.

mileage
integer

The mileage of the trade.

Responses

Request samples

Content type
application/json
{
  • "dpid": "umazda",
  • "email": "steve.mcqueen@example.com",
  • "vin": "4T1C11AK0LU322811",
  • "value": 0,
  • "year": 2020,
  • "make": "Toyota",
  • "model": "Camry LE",
  • "trim": "4 Cylinders 2.5L DI DOHC 152 CID",
  • "mileage": 95000
}

Response samples

Content type
application/json
{}

Payments

Payment Calculations

You can detailed pricing information for a VIN at a specified dealership. This includes cash, finance and lease options as available including existing dealer markups, fees, etc.

Authorizations:
api_key
Request Body schema: application/json

Request Payload

object (UserPayments)

Optional customer data used to calculate the payment

required
object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

required
object (Vehicle)

The vehicle the customer is interested in.

object (Payment_v2)

The parameters of the payment being requested.

object (TradePayments)

The trade in

Array of objects (Plans)

Service and protection plans that are to be included as returned from the GET service and protection plans endpoint.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "dealer": {
    },
  • "vehicle": {
    },
  • "payment": {
    },
  • "trade_in": {
    },
  • "plans": [
    ]
}

Response samples

Content type
application/json
{
  • "deals": {
    },
  • "programs": {
    }
}

Service and Protection Plans

Vehicle Plans

You can get the F+I products catalog for a specific VIN and deal structure. This will include both static plan pricing as well as dynamic pricing provided from the product vendor.

Authorizations:
api_key
query Parameters
dealer[partner_id]
required
string

The partner ID for the dealership

vin
required
string

The vehicle identification number of the vehicle to fetch SPPs for.

deal_type
required
string

The deal type if any to fetch SPPs for. One of "cash", "finance", "lease." Plans vary by deal type so this is required.

deal_rate
number <float>

The APR expressed as a percentage for the chosen deal. Required if the deal_type is "finance" or "lease."

deal_term
integer

Specific term requested for finance or lease deal_type. Required if deal_type is "finance" or "lease."

amount_financed
integer

The total amount financed. This is provided to some product providers in order to calculate dynamic prices. It is required if deal_type is "finance" or "lease."

Responses

Response samples

Content type
application/json
{
  • "plans": [
    ]
}

Web Hooks

Customer Event Web Hooks

Allows you to receive customer events at some HTTP endpoint of your choice.

When some customer event happens at a Roadster dealer partner we will send an HTTP POST request to a URL of your choice so that you can process these events as per your needs.

Roadster uses HTTP webhooks/callbacks to notify your application when a customer event happens at a dealer partner. For example like when a customer starts a purchase, an agent checks a customer in the showroom, or a customer reserves a vehicle.

Events get more data as the deal is built

You will notice that the customer events you receive will have more data as the customer or the agent move the purchasing process forward. Each subsequent event will have all the latest data as it relates to the purchase (vehicle, trade in, order, credit application). Note that message elements that are included in events like agent_sent_message will not be included in subsequent events and must be captured by your system if you want a history of these.

Key considerations

For each event occurrence, Roadster POSTs the event data to your endpoint in JSON format. The full event details are included and can be used directly after parsing the JSON into an Event object. Thus, at minimum, your endpoint needs to expect data through an HTTP POST request and confirm successful receipt of that data.

Return a 2xx status code quickly

To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code to Roadster. All response codes outside this range, including 3xx codes, indicate to Roadster that you did not receive the event.

If Roadster does not receive a 2xx HTTP status code, the notification attempt is repeated. After multiple failures to send the notification, Roadster marks the event as failed and stops trying to send it to your endpoint. After multiple days without receiving any 2xx HTTP status code responses, Roadster emails you about your failed endpoint, and automatically disables it soon after if unaddressed.

Because properly acknowledging receipt of the event callback is so important, your endpoint should return a 2xx HTTP status code prior to any complex logic that could take enough time to cause the HTTP connection to timeout.

Acceptable data to return when you receive a customer event

Since all these events pertain to a customer, it is optional for you to return your customer event identifiers as a JSON response and we will send it in subsequent events so that you may use it to look up the customer on your system. Your response should be of mimetype application/json and should be proper JSON with the format exactly as below:

{ "customer_id": "YCid6453", "lead_id": "YLid6459", "agent_id": "YAid007", "dealer_id": "YDid004" }

Any JSON elements not listed above will be ignored by Roadster.

Note that there could be some subsequent customer events that may not have the data you send back if they were scheduled for delivery before we received and processed your response.

To begin listening to customer events you must do the following:

  1. Create a callback/webhook endpoint on your server
  2. Register the endpoint with Roadster by contacting dealersupport@roadster.com

The section below details what these customer event callback messages look like.

Responses

Callbacks

Response samples

Content type
application/json
{
  • "customer_id": "YCid6453",
  • "lead_id": "YLid6459",
  • "agent_id": "YAid007",
  • "dealer_id": "YDid004"
}

Callback payload samples

Callback
POST: Customer Event
Content type
application/json
{
  • "event_type": "agent_sent_message",
  • "customer": {
    },
  • "dealer": {
    },
  • "message": {
    },
  • "vehicle": {
    },
  • "order": {
    },
  • "credit_applicant": {
    },
  • "credit_decision": {
    },
  • "agent": {
    },
  • "api_partner": {
    },
  • "event_time": "2020-07-18T13:29:02-07:00",
  • "event_id": "51jf4co07c8m7b2pbiw4jyxy8"
}

User Documents

Upload and Manage user documents in Roadster

Upload User Documents

You can upload user documents for a customer in the Roadster Express Strorefront for a specified dealer.

A request to the upload user document endpoint will upload the user docs (driver's license, license back, insurance, income, residence, other) into the User Doc-Binder.

Authorizations:
api_key
Request Body schema: application/json

Request Payload

object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

document_name
required
string

Document name

document_type
required
string
Enum: "license" "license_back" "insurance" "income" "residency" "other"

User document type being uploaded

file_name
required
string

File name with valid file extension (.jpg .jpeg .png .pdf)

relationship
required
string
Enum: "self" "co_app"

Specify whether the uploaded document is for the buyer or co-buyer

co_app_email_id
string

Co-buyer email id. Required when relationship is 'co_app'

contents
required
string

base64 encoded content

Responses

Request samples

Content type
application/json
{
  • "document_name": "license front.png",
  • "document_type": "license",
  • "file_name": "license.png",
  • "relationship": "self",
  • "contents": "Base64 content"
}

Response samples

Content type
application/json
{
  • "document_id": 1602287
}

Get list of user documents

You can fetch the list of upload user documents uploaded for a customer in the Roadster Express Strorefront for a specified dealer.

A request to the upload user docbinder endpoint will upload the user docs (driver's license, license back, insurance, income, residence, other) into the User Doc-Binder.

Authorizations:
api_key
query Parameters
id
required
integer

The Roadster customer ID

Request Body schema: application/json

Request Payload

object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

Responses

Request samples

Content type
application/json
{
  • "dealer": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Get document content

You can fetch the content for a user document in the Roadster Express Strorefront for the specified customer.

Authorizations:
api_key
path Parameters
id
required
integer

The Roadster customer ID

query Parameters
doc_id
required
integer

The Roadster user document ID

Request Body schema: application/json

Request Payload

object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

Responses

Request samples

Content type
application/json
{
  • "dealer": {
    }
}

Response samples

Content type
application/json
{
  • "contents": "Base64 content"
}

Delete user document

You can delete a user document uploaded in the Roadster Express Strorefront for the specified customer.

Authorizations:
api_key
path Parameters
id
required
integer

The Roadster customer ID

query Parameters
doc_id
required
integer

The Roadster user document ID

Request Body schema: application/json

Request Payload

object or object (Dealer)

Parameters to identify the dealership against which the call is being made.

Responses

Request samples

Content type
application/json
{
  • "dealer": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Successfully deleted user document"
}

Vehicles

Warning! These are endpoints that are currently in development and will change without notice until they reach a stable state for public release. You may not have access to all of these endpoints with your production token.

Vehicle Inventory

You can get a list of new vehicles in a dealer's inventory from this endpoint. Vehicles are sorted by VIN to ensure a unique sort order. To paginate, use the from_vin parameter. To query for updates since the last fetch, use the updated_since and in_stock parameters.

Authorizations:
api_key
query Parameters
dpid
required
string
Example: dpid=hyundaidemo

The dealer partner ID

size
number

The number of results to return

from_vin
string

To paginate results, pass the VIN of the last result, and the subsequent size vehicles will be returned.

updated_since
number
Example: updated_since=1678812101

To fetch updates since a given timestamp, pass the timestamp as seconds since the epoch.

in_stock
string

Pass any to return all vehicles including those that are out of stock; for use with updated_since.

Responses

Response samples

Content type
application/json
{
  • "vehicles": [
    ],
  • "total": 0
}

Vehicle Details

You can get detailed information about a vehicle in a dealer's inventory through using this endpoint.

Authorizations:
api_key
query Parameters
dealer[partner_id]
required
string

The partner ID for the dealership

Responses

Response samples

Content type
application/json
{}

Documents

Warning! These are endpoints that are currently in development and will change without notice until they reach a stable state for public release. You may not have access to all of these endpoints with your production token.

Templates

Templates are a definition of a document and all of the dynamic content it contains. A dealership will have multiple stored templates that contain a filename and X-Y coordinates of content that the document requires for consumer or dealer execution. Get a list of all document templates created for a specific dealership.

Authorizations:
api_key
query Parameters
dpid
required
string

Roadster's identifier for the dealership

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Template

Create a template that can be used by the dealership to generate forms for their customers. The template should describe all of the expected fields and include a base64 encoded file in PDF format.

Authorizations:
api_key
Request Body schema: application/json

Request Payload

required
object (TemplateRequest)

An object describing the document template

file_stream
required
string

A base64 encoded string version of the PDF document including the header

Responses

Request samples

Content type
application/json
{
  • "form_data": {
    },
  • "file_stream": "data:application/pdf;charset=utf-8;base64,BASE64_ENCODED_STRING"
}

Response samples

Content type
application/json
{
  • "expiration": "string",
  • "etag": "e9feaffe16bb3a6fad362a99294ad2d0",
  • "checksum_crc32": "string",
  • "checksum_crc32c": "string",
  • "checksum_sha1": "string",
  • "checksum_sha256": "string",
  • "server_side_encryption": "string",
  • "version_id": "string",
  • "sse_customer_algorithm": "string",
  • "sse_customer_key_md5": "string",
  • "ssekms_key_id": "string",
  • "ssekms_encryption_context": "string",
  • "bucket_key_enabled": "string",
  • "request_charged": "string"
}

Template Details

Get all the details associated with a specific dealership template.

Authorizations:
api_key
query Parameters
dpid
required
string

Roadster's identifier for the dealership

template_id
required
string

The unique identifier for the template

Responses

Response samples

Content type
application/json
{
  • "name": "Insurance Acknowledgement",
  • "file_name": "Hyunda Lease Insurance.pdf",
  • "description": "This is for insurance details",
  • "form_definition": {
    },
  • "id": 278,
  • "doc_identifier": "7b9b99ba-2bb7-4e63-b238-7ba7a5f03fce",
  • "created_at": "2021-07-14T22:44:42.698Z",
  • "updated_at": "2022-03-11T18:49:50.245Z",
  • "is_deleted": false,
  • "order_id": null
}

Template File

Get the file from a dealership template encoded as a base64 string

Authorizations:
api_key
query Parameters
dpid
required
string

Roadster's identifier for the dealership

template_id
required
string

The unique identifier for the template

Responses

Response samples

Content type
application/json
"JVBERi0xLjUNJeLjz9MNCjI0IDAgb2JqDTw8L0xpbmVhcml6ZWQgMS9MIDE4ODI0NS9PIDI2L0UgMTgzNjA5L04gMS9UIDE4Nzk0NC9IIFsgNDY3IDE1OV0+Pg1lbmRvYmoNICAgICAgICAgICAgICAgIA0zMyAwIG9iag08PC9EZWNvZGVQYXJtczw8L0NvbHVtbnMgNS9QcmVkaWN0b3IgMTI+Pi9GaWx0ZXIvRmxhdGVEZWNvZGUvSURbPEIzOURBQ0QyNjc2OTA4NDE4QUM4OUFEMTVENTRCNkNEPjxBQ0RGNkJCRTYwN0M0QjhBODk1QTAyRTdDQ0MzODVCMD5dL0luZGV4WzI0IDE5XS9JbmZvIDIzIDAgUi9MZW5ndGggNjcvUHJldiAxODc5NDUvUm9vdCAyNSAwIFIvU2l6ZSA0My9UeXBlL1hSZWYvV1sxIDMgMV0+PnN0cmVhbQ0KaN5iYmRgEGBgYmBgSgKRDBVgtjeYrAeR7KxAkjHaB0Q6mIJERGYCyX8uCxmYgHqXg3UxMBJF/mdg3PETIMAAwWsI/A1lbmRzdHJlYW0NZW5kb2JqDXN0YXJ0eHJlZg0wDSUlRU9GDSAgICAgICAgIA00MiAwIG9iag08PC9DIDc4L0ZpbHRlci9GbGF0ZURlY29kZS9JIDEwMC9MZW5ndGggNzUvUyAzOD4+c3RyZWFtDQpo3mJgYGBnYGDyZgASp/wZUAEjELMwcDQgi7FDMQOjN4MgkPJl2B46QfJ7gK+FnBlED9NZS4heJh+4LhYGprvuUBMfAQQYAM1+Ce8NZW5kc3RyZWFtDWVuZG9iag0yNSAwIG9iag08PC9MYW5nKGVuLVVTKS9NYXJrSW5mbzw8L01hcmtlZCB0cnVlPj4vTWV0YWRhdGEgMiAwIFIvUGFnZXMgMjIgMCBSL1N0cnVjdFRyZWVSb290IDYgMCBSL1R5cGUvQ2F0YWxvZz4+DWVuZG9iag0yNiAwIG9iag08PC9Db250ZW50cyAyOCAwIFIvQ3JvcEJveFswIDAgNjEyIDc5Ml0vR3JvdXA8PC9DUy9EZXZpY2VSR0IvUy9UcmFuc3BhcmVuY3kvVHlwZS9Hcm91cD4+L01lZGlhQm94WzAgMCA2MTIgNzkyXS9QYXJlbnQgMjIgMCBSL1Jlc291cmNlczw8L0V4dEdTdGF0ZTw8L0dTNyAzNCAwIFIvR1M4IDM1IDAgUj4+L0ZvbnQ8PC9GMSAzOCAwIFIvRjIgNDEgMCBSPj4vUHJvY1NldFsvUERGL1RleHQvSW1hZ2VCL0ltYWdlQy9JbWFnZUldL1hPYmplY3Q8PC9JbWFnZTExIDMyIDAgUj4+Pj4vUm90YXRlIDAvU3RydWN0UGFyZW50cyAwL1RhYnMvUy9UeXBlL1BhZ2U+Pg1lbmRvYmoNMjcgMCBvYmoNPDwvRmlsdGVyL0ZsYXRlRGVjb2RlL0ZpcnN0IDUzL0xlbmd0aCA1NDUvTiA4L1R5cGUvT2JqU3RtPj5zdHJlYW0NCmjenJRta9swEMe/"

Create Forms

Forms are the application of a document template against a specific order. This action will generate a new document packet of forms that the consumer and dealer are required to complete as part of the transaction.

It's important to note that forms are specific to an order and therefor cannot be created without an exisiting order id.

When forms are created, the template is autofilled with the details of the order (consumer, dealer, deal, vehicle, lender information) and then made available to the consumer and dealer for electronic signatures.

Authorizations:
api_key
Request Body schema: application/json

Request Payload

title
required
string

A title for the document packet

template_ids
required
Array of integers

An array containing one or more templates that will be added to the document packet

Responses

Request samples

Content type
application/json
{
  • "title": "Your title documents for review",
  • "template_ids": [
    ]
}

Response samples

Content type
application/json
{ }