Overview
This API is used to send dealer data to Aimbase to create new dealers or update existing dealers.
Once a dealer has been created, you can add dealer contacts with the Dealer Contacts API.
API Token
All web service requests must have a valid API token added to the request’s Authenticate message header in the Avala-Api schema.
Authenticate: Avala-Api {username}:{token}
An API token that is valid for one hour may be retrieved using the Login API call or an API token that does not expire may be created by AVALA. (See the Aimbase Authentication Web Service Specification document)
Content-Types
The API will accept JSON or XML based on what content type is set in the Content-Type HTTP header. To submit JSON data set the Content-Type header to “application/json”, to submit XML set the Content-Type HTTP header to “application/xml”.
Process Flow
The process flow of sending dealer(s) to the system is as follows:
New dealers should be included in a request sent via an HTTP POST to the end point. The request may contain one or more dealers. Any dealer that matches an existing dealer number will be updated.
Each dealer is validated against the Dealer XSD.
A response is generated containing a success or failure for each registration provided in the request.
Any dealer successfully passing the first wave of validation checks will be assigned an Id that uniquely identifies the record in the staging process. This Id will be included in the response.
Response Codes
Possible response codes are:
201 (Created). This response indicates that the Dealer data was successfully parsed. The body of the response will contain the success or failure status for each dealer that was submitted in the request.
400 (Bad Request). Along with the 400 response, the body of the response will contain an error message describing why the request was a bad request. See Appendix D for the structure of an error response.
500 (Internal Server Error). An unknown error occurred during the import.
Endpoints
The HTTP endpoint that will accept the POST data are:
https://{baseaddress}/api/dealer?manufacturer={manufacturerCode}
Below is the list of properties that are accepted in the POST body.
Dealer Data Schema
Field Name | Required | Format | Description |
DealerNumber | X | Max Length: 20 | Manufacturer dealer number. Used to identify a dealer in the system. |
DealerLocation | Max Length: 10 | Manufacturer dealer location. Used to identify a dealer’s sub location in the system. | |
Name | X | Max Length: 80 | Name of the dealer |
Contact | Max Length: 50 | Primary dealer contact | |
Max Length: 999 | Email address of dealership. | ||
Address1 | Max Length: 64 | ||
Address2 | Max Length: 64 | ||
City | Max Length: 35 | ||
State | Max Length: 3 | ||
PostalCode | Max Length: 10 | ||
CountryCode | Max Length: 2 | ||
Phone | Max Length: 20 | ||
Fax | Max Length: 20 | ||
TollFree | Max Length: 20 | ||
Url | Max Length: 256 | ||
District | Max Length: 50 | ||
Region | Max Length: 1000 | ||
Territory | Max Length: 1000 | ||
IsActive | X | Max Length: 1 | A Value of “1” or “true” indicates the dealer is active and a value of “0” or “false” indicates in-active. |
Brands | Collection/Array of strings. | A list of valid brand codes. If no list is supplied, the dealer will be linked to all brands. | |
Customs | Collection/Array of CustomData data schema. | Additional data arguments that can be configured for custom dealer properties and submitting in name / value pairs. | |
DealerType | Max Length: 20 |
The Code of a dealer type within the system. Standard Dealer Type Codes: "S" for Standard Dealer, "D" for Default Dealer. |
CustomData Data Schema
Field Name | Required | Format | Description |
FieldName | X | Max Length: 50 | The field name of the custom field. |
FieldValue | X | Max Length: 2048 | The field value of the custom field. |
APPENDIX A – Sample POST/Response (XML)
Post:
<Dealers> <Dealer> <DealerNumber>1000</DealerNumber> <DealerLocation>2</DealerLocation> <Name>Sample Dealer</Name> <Contact>John Doe</Contact> <Email>john@doe.com</Email> <Address1>123 Main Street</Address1> <Address2></Address2> <City>St Louis</City> <State>MO</State> <PostalCode>63026</PostalCode> <CountryCode>US</CountryCode> <Phone>16363439988</Phone> <Fax>16363439987</Fax> <TollFree>18883439988</TollFree> <DealerUrl>www.sampledealer.com</DealerUrl> <District>MidWest</District> <Territory>Missouri</Territory> <Region>St. Louis</Region> <IsActive>1</IsActive> <Brands> <string>Brand1</string> <string>Brand2</string> <string>Brand3</string> </Brands> <Customs> <Custom> <FieldName>Secondary Contact</FieldName> <FieldValue>Jane Doe</FieldValue> </Custom> <Custom> <FieldName>Facility</FieldName> <FieldValue>Sales and Service</FieldValue> </Custom> </Customs> </Dealer> </Dealers>
Response:
<Dealers> <Dealer> <Id>158203</Id> <Status>Success</Status> <StatusMessage>Dealer successfully received</StatusMessage> <Messages /> <DealerNumber>1000</DealerNumber> <DealerLocation>2</DealerLocation> </Dealer> </Dealers>
APPENDIX B – Sample POST/Response (JSON)
Post:
[ { "DealerNumber":"1000", "DealerLocation":"2", "Name":"Sample Dealer", "Contact":"John Doe", "Email":"john@doe.com", "Address1":"123 Main Street", "Address2":null, "City":"St Louis", "State":"MO", "PostalCode":"63026", "CountryCode":"US", "Phone":"16363439988", "Fax":"16363439987", "TollFree":"18883439988", "DealerUrl":"www.sampledealer.com", "District":"MidWest", "Territory":"Missouri", "Region":"St. Louis", "IsActive":"1", "Brands":[ "Brand1", "Brand2", "Brand3" ], "Customs":[ { "FieldName":"Secondary Contact", "FieldValue":"Jane Doe" }, { "FieldName":"Facility", "FieldValue":"Sales and Service" } ] } ]
Response:
{ "TopLevelError":null, "DealerResponseRecords":[ { "DealerNumber":"1000", "DealerLocation":"2", "Id":"158209", "Status":"Success", "StatusMessage":"Dealer successfully received", "Messages":[ ] } ] }
APPENDIX C – Sample Failed Responses (XML/JSON)
The error responses below were generated by submitting a dealer without the required field “IsActive”.
XML Response
<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Dealer> <Status>Failure</Status> <StatusMessage>Dealer failed validation</StatusMessage> <Messages> <Message> <Field>IsActive</Field> <Message>The IsActive field is required.</Message> </Message> </Messages> <DealerNumber>1000</DealerNumber> <DealerLocation>2</DealerLocation> </Dealer> </Dealers>
JSON Response
{ "TopLevelError":null, "DealerResponseRecords":[ { "DealerNumber":"1000", "DealerLocation":"2", "Id":null, "Status":"Failure", "StatusMessage":"Dealer failed validation", "Messages":[ { "Field":"IsActive", "Message":"The IsActive field is required." } ] } ] }
The error responses below were generated by submitting a dealer that could not be parsed into the correct data schema.
XML Response
<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <TopLevelError> <Message>Bad request: There is an error in XML document (1, 9).</Message> </TopLevelError> </Dealers>
JSON Response
{ "TopLevelError" : { "Message" : "Bad request: Unexpected end when desterilizing array. Path '[0]', line 75, position 1." }, "DealerResponseRecords" : [] }