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..
Choose the following fields (which networks frequently reference to track performance):
- The 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 is midnight in the network's time zone.
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.
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)
- The payout for the conversion (Stat.payout)
- Revenue for the conversion (Stat.revenue)
- Sale amount recorded by advertiser for the 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 is midnight in the network's time zone, though by using Stat.datetime instead of Stat.date, you can specify the time portion.
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.
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.
You can just as easily filter by offer_id or a variety of other fields. Filter by DateTime if you wish 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 depending 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.
To reject the conversion for ID record 114006, run the following Conversion::update call:
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.
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:
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.
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.
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.
To set the offer for ID 2004 to paused, run the following Offer::update call:
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 the ID of the offer you want that affiliate approved for. Use Offer::findAll (described above) to find the offer ID, the run this call.
The following call retrieves a list of affiliate IDs approved for offer ID 2004:
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.
Choose the following fields:
- The 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.
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.
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:
Adding notes to the approval state switch is optional.