Sample Network API Calls

Below are a few sample API calls for commonly used methods that show how to use our API in various ways. Each call requires a valid network ID and network token, as mentioned in our Setting Up API Authentication and Making API Calls articles. You should also be aware of other general HasOffers API topics, including the common field types and how filtering, sorting, and paging works.

Click on the View/Modify This Call buttons for each call to view that method's parameters and to execute or modify that specific call in the API builder.

Caveat: In many cases, you can copy and use these calls right away, provided you use a correct network ID and token. As with any sample code, review the example and make sure you actually want to execute the call before doing so. There is no rollback system, should you make an update you didn't mean to.

Retrieve Aggregated Stats

Say you want to generate a report for your offers' performance—impressions, clicks, conversions, payout, and revenue—over a given month. You want to aggregate the data based on the offer and the calendar date, to see the changes over each day.

Report::getStats is the workhorse of the Report controller, your main way of retrieving network performance stats. This method is very flexible, able to aggregate and return data based on numerous fields (as detailed in the method's documentation).

Composing the Call

Choose the following fields (which networks frequently reference to track performance):

  • calendar date of a given stat (Stat.date)
  • name of an offer (Offer.name)
  • number of impressions for that date and offer (Stat.impressions)
  • number of clicks for that date and offer (Stat.clicks)
  • number of conversions for that date and offer (Stat.conversions)
  • total payout for that date and offer (Stat.payout)
  • CPC for that date and offer (Stat.cpc)
  • total revenue for that date and offer (Stat.revenue)
  • RPC for that date and offer (Stat.rpc)
  • total profit for that date and offer (Stat.profit)

Then set the call to aggregate by calendar date and offer, filtering for all calendar dates between (for example) January 1 2016 and February 1 2016. The time portion of those dates are midnight in the network's time zone.

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Report&Method=getStats&fields[]=Stat.date&fields[]=Offer.name&fields[]=Stat.impressions&fields[]=Stat.clicks&fields[]=Stat.conversions&fields[]=Stat.payout&fields[]=Stat.cpc&fields[]=Stat.revenue&fields[]=Stat.rpc&fields[]=Stat.profit&groups[]=Stat.date&groups[]=Offer.name&filters[Stat.date][conditional]=BETWEEN&filters[Stat.date][values][]=2016-01-01&filters[Stat.date][values][]=2016-02-02

View/Modify This Call in Our API Builder

Note: Make sure to use filters[Stat.date] to filter by date, and not the data_start and data_end parameters in that method. See the method's documentation for further details.

Retrieve Individual Conversion Details

Say you want to generate a report listing every conversion in the past day, with comprehensive details on each one.

Report::getConversions is another powerful tool in the Report controller, used to retrieve conversion reports. Like Report::getStats above, this method is very flexible, able to aggregate and return data based on numerous fields.

Composing the Call

Choose the following fields (which networks frequently reference to track a given conversion):

  • name of the offer for a given conversion record (Offer.name)
  • name of the affiliate recorded for that record (Affiliate.company)
  • date/time of the conversion (Stat.datetime)
  • payout for that conversion (Stat.payout)
  • revenue for that conversion (Stat.revenue)
  • sale amount recorded by advertiser for that conversion (Stat.sale_amount)
  • conversion status (Stat.status)
  • specific status code (Stat.status_code, see reference)
  • if the conversion is an adjustment (Stat.is_adjustment)
  • conversion transaction ID (Stat.ad_id)
  • IP recorded for the conversion (Stat.ip)

Then set the call to filter for conversions that happen between July 15 2016 and July 16 2016, sorted by Stat.datetime descending.The time portion of those dates are midnight in the network's time zone, though by using Stat.datetime instead of Stat.date, you can specify the time portion.

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Report&Method=getConversions&fields[]=Offer.name&fields[]=Affiliate.company&fields[]=Stat.datetime&fields[]=Stat.payout&fields[]=Stat.revenue&fields[]=Stat.sale_amount&fields[]=Stat.status_code&fields[]=Stat.status&fields[]=Stat.is_adjustment&fields[]=Stat.ad_id&fields[]=Stat.ip&filters[Stat.datetime][conditional]=BETWEEN&filters[Stat.datetime][values][]=2016-07-15&filters[Stat.datetime][values][]=2016-07-16&sort[Stat.datetime]=desc&totals=1

View/Modify This Call in Our API Builder

Note: Make sure to use filters[Stat.datetime] to filter by date/time, and not the data_start and data_end parameters in that method. See the method's documentation for further details.

Update Conversion Status

Let's say you have an existing conversion, and you want to reject it. First, you need to know the IDs of the conversion record or the transaction ID of the user's session you want to update. If you don't know it, you can look it up by the conversion's associated affiliate with Conversion::findAll.

Composing the Look-Up Call

Choose the following fields:

  • ID of the conversion record (id)
  • transaction ID for that user session (ad_id)
  • date/time of the conversion (datetime)
  • offer ID linked to that conversion (offer_id)

Then have the call filter for records only associated with affiliate with ID of 1000, sorted by Stat.datetime descending.

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Offer&Method=findAll&fields[]=id&fields[]=name&fields[]=description&fields[]=advertiser_id&fields[]=expiration_date&fields[]=offer_url&fields[]=protocol&fields[]=status&fields[]=currency&fields[]=is_private&sort[id]=desc

View/Modify This Call in Our API Builder

You can just as easily filter by offer_id or a variety of other fields. Filter by datetime if you to reduce the list of results.

With the list of IDs you want to update, use Conversion::update to update those records. The specifics of the call depend on if you're referencing the conversion record ID or the transaction ID. The status field can contain one of three values: "approved", "pending", or "rejected". See the Conversion model for further details.

Composing the Update-by-Record ID Call

To reject the conversion for ID record 114006, run the following Conversion::update call:

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Conversion&Method=update&id=114006&data[status]=rejected&return_object=1

View/Modify This Call in Our API Builder

In this example, we set return_object to "1" so the API call returns the updated conversion record in the call result. You can set that parameter to "0" if you don't want the updated record returned in the result.

Composing the Update-by-Transaction ID Call

To approve (instead of reject, just to show a different example) the conversion associated with transaction ID 1025c8025078077478a99500586d34 (and return the updated object), run the following Conversion::update call:

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Conversion&Method=update&data[status]=approved&return_object=1&transaction_id=1025c8025078077478a99500586d34

View/Modify This Call in Our API Builder

Update Offer Status

Let's say you have an active offer that you want to pause. First, you need to know the IDs of the offers you want to update. If you don't know them, you can look them up by their associated affiliate with Offer::findAll.

Composing the Look-Up Call

Choose the following fields:

  • ID of the offer (id)
  • name of the offer (name)
  • offer's full description (description)
  • ID of related advertiser (advertiser_id)
  • date/time of the conversion (datetime)
  • offer ID linked to that conversion (expiration_date)
  • default offer URL (offer_url)
  • conversion protocol (protocol)
  • offer's status (status)
  • offer's currency (currency)
  • offer's private setting (is_private)

Then have the call sort by id descending.

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Offer&Method=findAll&fields[]=id&fields[]=name&fields[]=description&fields[]=advertiser_id&fields[]=expiration_date&fields[]=offer_url&fields[]=protocol&fields[]=status&fields[]=currency&fields[]=is_private&sort[id]=desc

View/Modify This Call in Our API Builder

Note: You can filter by any Offer model field to narrow your results, such as by offer name or advertiser ID.

Once you know the IDs of the offers you want to update, use Offer::update to update those records. The status field can contain one of five values: "active", "deleted", "paused", "expired", and "pending". See the Offer model for further details.

Composing the Update Call

To set the offer for ID 2004 to paused, run the following Offer::update call:

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Offer&Method=update&id=2004&data[status]=paused&return_object=1

View/Modify This Call in Our API Builder

In this example, we set return_object to "1" so the API call returns the updated offer record in the call result. You can set that parameter to "0" if you don't want the updated record returned in the result.

Set Affiliate Approval for an Offer

Let's say you want to approve a given affiliate for a particular offer. As with other update calls, you'll need to know the IDs of the objects in question: the affiliate and the offer.

You can see the list of affiliates approved for an offer with Offer::getApprovedAffiliateIds. You need to know ID of the offer you want that affiliate approved for. Use Offer::findAll (described above) to find the offer ID, the run this call.

Composing the Approved Affiliate ID Look-Up Call

The following call retrieves a list of affiliate IDs approved for offer ID 2004:

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Offer&Method=getApprovedAffiliateIds&id=2004

View/Modify This Call in Our API Builder

You can also find lists of affiliates that are blocked or unapproved with Offer::getBlockedAffiliateIds and Offer::getUnapprovedAffiliateIds respectively.

To set an affiliate's approval state for an offer, you also need to know the ID of the affiliate you want to approve. If you don't know it, you can look it up with Affiliate::findAll.

Composing the Affiliate ID Look-Up Call

Choose the following fields:

  • ID of the affiliate (id)
  • name of the affiliate (company)

Then have the call filter for affiliate with "Media" in its name and whose status is set to "active". Sorted by the name, ascending.

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Affiliate&Method=findAll&fields[]=company&fields[]=id&filters[status]=active&filters[company][LIKE]=%25Media%25&sort[company]=asc

This example shows how to use the Like search method. "%25" is the URL code for the "%" wildcard character, in this example used on both sides of the filter entry.

View/Modify This Call in Our API Builder

Composing the Approval Modification Call

With the offer ID and affiliate ID known, use Offer::setAffiliateApproval to update that associated approval status. The status field can contain one of three values: "approved", "pending", or "rejected". See the AffiliateOffer model for further details.

To approve affiliate ID 1452 to run offer ID 2004, including a note reading "This is a test API call", run the following call:

https://NETWORKID.api.hasoffers.com/Apiv3/json?NetworkToken=NETWORK_TOKEN&Target=Offer&Method=setAffiliateApproval&id=2004&affiliate_id=1452&status=approved&notes=This+is+a+test+API+call

Adding notes to the approval state switch is optional.

View/Modify This Call in Our API Builder

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