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

Once you've been successfully authenticated, calls you make against the Integrator API return data in the same format as if you called the Network API. For situations where your call is formatted incorrectly or the Integrator API is experiencing intermittent issues, you may encounter error codes from the following list:

Error Code Message Meaning
400 "missing integratorId parameter" Your request doesn't contain the required IntegratorId query string parameter.
401 "JWT is not valid or missing"

"Insufficient permissions for this request. Please verify your JWT and try again later"

There's an issue with your access token. It could be expired, missing, or indicative of insufficient permissions.
403 "Invalid origin: <cross-origin resource domain>" Cross-origin resource sharing (CORS) is only available for certain origins. Contact an integration manager to discuss this feature if it's needed for your integration.
404 "<IntegratorId> does not exist within our system. Please contact an administrator" Your IntegratorId was entered incorrectly or hasn't been set up as an integration. Contact an integration manager if the problem persists.
405 "Invalid HTTP Method: <HTTP method>" The HTTP method used isn't supported for the requested endpoint. For example, using HTTP TRACE on an endpoint that only accepts GET requests.
414 "URL exceeds allowed length. Please shorten query and try again." Your request URL is too long to process. Consider splitting complex queries into multiple shorter ones.
429 "Exceeded concurrent rate limit: <current rate / rate limit>"

"Exceeded flat rate limit: <current rate / rate limit> in <rate limit window> second window."

You've made too many API calls simultaneously or in a period of time. Reduce the frequency or concurrency of your calls.
500 "Error encountered while validating origin" Cross-origin resource sharing (CORS) is only available for certain origins. Contact an integration manager to discuss this feature if the problem persists.
502 "Internal Server Error" This is usually a temporary error, where the server or an individual endpoint is having issues. Try again later, or contact your integration manager if the problem persists.
Have a Question? Please contact support@tune.com for technical support.