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 }