getDeals: A Deep Dive
Welcome back to Tech Corner, where we take a deep dive into FMTC’s tools and technology. Today, we will be taking a look at the getDeals API call.
The endpoint getDeals is a core part of our API. Its job is to give you the accurate deals processed by FMTC in a format that’s machine readable. In fact, a call to getDeals can be provided in five machine-readable formats: JSON, XML, CSV, tab separated values, and pipe separated values. These format options can be configured in your dashboard, or provided as the “format” parameter to any request. We recommend JSON or XML formats if you want access to the available data.
A basic getDeals call will look like this:
If you’re familiar with APIs, you will recognize the key parameter. This is a string we provide in your dashboard that authenticates your request. The key is required for any requests to the getDeals endpoint; if it is missing, you will get an error message. For the rest of this post, we will use <YOUR_KEY_HERE> to represent your key.
If needed, a call to getDeals can be filtered using up to seven parameters. Some of these parameters override each other. Here’s a breakdown:
- sincedate: Download deals created or modified since this date. It is in a modified ISO 8601 format, omitting the time zone. For example: https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&sincedate=2021-10-01T05:00:00 will return all deals modified or created after October 1, 2021, at 5:00 AM. Please note, all of our timestamps are in Pacific time.
- network: Give a comma-separated list of networks. Please use the slugs from the getNetworks endpoint. For example: https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&network=sas,cj will return deals for all the merchants you’ve selected from ShareASale and Commission Junction.
- merchantids: Give a comma-separated list of FMTC merchant program IDs for deals. For example: https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&merchantids=12345,9876 will return deals for merchants #12345 and #9876. Merchant IDs can be found on the Manage Merchants page on your dashboard (“FMTC ID” column) or via a getMerchants API Call.
- categoryids: Returns deals for a particular category of categories. Example: apparel-baby, big-tall, intimate-apparel. To call, give a comma-separated list of category IDs. Category IDs can be found via a getCategories API Call.
- dealtype: Return only deals from a particular type. Example: rebates, sale, offer. To call, give a comma-separated list of deal types. The deal types can be retrieved by using a getTypes API Call. For example: https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&dealtype=coupon returns all deals with coupon codes.
- country: Filter the deals by country. The valid values are “US,” “CA,” “UK,” and “AU.” This field accepts a comma separated list. For example: https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&country=us will return all deals for merchants in the United States.
- couponid: Need to just look at a single coupon? Add the couponid parameter, which is a value of a single integer. For example: https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&couponid=12345
In addition, we have incremental calls on our API. In general, FMTC recommends making an incremental call every 30 minutes and a full call every couple of hours. The first time you make an incremental call, you will get all data in the getDeals feed. After that, every call will only give you data that has changed, which makes the calls lightweight and quick.
There are two parameters that help with an incremental call. The first is “incremental”, which requires a value of 1. This tells our system that you want to make an incremental call. The second is “nosave”, which doesn’t change the pointer for an incremental call. This is useful for testing or debugging. An example incremental call is https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&incremental=1 while an example debugging incremental call is https://services.fmtc.co/v2/getDeals?key=<YOUR_KEY_HERE>&incremental=1&nosave=1.
Downloading the getDeals feed will result in the fields listed in our API documentation. We encourage our subscribers to monitor the StartDate and EndDate fields as well as Status to ensure your deals are up to date and working for your users. The deal label is processed by a real person,and is subjected to a full round of testing, verification, and categorization.
There are six types of links provided by getDeals. Depending on your access, you might not see all these links:
- AffiliateURL: This is an affiliate link containing your own affiliate ID that is used to go to the merchant’s landing page and set the appropriate network cookie. In order to generate these links, you need to input your affiliate ID in our dashboard under Relationships > Manage Network IDs.
- DirectURL: This is the direct, unmonetized non-affiliate link that lands on the page associated with the offer. It may be a homepage link or a deep link.
- FMTCURL: This URL goes to FMTC. FMTC will then determine the best link and send the users that direction. FMTC will prioritize the links in the following order depending on your relationship status with the merchant: the AffiliateURL, the SubaffiliateURL, and then the DirectURL.
- FreshreachURL: A link using FMTC’s FreshReach™ sub-affiliate program. It will appear if both the merchant and your account are FreshReach™ enabled.
- SkimlinksURL: This is a link through Skimlinks. It will only appear if your account has Skimlinks enabled.
- SubaffiliateURL: Link that lands on the page associated with the offer and is monetized by a sub-affiliate network.
Need more detailed information about getDeals? Our full API documentation can be found here.
- FMTC Tech Corner: Get Deals and Get Merchants
- FMTC Tech Corner: The Product Feed
- FMTC Tech Corner: FreshReach™
- FMTC Tech Corner: Rakuten API
- How APIs Fuel More Efficient Affiliate Marketing
– Matthew Bowker