Admin Services API
OVERVIEW
Lotame's Spherical 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 Sphreical into another application. Find the details on the API in this article.
Functionality
- 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:
- Login to the Spherical platform with your credentials
- 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
- Select “Create Token Pair”
- Provide a description for your Token
- Immediately store your Access Key and Token somewhere local that can be accessed later as needed
- 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/activeUserJava
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!
Note: Please be mindful that the data you see and manipulate in the API Explorer is your Spherical 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
Lotame's Spherical 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.
Spherical 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.
Expiration Time Out for User API keys:
The expiration time-out for the User API keys is 7 days by default. Upon request, it can be increased to 31 days for your account.
NOTE: We would request you to work with your Lotame representative to ensure all network accounts and all child accounts are configured with the same expiration time-out.
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
[New] Client API Tokens
We have now introduced a new feature called Client API tokens. Clients will now be able to create these Client API tokens to access Lotame’s APIs in their automated processes through a new page in the UI under Manage Settings → Tokens
More importantly, these client tokens will NOT be automatically logged out due to inactivity as their tokens are valid for a year.
From a client perspective, there are:
Human users,
Human user API keys
[NEW] Client API tokens
Important notes:
This can only be accessed by the Client Admin from your side.
The Client API tokens do not belong to a user, they belong to a client as a whole. They are meant specifically for long term automated, programmatic use cases.
A Client API token can NOT log in via the platform UI (only via APIs)
Any given user can generate a human user API key and use it to access our API. A regular user has to log in to the actual platform each week or their API key will get locked down for security reasons
Client API tokens are special in that they cannot log in to the platform, and their tokens do not expire if they don't log in to the platform.
We are excluding these new Client API tokens from being counted as ‘users’ in the client’s user count
This feature is behind a feature flag in the client admin
A notification will be sent out to users if the Client API token is over a year old