Overview
The API is used to assign and update dealer territories.
API Token
This API requires authentication, so 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}
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”.
Response Codes
Possible response codes are:
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.
Endpoints
The HTTP endpoints that will accept the POST data are:
https://{baseaddress}/Marketing/api/DealerTerritory?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 |
Dealer identifier |
DealerLocation |
|
Max Length: 10 |
Dealer location identifier |
Territories |
X |
Collection/Array of Territory Data Schema |
Specify the territories to be assigned to the dealer through the API. Note: The assigned dealer territories will match what is sent in the API. Only territories that are pre-existing within Aimbase can be assigned through the API. To introduce new territories, get in touch with your Rollick representative for addition. Excluding any current territories from this submission will result in their removal from the dealer's assignment list. To unassign all territories from a dealer, submit an empty array or collection for the Territory parameter. e.g. [ { "DealerNumber":"ABC", "Territories":[] } ] |
Territory Data Schema
Field Name |
Required |
Format |
Description |
TerritoryLevelCode |
X |
Max Length: 20 |
Indicates the type of territory assignment. |
CountryCode |
X |
Max Length: 2 |
ISO ALPHA-2 country code |
PostalCode |
X |
Max Length: 10 |
Zip or Postal Code depending on the country. May be a full postal code or a partial depending on the territory level for assignment. |
FIPSCode |
|
Max Length: 5 |
Uniquely identifies counties based on the Federal Information Processing Standard (FIPS) |
County |
|
Max Length: 25 |
County name |
State |
|
Max Length: 50 |
State code or abbreviation. |
NOTE: the behavior of the service end point is described below.
Behavior
Posting dealer territories will update the complete territory assignment collection for the dealer. The service expects all dealer territories to be sent in the API call. It will not append territory assignments to an existing dealer. Instead the territories posted will replace the current dealer territories.
To remove a dealer territory, it is simply not included in the collection of territories posted to the API end point.
Territory Level Codes
The codes below control the type of territory area being assigned to the dealer.
Code |
Supported Country Code |
Description |
Required Territory Values |
ZIP |
US | ZIP or Postal code level territories |
TerritoryLevelCode, CountryCode, PostalCode |
|
County
|
US | County (FIPS) level |
TerritoryLevelCode, CountryCode, FIPSCode |
|
State
|
US |
State/Province level
|
TerritoryLevelCode, CountryCode, State |
|
Country
|
Country level territory
|
TerritoryLevelCode, CountryCode |
|
|
CA FSA
|
CA |
Canadian 3 digit FSA Postal code level territory
|
TerritoryLevelCode, CountryCode, PostalCode |
| CA Postal | CA | Canadian full postal code level territory | TerritoryLevelCode, CountryCode, PostalCode |
|
AU Postal
|
AU |
Australian Postal Code level territories
|
TerritoryLevelCode, CountryCode, PostalCode |
|
DE Partial Postal
|
DE |
German Partial Postal Code level territories (first 2 digits of code)
|
TerritoryLevelCode, CountryCode, PostalCode |
|
FR Partial Postal
|
FR |
French Partial Postal Code level territories (first 2 digits of code)
|
TerritoryLevelCode, CountryCode, PostalCode |
APPENDIX A – Sample POST/Response (XML)
Post:
<Dealers> <Dealer> <DealerNumber>1000</DealerNumber> <Territories> <Territory> <TerritoryLevelCode>ZIP</TerritoryLevelCode> <CountryCode>US</CountryCode> <PostalCode>63368</PostalCode> </Territory> <Territory> <TerritoryLevelCode>ZIP</TerritoryLevelCode> <CountryCode>US</CountryCode> <PostalCode>63026</PostalCode> </Territory> </Territories> </Dealer> </Dealers>
Response:
<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Dealer> <Status>Success</Status> <StatusMessage>Dealer's territories successfully updated.</StatusMessage> <Messages /> <DealerNumber>1000</DealerNumber> <Territories> <Territory> <TerritoryLevelCode>ZIP</TerritoryLevelCode> <CountryCode>US</CountryCode> <PostalCode>63026</PostalCode> <FIPSCode>29189</FIPSCode> <County>Saint Louis</County> <State>MO</State> </Territory> <Territory> <TerritoryLevelCode>ZIP</TerritoryLevelCode> <CountryCode>US</CountryCode> <PostalCode>63368</PostalCode> <FIPSCode>29183</FIPSCode> <County>Saint Charles</County> <State>MO</State> </Territory> </Territories> </Dealer> </Dealers>
APPENDIX B – Sample POST/Response (JSON)
Post:
[
{
"DealerNumber":"1000",
"DealerLocation":null,
"Territories":[
{
"TerritoryLevelCode":"ZIP",
"CountryCode":"US",
"PostalCode":"63368"
},
{
"TerritoryLevelCode":"ZIP",
"CountryCode":"US",
"PostalCode":"63026"
}
]
}
]
Response:
{ "TopLevelError":null, "DealerTerritoryResponseRecords":[ { "DealerNumber":"1000", "DealerLocation":null, "Territories":[ { "TerritoryLevelCode":"ZIP", "CountryCode":"US", "PostalCode":"63026", "FIPSCode":"29189", "County":"Saint Louis", "State":"MO" }, { "TerritoryLevelCode":"ZIP", "CountryCode":"US", "PostalCode":"63368", "FIPSCode":"29183", "County":"Saint Charles", "State":"MO" } ], "Id":null, "Status":"Success", "StatusMessage":"Dealer's territories successfully updated.", "Messages":[] } ] }
APPENDIX C – Sample POST/Response Remove All Territories (XML/JSON)
Post:
<Dealers> <Dealer> <DealerNumber>1000</DealerNumber> <Territories> </Territories> </Dealer> </Dealers>
Response:
<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Dealer> <Status>Success</Status> <StatusMessage>Dealer's territories successfully updated.</StatusMessage> <Messages /> <DealerNumber>1000</DealerNumber> <Territories> </Territories> </Dealer> </Dealers>
Post:
[ { "DealerNumber":"1000", "Territories":[] } ]
Response:
{ "TopLevelError":null, "DealerTerritoryResponseRecords":[ { "DealerNumber":"1000", "DealerLocation":null, "Territories":[], "Id":null, "Status":"Success", "StatusMessage":"Dealer's territories successfully updated.", "Messages":[] } ] }
APPENDIX D – Sample Failed Responses (XML/JSON)
The error responses below were generated by submitting without a required field.
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>DealerNumber</Field> <Message>The DealerNumber field is required.</Message> </Message> </Messages> <Territories /> </Dealer> </Dealers>
JSON Response
{ "TopLevelError":null, "DealerTerritoryResponseRecords":[ { "DealerNumber":null, "DealerLocation":null, "Territories":[ ], "Id":null, "Status":"Failure", "StatusMessage":"Dealer failed validation", "Messages":[ { "Field":"DealerNumber", "Message":"The DealerNumber field is required." } ] } ] }
The error responses below are generated by submitting a non-existent dealer number.
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>Could not find dealer with number: 1000 and location: .</StatusMessage> <Messages /> <DealerNumber>1000</DealerNumber> <Territories /> </Dealer> </Dealers>
JSON Response
{ "TopLevelError":null, "DealerTerritoryResponseRecords":[ { "DealerNumber":"1000", "DealerLocation":null, "Territories":[ ], "Id":null, "Status":"Failure", "StatusMessage":"Could not find dealer with number: 1000 and location: .", "Messages":[ ] } ] }
The error responses below were generated by submitting data that could not be parsed into the correct format.
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, 1).</Message> </TopLevelError> </Dealers>
JSON Response
{ "TopLevelError":{ "Message":"An unhanded error occurred. Object reference not set to an instance of an object." }, "DealerTerritoryResponseRecords":[ ] }