0

Admin Services API

Overview: Services REST API

The Lotame platform is primarily accessed through the user interface of our web application. Users can manage first party data, build audience segments, view analytics and perform administrative actions. In addition to the web application, developers can use the Lotame Services API to automate functionality or pull information from the Lotame platform into another application.

For example, you may:  

  • view stats about your audiences and behaviors
  • navigate categories in a taxonomy, search for behaviors, and view their stats
  • create and edit audiences, estimate their size, and track their stats
  • activate an audience to a partner for targeting

The Services API is a family of services based on a REST architecture and are accessed over HTTPS using the GET, PUT, POST, and DELETE methods. All service calls are authorized by a token based authentication: Header and all data in transit is protected by transport layer security (SSL/TLS). Entities produced by service calls are formatted as JSONs. Appropriate HTTP response codes are used to indicate the status of each call and should be interpreted according to the specification.

Security and Authentication

This section reviews how Lotame secures the API and provides tools for authentication.

Transport Layer Security

To ensure the privacy and integrity of all data in transit between clients and service resources (including credentials for authentication), the Services API is only accessible through the HTTPS protocol.

Data Scoping

Many of the Services API resources provide access to data that is specific to a particular client or network. In such cases the data returned will be scoped to the requested client(s). If a request is not authorized to access the data for a given client, a 403 Forbidden response will be returned.

Authorized Access

All access to the Lotame Services API resources is restricted by a token based authentication scheme.  To acquire a reusable API token for access to the Lotame Services API, the following steps are required:

  1. Login to the Lotame platform with your credentials
  2. Visit the “Manage API Tokens” section of the platform. This can be accessed in the UI by selecting your username and “Manage API Tokens” from the dropdown menu
  3. Select “Create Token Pair”
  4. Provide a description for your Token 
  5. Immediately store your Access Key and Token somewhere local that can be accessed later as needed
  6. Use your Access Key and Token pair in the header of your API request
x-lotame-token: [token]
x-lotame-access: [accesskey]

Authentication Examples 

Curl/CLI

curl -XGET -H’x-lotame-token: tokengoeshere’ -H’x-lotame-access: accesskeygoeshere’ -H’Content-Type: application/json’ https://api.lotame.com/2/users/activeUser

Java

HttpRequest r = HttpRequest.newBuilder().uri(URI.create(“https://api.lotame.com/2/users/activeUser”).header(“Content-Type”,”application/json”).header(“x-lotame-token”, “tokengoeshere”).header(“x-lotame-access”,”accesskeygoeshere”).GET().build() 

Python

r = requests.get(‘https://api.lotame.com/2/users/activeUser’, headers={‘x-lotame-token’: ‘tokengoeshere’, ‘x-lotame-access’:’accesskeygoeshere’,’Content-Type’:’application/json’})

Services API Documentation

Additional Services API documentation can be found at https://api.lotame.com/docs/. A useful feature of the Services API documentation site is the Swagger API Explorer, which allows users to test functionality directly in the documentation. 

For example, to see statistics on a behavior, click statistics and then "GET /statistics/behaviors/{behavior_id}". When that opens up it will show you the model for the response, the optional and required parameters for the request, the error status codes, and finally, a "Try it out!" button. Assuming you have entered all of the required parameters, you will make a request to the service endpoint and it will return the results to you right there in the page, including the request URL, response code, and response headers!

Please be mindful that the data you see and manipulate in the API Explorer is your Lotame Platform production data, so please exercise caution. If you delete an audience through the API Explorer, it is just like requesting a delete through the UI or API, and the audience will be deleted.

Note: there are limits in place on api endpoints to ensure platform stability. Submit a Support ticket form through this link if you believe you are hitting platform limits.

View API Calls in Real-Time 

The Lotame Platform UI is the ultimate reference for any API call and response you want to review. The platform leverages the same services and as such, it provides the base of every valid request and resulting server responses.

This Platform UI API calls can be viewed directly in your browser. For example, using the Chrome browser while working in the platform, you can open the developer tools (Press F12), navigate to the Network tab, check “Preserve log” and set the filter to api.lotame.com. With that in place, execute the UI action you are attempting to automate (behavior creation, saving an audience, loading a report, etc). All resulting calls and responses will be captured in the Network tab and can then be checked for additional details, such as URL format, endpoint syntax, JSON payloads and responses.

Let's go through an example. Say you want to make something that pulls the stats from an audience for use in an external tool. Through the API Documentation page, you can identify this call is "GET /statistics/audiences".

 

From this, we know to look for a call that contains "/statistics/audiences". From there, we can get into the platform and open the developer tools. You can choose to have this docked to the bottom of your window, the side, or in a separate window, which we will be using for this example.

 

With that open, we can set our filter to the call we are looking to learn about ("/statistics/audiences"), and load the audience stats page for any audience. Note that several calls are made, as each one populates a different section of the page.

 

Clicking on each of these will let us dig into the details of the call. Let's focus on the second one, which populates the "Stats Overview" on the page. The full URL of the call is;

https://api.lotame.com/2/statistics/audiences/65478/ranges?date_range=YESTERDAY&date_range=LAST_30_DAYS&date_range=MONTH_TO_DATE&date_range=LAST_MONTH&universe_id=1&_=1487342525774

  

You'll see we have several tabs of information, but the important ones to this will be Headers, Preview, and Response. Headers will give information on how the call was formatted, both the body of the call, and the parameters, which can be found further down in the page. The Preview and Response tabs actually give the same information, just with different formatting

 

 

The preview tab will allow you to step through the response in a bit more readable format, whereas the response tab is the raw JSON returned by the API call (which you may also break down with a tool such as  https://jsonformatter.curiousconcept.com/).

Additionally, if you are making a call to create something (new audience, behaviors, taxonomy nodes, etc), which will usually have a body / Payload, that will be in its own section of the Headers Tab. Next to that section, you can click "view source" and "view parsed" to see how the JSON is constructed there.

 

Services API GitHub Repository

Lotame has created a Github project to host real-world examples of scripts that use our API. Our goal is to collect and store scripts as a reference and collaboration library, to save time involved in repeating efforts.

If you create a script that would be beneficial for others, add your example to the repository.  Please feel free to pull a copy of the original and submit versions of your own.  When submitting to the library, please keep the following in mind:

  • Never hardcode any authentication credentials into any scripts

  • Please provide pseudo-code and be descriptive about your methods

  • Use existing utility libraries whenever possible to maintain consistency and organization (ex., there’s a single python library for API authentication)

  • Use any scripting language you wish or need

Upvote Follow
  • 3 wk agoLast active
  • 561Views
Log In