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: 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.
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.  

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" : [] 
}