Getting Started

Getting Access to LOCATE

Each company using LOCATE is assigned a unique subdomain under the locateinv.com domain to house their instance of LOCATE. To access data within a LOCATE instance you will need to have a user created within this subdomain. LOCATE has two types of users (Standard and API). Standard users have access to login into the LOCATE web and mobile applications. Authentication for this type of user is via an email and password combination. This type of user has various limitations more tuned for a human user interacting with LOCATE and is subject to our per user license limits/costs including the ability for users to kick other users out. API type users are limited to API based access and have a fixed rate of access allocated to them and cannot be kicked from sessions. For all code related calls you will want to use the latter (API) type user.

Create an API User

Login to the LOCATE instance with a user account that has Administrator (the user is a member of the Administrators group) access. In the top right corner click on Setup > Users. Click on the “New User” button in the top right of the table. Enter a First Name and Last Name to identify the the account. Select “API” from the User Type drop down. Enter an Email Address and click “Save”. You will be presented with the new user’s details and most importantly their “API Key”. Keep this key safe as it is a long lived token granting access to the LOCATE instance with all the rights/privileges granted to the API user.

Access Control Lists and Permissions

By default all newly created API users do not have any rights to the LOCATE instance. Based on the scope of access required by your code/application you will need to grant the necessary access on the “Permissions” tab of your newly created user as well as through the Settings (gear icon) in the top right (alternatively you can add your API user to groups where they will inherit permissions/ACLs). Under each setting group there are “Access Tabs” these control the basic CRUD access for each user/group within LOCATE. On root endpoints not having read access will not result in an error, but an empty response. Errors are only thrown when trying to access/manipulate a specific object since LOCATE supports object level permissions.

Building Your First Request

There are three required headers when accessing the LOCATE API:

HeaderValue
Content-Typeapplication/json
Acceptapplication/json
AuthorizationBasic base64encode([API Key]:[API Key])
The authorization header is a standard “basic authentication” header. Many programming libraries offer helper methods for generating these headers. The username/password for our header is the API Key you received for your API User. The square brackets are provided for clarity and should not be included in your actual request. Use whatever base64 encoding function you have available to encode the values.

The root URL to the LOCATE API contains the subdomain of the LOCATE instance you are accessing (the same one from the web browser when you created your user).

https://{subdomain}.locateinv.com/

For our first request we will ask LOCATE for the list of sales order types. This will be a GET request to the /salesordertype endpoint. The full URL would be https://{subdomain}.locateinv.com/salesordertype.

If you received a JSON response with an array of objects, and each object contains an id and name field, then Congratulations! You have successfully completed your first API request against the LOCATE API.

If you received a 401 response then check your API Key and Authorization header. You need to use the API Key as the username and password for the basic authentication header. Don’t forget the key word “Basic ” before the base 64 encoded “API Key:API Key” string.

Here is a sample request using curl:

curl –user [API Key]:[API Key] –header “Content-Type: application/json” –header “Accept: application/json” https://[subdomain].locateinv.com/salesordertype

Substitute your API Key and subdomain into the request. Do not include the square brackets.

Sending Data to the Server

LOCATE accepts data in several different places depending on the type of request being made:

Request VerbPayload Location
GETURL parameters
POST,PUTPOST parameters (in header) or JSON encoded in the body of the request

PHP Code Sample

/**
* Constants
*/
define('LOCATE_SUBDOMAIN', '[insert subdomain here]');
define('LOCATE_API_KEY', '[insert API Key here]');

function locateRequest($curlRequestType, $endpoint, $postData = null) {

    // Create CURL Request
    $curlRequest = curl_init();

    // Set CURL Options
    curl_setopt($curlRequest, CURLOPT_CUSTOMREQUEST, $curlRequestType);
    curl_setopt($curlRequest, CURLOPT_URL, 'https://' . LOCATE_SUBDOMAIN . '.locateinv.com' . $endpoint);
    curl_setopt($curlRequest, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    curl_setopt($curlRequest, CURLOPT_RETURNTRANSFER, true);

    // Check for POST Data
    if($postData !== null) {
        curl_setopt($curlRequest, CURLOPT_POSTFIELDS, json_encode($postData));
    }

    // Basic Auth
        curl_setopt($curlRequest, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
        curl_setopt($curlRequest, CURLOPT_USERPWD, LOCATE_API_KEY);
    }
    // Execute CURL Request
    $response = curl_exec($curlRequest);
    $httpCode = curl_getinfo($curlRequest, CURLINFO_HTTP_CODE);

    // Check HTTP Status Code
    if($httpCode == 200 || $httpCode == 201) {
        return (json_decode($response));
    }
    else {
        throw new Exception($httpCode . ' - ' . $response);
    }
}

// Get One Customer
$customerResponse = locateRequest('GET', '/customer?perPage=1');
print_r($customerResponse);