1 Welcome

The Adility API provides a simple RESTful interface with JSON- and XML-formatted responses to use distribution and submission operations, including offers, advertisers, orders, coupon clips, accounts, and reservations, using authentication to allow both read and write access to the offers database. This document provides information to developers on how to integrate with the Adility API.


Getting Started

We organized this documentation with a goal to help you get started as quick and easy as possible.
We assume you are here because of one of the following use cases:
  • you have an audience and you look for ways to monetize it. Our solution for you is our Distribution API.
  • you have relationships with advertisers/ merchants and you want to help them market. One solution is our Submission API.
  • you have a new idea for a location based service or mobile application and you want to enrich it with a relevant geo content. Distribution API is the tool for you.
  • any other interest in deals, coupons and gift cards from local merchants and brands. Check both our Submission API and Distribution API.
Quickstart. You can get started with the Adility API via our Quickstart guide. You can execute a few simple API calls without signing up for an account.

Submission API. The Submission API enables you to submit deals, coupons or gift cards that you would like to distribute via our publisher and developer network. 

Distribution API. The Distribution API enables you to take deals, coupons or gift cards and present them to your audience. The API helps you to configure queries with a certain set of filters such as postal code, city, state, longitude and latitude, advertiser categories, and offer types. After your customer purchases a deal or a gift card or clips a coupon you receive a unique redemption code through our Distribution API.

Guidelines. After you get familiar with the Submission API and the Distribution API basics, a number of guidelines can provide more complex concepts and workflows of Adility API. This section explains the difference between offer types, who pays who, vouchers and redemption codes, refunds, submission workflow, and other topics. 

API Reference. In this section you will find technical references to the API such as RESTful resources, data types, errors, and helper libraries. You may encounter links to topics in this section across all the documentation. 

FAQ. If you did not find an answer to your question after reading the documentation or for a quick look on frequently asked questions of Adility API just go the FAQ page.

RESTful Concept

We designed the Adility API as close to the RESTful concept as possible. If you are not familiar with the RESTful concept or you need to refresh your knowledge we would recommend to read about it in wikipedia.

Base URL

The Adility API has a Submission API and a Distribution API. Each API has its own base url. Also, there are two environments: sandbox and production. Each environment has its own url as well. Version is a part of urls. Currently, the system is in beta. So we have the following four base urls:

Submission API urls:
  • sandbox: https://testapi.adility.com/submission/beta
  • production: https://api.adility.com/submission/beta
Distribution API urls:
  • sandbox: https://testapi.adility.com/distribution/beta
  • production: https://api.adility.com/distribution/beta
You can sign up for an account at http://www.adility.com and get your sandbox API keys. When your application is ready for production you will have to send us a request to approve your application via email to api@adility.com. Our team will review your application and provide you a production API key after approval of your application.

Versioning

The Adility API current version is v0.1.

Authentication

Authentication is managed using special HTTP header. Every request must include this HTTP header with API key. You can find your API key in your account at Adility.

API key should be passed in request header as shown below
"X-ADILITY-API-KEY: your_api_key"

Example using curl command line tool
curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <your key>" "http://testapi.adility.com/distribution/beta/categories"

Supported Formats

Adility API supports 2 common formats of request and response: XML and JSON.
To specify data format of your request use corresponding Content-Type and Accept request headers:

"Content-Type: application/xml" or "Content-Type: application/json"

Examples using curl command line tool: 
curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <your key>" "http://testapi.adility.com/distribution/beta/accounts" -d '{"account": {"name": "My Account"}}'

curl -k -X GET -H "Content-Type: application/xml" -H "Accept: application/xml" -H "X-ADILITY-API-KEY: <your key>" "http://testapi.adility.com/distribution/beta/accounts" -d '<?xml version="1.0" encoding="UTF-8"><account><name>"My Account"</name></account>' 

To specify format of response add corresponding extension to resource name or use "Accept" header: 
Accept: application/json" or "Accept: application/xml"

Examples using curl command line tool:
curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <your key>" "https://testapi.adility.com/distribution/beta/categories"

curl -k -X GET -H "Content-Type: application/xml" -H "Accept: application/xml" -H "X-ADILITY-API-KEY: <your key>" "https://testapi.adility.com/distribution/beta/categories"

Rate Limiting

Currently all clients are allowed 3 requests per second. Requests are tracked by API key. Rate limit is subject to change.

HTTP & HTTPS

The Adility REST API is served over HTTP and HTTPS. Unencrypted HTTP is not supported in production environment in order to ensure data privacy.

Support

The Adility API may change over time. We'll be continuously improve it to serve you better and better. Also, we plan to share experience of using our API between our clients. You can stay updated if you periodically read our blog and follow us on twitter:
At last, you can request a direct answer from our support team:

Next step: Quickstart.

Comments