Aimbase Dealer Search API

Overview 

The purpose of this document is to define the request and response XML/JSON for searching dealers. 

Possible Response Codes 

  • 201 (Created). This response indicates that the dealer territory data was successfully parsed. The body of the response will contain the success or failure status for each item that was submitted in the request. NOTE: The response record details for each item will be returned in the order that they were submitted. 

  • 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 C for the structure of the error response. 

  • 500 (Internal Server Error). An unknown error occurred during the import. 


Authentication

The Lead API requires authentication. The HTTP POST will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token. 

Authenticate message header example:

Authenticate: Avala-Api {username}:{token}


Post Information

HTTP Endpoint 

 https://{baseaddress}/api/DealerSearch?manufacturer={manufacturerCode} 

 

Dealer Search Data Schema 

Field Name 

Required 

Format 

Description 

DealerNumber 

 

Max Length: 20 

Manufacturer dealer number. Used to identify a dealer in the system.  The service will match to dealers that have a dealer number that starts with the parameter value. 

DealerLocation 

 

Max Length: 10 

Manufacturer dealer location. Used to identify a dealer’s sub location in the system.  The service will match to dealers that have a dealer location that starts with the parameter value. 

DealerTypes

 

Collection/Array of strings. 

Classification of dealers in the system. Values "S" (Standard) and "D" (Default) are the common values. 

DealerGroups 

 

Collection/Array of strings.

Dealer segments often grouped based on the dealer number. 

Brands 

 

Collection/Array of strings. 

A list of brands that the dealer must be assigned too.   

BeginCreateDate 

 

DateTime  

The minimum value for the dealer create date and time. 

EndCreateDate 

 

DateTime  

The maximum value for the dealer create date and time. 

BeginUpdateDate 

 

DateTime  

The minimum value for the dealer update date and time. 

EndUpdateDate 

 

DateTime 

The maximum value for the dealer update date and time. 

City 

 

Max Length: 35 

City value.  Needs to be an exact match. 

State 

 

Max Length: 3 

State code or abbreviation 

PostalCode 

 

Max Length: 10 

Zip or Postal Code depending on the country.   

County 

 

Max Length: 25 

County value.  Needs to be an exact match. 

FIPSCode 

 

Max Length: 5 

Uniquely identifies counties based on the Federal Information Processing Standard (FIPS) 

CountryCode 

 

Max Length: 2 

ISO ALPHA-2 country code 

IsActive 

 

Max Length: 1 

A Value of “1” indicates the dealer is active and a value of “0” indicates in-active. 

Customs 

 

Collection/Array of CustomData data schema. 

Additional data arguments that can be configured for custom dealer properties and submitting in name / value pairs. 

PageNumber  


Integer  Format 

Default value is 1. 

PageSize 

 

Max Length: 4  

Default value is 20 and the maximum value is 1000. 

OrderBy 

 

Max Length: 25 

Default value is “Id”.  Valid order by fields: Id, Name, DealerNbr, City, State, PostalCodeCountryCodeCreateDateUpdateDate 

IsOrderByDescending 

 

Max Length: 

A Value of “1” indicates the results should be sorted in descending order and a value of “0” indicates ascending. 

 

Behavior 

 Posting search criteria will restrict the dealers returned based on the dealer details, brands, and territory assignments.  The service requires a manufacturer code to be passed in the url of the request and the dealer search criteria to be in the body of the POST request.  The service will return a collection of dealers and also include the total count of dealers for the search, the current page size, and the current page.  To pull all results of the search the client is responsible for managing the paging and making subsequent API calls to retrieve all results.  


XML Example Post

<DealerSearchRequest> 
  <CountryCode>US</CountryCode> 
  <PostalCode>63026</PostalCode> 
  <IsActive>1</IsActive> 
</DealerSearchRequest> 


Json Example Post

{ 
   "CountryCode":"US", 
   "PostalCode":"63026", 
   "IsActive":"1" 
} 


Sample Success Response (XML/JSON)


<DealerSearchResponse> 
  <Total>1</Total> 
  <PageSize>20</PageSize> 
  <PageNumber>1</PageNumber> 
  <Dealers> 
    <Dealer> 
      <Id>1</Id> 
      <DealerNumber>1000</DealerNumber> 
      <DealerLocation>2</DealerLocation> 
      <Name>Sample Dealer</Name> 
      <DealerTypeCode>S</DealerTypeCode> 
      <DealerType>Standard</DealerType> 
      <DealerGroupCode>DG1</DealerGroupCode> 
      <DealerGroup>Dealer Group 1</DealerGroup> 
      <ManufacturerCode>SM001</ManufacturerCode> 
      <Manufacturer>Sample Manufacturer</Manufacturer>       
      <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> 
      <County>St Louis</County> 
      <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> 
      <Latitude>38.5408166</Latitude> 
      <Longitude>-90.4657284</Longitude> 
      <CreateDate>2014-06-12T15:28:38.39</CreateDate> 
      <UpdateDate>2014-06-15T12:54:23.07</UpdateDate> 
      <Brands> 
        <Brand> 
          <Code>BRD01</Code> 
          <Name>Brand One</Name> 
        </Brand> 
        <Brand> 
          <Code>BRD02</Code> 
          <Name>Brand Two</Name> 
        </Brand> 
      </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> 
</DealerSearchResponse>
{ 
   "Dealers":[ 
      { 
         "Id":"1", 
         "DealerNumber":"1000", 
         "DealerLocation":"2", 
         "Name":"Sample Dealer", 
         "DealerTypeCode":"S", 
         "DealerType":"Standard", 
         "DealerGroupCode":"DG1", 
         "DealerGroup":"Dealer Group 1", 
         "ManufacturerCode":"SM001", 
         "Manufacturer":"Sample Manufacturer", 
         "Contact":"John Doe", 
         "Email":"john@doe.com", 
         "Address1":"123 Main Street", 
         "Address2":null, 
         "City":"St Louis", 
         "State":"MO", 
         "PostalCode":"63026", 
         "County":"St Louis", 
         "CountryCode":"US", 
         "Phone":"16363439988", 
         "Fax":"16363439987", 
         "TollFree":"18883439988", 
         "DealerUrl":"www.sampledealer.com", 
         "District":"MidWest", 
         "Territory":"Missouri", 
         "Region":"St. Louis", 
         "IsActive":"1", 
         "Latitude":"38.5408166", 
         "Longitude":"-90.4657284", 
         "CreateDate":"2014-06-12T15:28:38.39", 
         "UpdateDate":"2014-06-15T12:54:23.07", 
         "Brands":[ 
            { 
               "Code":"BRD01", 
               "Name":"Brand One" 
            }, 
            { 
               "Code":"BRD02", 
               "Name":"Brand Two" 
            } 
         ], 
         "Customs":[ 
            { 
               "FieldName":"Secondary Contact", 
               "FieldValue":"Jane Doe" 
            }, 
            { 
               "FieldName":"Facility", 
               "FieldValue":"Sales and Service" 
            } 
         ] 
      } 
   ], 
   "Total":1, 
   "PageSize":20, 
   "PageNumber":1 
}