Dealer Create & Update API

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
Email		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: 80
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. Custom Dealer Type Codes: instance specific.

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.