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: 

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

  1. Each dealer is validated against the Dealer XSD. 

  1. A response is generated containing a success or failure for each registration provided in the request. 

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

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