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, PostalCode, CountryCode, CreateDate, UpdateDate
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 
}

Rollick Knowledge