This document provides an overview of the AutoAlert API and describes the various data resources that are returned by the API methods and how they relate to each other. For specific details about each API method please go to the main help page at API Help. Accessing any of the API methods requires an API access token. Dealers wishing to integrate AutoAlert data with CRM or other vendor systems using this API will need to work with AutoAlert to set up an account and receive an access token.
The base URL to access the API is https://api.autoalert.com. Using this address without appending an API method will return the online help page. The main help page lists every API method organized by categories mostly based on the specific resources that are associated with the methods. For example, the User category has methods that deal with user data, e.g. authenticate, getusers, etc.
To get specific information about an API method, click on the method name. This will take you to a page that describes the request and response in detail. It also shows sample data formats in JSON and XML. The sample formats do not include realistic data. It only shows dummy data that matches the proper data type. This helps at least to show the data structure that is required for input or what will be returned as output.
The end point URL for a given method call consists of the base URL combined with the category and method name, e.g. https://api.autoalert.com/user/getusers. All requests must be submitted as POST requests with all necessary parameters included in the request body.
Here is an example of a method call by using JQuery:
var data = { "token": "EGAC0365-B1B8-432C-B2AE-70AFCD9082D7", "fromDateUTC": "1/1/2014" };
$.ajax({
dataType: "json",
contentType: "application/json",
type: "POST",
url: "https://api.autoalert.com/vehicle/getnotowned",
data: JSON.stringify(data),
success: success
});
In AutoAlert the term Entity refers to a data element that represents a combination of a customer and a vehicle. An AutoAlert dealsheet displays data for a specific entity. The unique identifier for an entity is called EntityID. The data type for EntityID is a GUID (globally unique identifier).
To get a list of all current entities for a store in AutoAlert you can call the API method Entity/getallentities. This method includes a date parameter so that you can return only entities that have been added or updated since the input date. By providing a minimum date value you can return all entities in the system for a dealer. So to minimize data traffic you can make an initial call to get all entities and after that you can make daily calls (or some regular interval) that only retrieves new or updated entities by specifying a FROM date that is equal to the date the method was last called.
Included in the data returned from getallentities are fields VIN, SaleRODate and IsConquest. VIN is the VIN number of the vehicle associated with the Entity record. SaleRODate is either the deal date associated with the original sale of the vehicle if the vehicle was sold by the dealership or the latest RO date if the vehicle is a conquest (serviced at the dealership but not purchased there). If the SaleRODate represents a sale date (deal date) the IsConquest flag will be false. Otherwise, if the date is the latest RO date, the IsConquest flag will be true. The VIN and SaleRODate can be used to link AutoAlert Entity records with vehicle sale data in the store CRM system.
Several of the data items returned for each entity (EntityID & VHash) can be used to help construct a URL to access the AutoAlert dealsheet for the given entity. See the section below titled “Accessing a Dealsheet using the AutoAlert API” for more information.
The API method User/getusers will return a list of all current AutoAlert enabled users for a store. It includes basic information such as First Name, Last Name, Email. It also includes an AccessCode that can be used to directly access a dealsheet in a browser without having to log in with the user’s credentials. See the section below titled “Accessing a Dealsheet using the AutoAlert API” for more information.
The getusers method should probably be called on a daily basis to get the most recent list of AutoAlert users. This list can then be mapped to dealer employees in the dealer’s CRM system or other vendor system by matching up data by the FirstName, LastName and Email fields. Having the AccessCode associated with the employee will now allow access to a dealsheet by that employee assuming they have the proper access rights to the dealsheet.
When calling getusers you can specify whether or not to generate new access codes. To generate new access codes set the refreshAccessCodes parameter to true. This will delete any existing access codes and generate new ones which will expire in 48 hours. If you set this parameter to false when calling getusers it will return the user list but will not generate new access codes.
There are two methods that can be used for accessing an AutoAlert Dealsheet. Both require that a URL be constructed by combining several data items and appending them to a base URL. The data items required can be obtained by making one or more calls to API methods.
In one case no user-specific data is supplied and the user will be required to authenticate and will be redirected to a login page.
In the other case, an access code which is associated with a specific user is supplied in the URL and this will enable auto-login and if successfully validated it will display the dealsheet directly.
Here are specific details about each method:
Constructing a URL with no user data supplied
Here is an example URL where no user information is included in the querystring:
https://dealer.autoalert.com/AlertDesk/DealSheet/Show?e=11a6a5aa-2fe4-e211-9a18-782bcb5c10c8&sn=auto
This URL is constructed by including the following parts:
| URL Part | Description |
| https://dealer.autoalert.com/ | This is the base URL which should be obtained by calling the Dealer/getdealer method. |
| AlertDesk/Dealsheet/Show | This is a constant and will not change. |
| ?e=xxx | xxx = EntityID which uniquely identifies the customer/vehicle combination. This is obtained by calling Entity/getallentities method to return a list of all entities within a store. |
| &sn=auto | This querystring parameter does not need to change. |
If a user knows the credentials for a given user account, this URL can be used and the user will be prompted for the credentials. Once the credentials are validated the user will be redirected to the proper dealsheet assuming the user has the proper access rights to that dealsheet.
Constructing a URL with user access code supplied
Here is an example URL:
https://dealer.autoalert.com/external/dealsheet?e=F23A2483-DF30-E111-91ED-0026B962EF04&v=0x5718035b8c057cf23d8ab6529e48cb2f&sn=auto&c=5ed4158e41eb481e95d125c6b866e9c4&d=123456
This URL is constructed by including the following parts:
| URL Part | Description |
| https://dealer.autoalert.com/ | This is the base URL which should be obtained by calling the Dealer/getdealer method. |
| external/dealsheet | This is a constant and will not change. |
| ?e=xxx | xxx = EntityID which uniquely identifies the customer/vehicle combination. This is obtained by calling Entity/getallentities method to return a list of all entities within a store. |
| &v=xxx | xxx = hash encryption of the EntityID. This is obtained along with the EntityID when calling Entity/getallentities. |
| &sn=auto | This querystring parameter does not need to change. |
| &c=xxx | xxx = a user access code. This is obtained when calling User/getusers to get a list of all users for a store. Each user has their own unique access code. |
| &d=xxx | xxx = the Dealer ID, obtained when calling Dealer/getdealer. |
This form of the URL can be used if you have previously obtained a list of all AutoAlert users which provides user details such as First Name, Last Name, Email Address as well as a dealsheet access code. This method allows access to a dealsheet by using the access code to automatically log in the associated user to the system before presenting the dealsheet. The user associated with the access code must have the proper access rights for a given dealsheet.
Using the same access code described above for displaying a dealsheet, you can use the /external/page URL to automatically log in to AutoAlert and go to a specific page entered with the pg parameter. Any pages normally accessible for the user associated with the access code will be accessible via this URL.
Here is an example URL:
https://dealer.autoalert.com/external/page?c=5ed4158e41eb481e95d125c6b866e9c4&pg=AlertDesk/Opportunity&d=123456
This URL is constructed by including the following parts:
| URL Part | Description |
| https://dealer.autoalert.com/ | This is the base URL which should be obtained by calling the Dealer/getdealer method. |
| external/page | This is a constant and will not change. |
| ?c=xxx | xxx = a user access code. This is obtained when calling User/getusers to get a list of all users for a store. Each user has their own unique access code. |
| &pg=xxx | xxx = a page reference. For example, AlertDesk/DashBoard/Index displays the main Dashboard page. AlertDesk/Opportunity displays the Opportunities page. |
| &d=xxx | xxx = the Dealer ID, obtained when calling Dealer/getdealer. |