Dealer Territory API


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 

TerritoryLevelCodeCountryCodePostalCode 

County 

 

US

County (FIPS) level 

TerritoryLevelCode, CountryCodeFIPSCode 

State 

 

US

State/Province level 

 

TerritoryLevelCodeCountryCode, State 

Country 

 


Country level territory 

 

TerritoryLevelCodeCountryCode 

CA FSA 

 

CA

Canadian 3 digit FSA Postal code level territory 

 

TerritoryLevelCodeCountryCodePostalCode 

CA Postal CA Canadian full postal code level territory TerritoryLevelCodeCountryCodePostalCode

AU Postal 

 

AU

Australian Postal Code level territories 

 

TerritoryLevelCodeCountryCodePostalCode 

DE Partial Postal 

 

DE

German Partial Postal Code level territories (first 2 digits of code) 

 

TerritoryLevelCodeCountryCodePostalCode

FR Partial Postal 

 

FR

French Partial Postal Code level territories (first 2 digits of code) 

 

TerritoryLevelCodeCountryCodePostalCode 

 

 

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