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 StartedWe 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:
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.
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:
Versioning
The Adility API current version is v0.1. AuthenticationAuthentication 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 FormatsAdility 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 LimitingCurrently all clients are allowed 3 requests per second. Requests are tracked by API key. Rate limit is subject to change.
HTTP & HTTPSThe Adility REST API is served over HTTP and HTTPS. Unencrypted HTTP is not supported in production environment in order to ensure data privacy.SupportThe 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.
|