api_token

APIKEY

API key for authentication, available on the API Keys & Calls page.(https://account.fmtc.co/cp/api_keys)

Yes

N/A, must always be provided

format

String

XML, JSON, CSV, TAB, or PIPE

Choose the feed format you would like returned.

No

JSON

codesonly

0, 1

Limit to only deals with coupon codes

No

0

merchantids

Number(s)

Return only deals from a particular merchant. If you do not specify a merchantids value deals will be returned from all of your selected merchants.

No

null

categoryids

Number(s)

Return only deals from a particular category or categories. Use the Categories - 3.0.0 endpoint for available categories.

No

null

dealtypeids

Number

Return only deals from of a particular type. Use Types - 3.0.0 endpoint for available types.

No

null

country

String

Return only deals from merchants with a particular Primary Country. Value Format: A two-letter Country Code, or multiple Country Codes separated by commas.

No

null

networkid

Number

Return only deals from a particular network. Use Networks - 3.0.0 endpoint for available networks.

No

null

local

0, 1

This option will return only local deals from your selected merchants. Account level restrictions apply.

No

0

zipcode

US Zip Code (#####)

Display only local deals in this zip code. Requires local deals to be enabled on the account

No

null

active

0,1

Display only active deals.

0 - will show both the expired and currently active deals. This will not show deleted deals.

1 - will only show deals that are currently active.

No

1

activetoday

0,1

Retrieve deals that are active today (AKA they expire after today and begin before today)

No

0

sincedate

Date (YYYY-MM-DD)

The date from which data will be retrieved. The data returned will include all new data, modified data, deleted data, and expired data since the provided date.

NOTE: This will search for any deals that existed in the API before the date and it will return those deals. The deals will be marked as deleted to indicate that the deals are not a part of the current active deal feed.

No

null

incremental

Number

The amount of time from the previous call and to include only items that have changed since this time.

For Example, setting this value to 60 will send back all changes in the past 60 minutes from the time of this call.

No

0

activedatestart

Date (YYYY-MM-DD)

Display deals after this start after this date

No

null

activedateend

Date (YYYY-MM-DD)

Display deals that start before this date

No

null

expiredatestart

Date (YYYY-MM-DD)

Display deals that end after this date

No

null

expiredateend

Date (YYYY-MM-DD)

Display deals that end before this date

No

null

historical

0, 1

This option will return active, expired and deleted coupons and deals. This will grab from when your subscription began or up to two years worth of data. You must specify at least one merchantid with the historical parameter.

No

0

couponid

Number

Return only a single couponID.

No

null

sortby

String

“merchant,” “added,” and “update”

Field to order the results by.

No

merchant

public_only

0, 1

This option will return only publically available deals.

No

0

exclusive_only

0, 1

This option will return only exclusive deals available to the subscriber.

No

0

page_size

Number

1 - 150,000

Size of each page for the results of this call.

No

100

id

Our proprietary coupon ID - especially useful in identifying deals that are delivered more than once because they have changed.

merchant_name

Name of the merchant in the FMTC database.

merchant_id

The ID assigned to the merchant by FMTC.

master_merchant_id

Each unique merchant has an ID that is shared across all the networks a merchant is active on.

network_id

An FMTC assigned ID for the affiliate network associated with this merchant. Use Networks - 3.0.0 endpoint for available networks.

program_id

A Network assigned ID for the merchant that their program is on.

label

Describes the coupon value or description of the deal.

code

If the offer requires the user to enter a code, it is in this field. Any deal with a code will also contain the Deal Type ID (Types - 3.0.0) for “coupon” in the types field.

coupon_code_on_page

Automated FMTC has found the coupon code on the deal’s landing page. NOTE: This has the potential to provide false positives if the code is a generic term that is possibly used in multiple places on the page.

code_verified_at

The date that the code was verified by FMTC. This will be updated each time the code has been verified. (example: 2014-07-17T00:01:00-07:00).

image

Images are included when possible and are typically delivered with product offers and grocery coupons.

state_date

Date the offer begins with start time (example: 2013-07-17T00:01:00-07:00).

end_date

Date the offer ends with end time (example: 2014-07-17T00:01:00-07:00).

affiliate_url

The affiliate link containing your own affiliate ID that is used to go to the merchant's landing page and set the appropriate network cookie. It requires that you have inserted your affiliate IDs on the Manage Affiliate IDs page.

NOTE: Any deal with a code will also contain the Deal Type ID (Types - 3.0.0) for “coupon” in the types field.

skimlinks_url

Link that lands on the page associated with the offer and is monetized by Skimlinks. You must have a Skimlinks account and provide us with your Skimlinks publisher ID to activate this field.

freshreach_url

Link that lands on the page associated with the offer and is monetized by FreshReach®. You must have a FreshReach® account to activate this field.

direct_link

Unmonetized non-affiliate link that lands on the page associated with the offer. May be a homepage link or a deep link.

fmtc_url

FMTC tracking URL. FMTC will determine if you should use the NetworkAffiliate URL or the Sub-Affiliate (FreshReach®/Skimlinks) URL depending on your relationship status with the merchant. This will be a shortened URL.

cascading_full_url

This will direct to the same location as the FMTC URL. The difference is that this URL is not shortened.

subaffiliate_url

Link that lands on the page associated with the offer and is monetized by a subaffiliate network. You must have an applicable account with one of the participating subaffiliate networks to activate this field.

link_verified_at

The date that the link was verified by FMTC. This will be updated each time the link has been verified. (example: 2014-07-17T00:01:00-07:00).

pixel_html

Tracking pixel provided by the associated affiliate network when available.

restrictions

Any information the merchant provides regarding restrictions relating to how the coupon can or cannot be used.

categories

Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc.

types

Used to signify a offer's type, i.e. $ off, % off, category coupon, product coupon, free shipping, sale, category sale, product sale, rebate, etc. This is an array of ID’s that can be looked up via the Types - 3.0.0 endpoint.

status

The status should always be checked, and only "active" deals should be displayed (regardless of expiration date). The status is critical to tell if the deal is currently valid. Values may be: active - Deal is active, valid, and may be displayed; deleted - Deal was deleted - ignore other values and remove deal; suspended - The merchant was deactivated by FMTC, check your affiliation status; or expired - The deal expired normally.

created

The date the offer was added to FMTC's database.

last_update

When this deal was last modified by FMTC.

sale_price

Discounted price of a product. Not included on all product deals.

was_price

Original price of a product. Not included on all product deals.

discount

The system calculated dollar off savings when a sale product has "was" and "now" pricing.

percent

The system calculated percent off savings when a sale product has "was" and "now" pricing.

threshold

The minimum amount a shopper must spend in order to qualify for an offer.

rating

Deal Rankings are assigned to every offer. They can be used to aid in the placement of coupons and deals on your merchant pages based on offer value and potential of customer appeal. Rankings start at 1 (lowest value) and higher is better.

brands

List of brands related to this deal. Note: currently this field is only populated for grocery deals.

local

This will determine if the deal is a local deal, and will be a 0 or 1.

tiered_deal

This offer was flagged by an FMTC Data Processor as being a tiered deal.

link_id

This is the Network LinkID associated with this deal.

locations

This is an array of local deal information if the deal is a local deal. The following information is provided:

name: Name of the business.

street_address: Address of the business offering the deal.

extended_address: Address of the business offering the deal.

locality: The area in which the deal is being offered.

region: The region in which the deal is being offered.

postal_code: The Postal code of the deal being offered.

country: The country the deal is located in.

latitude: Geographical north-south location of the business offering the deal.

longitude: Geographical east-west location of the business offering the deal.

link: Website of the business offering the deal.

metadata

This is an object that contains AI information pulled from the label field.

currency - Currency value within the label.

value - Discount value within the label.

max_value - Maximum Discount value if a range has been provided.

is_precent - Whether the value and max_value values are percentages or fixed amounts.

old_price - Previous Price of the deal.

new_price - Discounted Price of the deal.

price_trigger - Requirement to use the deal.

coupon_code - Code needed for the deal.

deal_types

This is an object that will contain the deal type information. See Deal Types List Mapping for more information.

exclusive

This determines if the deal is public or exclusive, and what kind of exclusive deal.

0 - publically available deal

1 - exclusive automated (pulled through API calls)

2 - exclusive manual (added manually by a user)

links - JSON and XML

link - CSV, Tab, Pipe - will be located in the HTML link header.

All the different links that are for going through the pagination.

first - The first page of the endpoint call.

last - The last page of the endpoint call.

prev - The previous page of the endpoint call.

next - The next page of the endpoint call.

meta

The information about the current endpoint call.