Making Calls to the Integrator API

Requirements

Prior to making calls to the Integrator API, you need some information from your HasOffers integration manager. The following values are required, and are provided to you during your setup meeting:

  • client_id
  • client_secret
  • audience
  • IntegratorId

Important: Access to the Integrator API is available only to integrators who have worked with an integration manager to determine required scope of API access and rate limits. To contact a HasOffers integration manager, fill out this form. You can find more information in the Setting Up the Integrator API article.

Using the API

Typical usage of the API begins with the authorize endpoint, which generates an access token (JSON web token). Once you have an access token, you can use it to make other calls to the integrator API.

Step 1: Generate an Access Token

The Integrator API uses an OAuth2 two legged non-interactive client flow (more info here). An integrator can access multiple networks with a single access token. There is no need to refresh this token unless it expires.

To generate an access token, make a POST request to "https://integrator-auth.hasoffers.com/authorize" with client_id, client_secret, and audience in the body of the request.

For example:

curl -X POST \
https://integrator-auth.hasoffers.com/authorize \
-d '{
"client_id":"xOdaGe81PaMV3Z83Sk4Qba50tobS5ids",
"client_secret":"You'll need to look me up",
"audience":"BrandAPI"
}

Once your authorize call is validated, the Integrator API responds with your access token as access_token, as well as the number of seconds until the token expires. Here's an example response:

{
    "access_token": "TOKENSTRING",
    "token_type": "Bearer",
    "expires_in": 86400
}

Store and reuse your access token until it expires.

Step 2: Call the API

Make calls to the Integrator API using the same procedure as the Network API, with the following minor changes and requirements to each call:

  • Change the domain to: "integrator-api.hasoffers.com"
  • Calls must include the IntegratorId parameter
  • Calls must be made over HTTPS
  • Calls must include the access token as a Bearer token in the "Authorization" header

To use an API endpoint, make a GET request with the access token attached in the "Authorization" header, along with the appropriate IntegratorId value.

For example, a call in Python to Conversion::findAll via the Integrator API could look like this:

url = "https://integrator-api.hasoffers.com/Apiv3/json?Format=json&NetworkId={}&Target=Conversion&Method=findAll&IntegratorId={}".format(network_id, integrator_id)

headers = {}
headers['Authorization'] = "Bearer TOKENSTRING"

req = urllib.request.Request(url, headers = headers)
resp = urllib.request.urlopen(req)
respData = resp.read()

Once the Integrator API checks the access token for authorization to make the call, it returns the requested data with status code 200 on success. Response data format is the same as if the call was made using the Network API, with some information from the request object redacted for network privacy purposes.

Errors

403: JWT is missing/expired/unauthorized

429: Rate limit exceeded

502: Internal Server Error

Have a Question? Please contact support@tune.com for technical support.