Getting Started with EasyTerritory REST APIs


Overview

EasyTerritory provides REST service endpoints for developers to extend and build upon the features and capabilities of their EasyTerritory application.  For instance, developers can query the location of a specific record in an EasyTerritory project and retrieve information about the territory that the record falls in.  Also, if you have a need to map address records to a map interface, you would benefit from the EasyTerritory geocoding service endpoint that takes a set of addresses and converts them to their latitude and longitude equivalents.

Authenticate

In order to call the EasyTerritory REST services, developers need to first authenticate to EasyTerritory and retrieve an OI Token.

In your http request you must specify a JSON object that holds your EasyTerritory credentials.

{\"username\":\"mike\",\"password\":\"Password\"}

Here is sample code for a call to the EasyTerritory Login REST endpoint.

$.ajax({
     url: \"https://apps.easyterritory.com/{yourGuid}/{YourEZTInstanceType [DEV], [TEST], or [APP]. Note APP = Production.}/REST/Login/Login\",
     type: \"POST\", 
     data: JSON.stringify({\"username\":\"mike\",\"password\":\"Password\"}), 
     contentType: \"application/json\",
 });

You will need to retrieve the “token” property from the JSON response.

{
 "changePwdOnNextLogin": false,
 "email": "email@email.com",
 "firstName": "Benton",
 "id": "user id",
 "isAdmin": false,
 "isCrmWriter": true,
 "isMobileOnly": false,
 "lastName": "Belcher",
 "password": "password string",
 "restToken": "rest token guid",
 "token": "token guid",
 "ttlMillis": 31536000000,
 "username": "bbelcher"
}

Next set that as a cookie in your requests to the EasyTerritory REST endpoints.

Please note: If you are making calls to EasyTerritory under the same domain (and same protocol http or https) as your EasyTerritory application, then you can use client-side (in the browser) JavaScript. Otherwise, for cross-domain access, you will have to write a server-side proxy (like a c#/ashx HTTP handler.) to call EasyTerritory REST APIs. If you use a server side approach you will need to provide your domain name to an EasyTerritory admin for permitted origin configuration.

Postman EZT project for download

Next steps:

Easyterritory Geocoding Service

Location Lookup Service