Link Search

Overview

Publishers can use the CJ Link Search API to find a variety of links matching a desired criteria across all advertisers using a single API call. Say you wanted to find all of the current promotional links available to you--rather than manually pulling every link every time they update, you can make a single call to the Link Search API to receive all of them at once, and even receive them automatically in the future. Publishers may search for links by any number of criteria including keywords, category, relationship status (with the advertiser) or link type.

The Link Search Service is a REST API that enables publishers to find links based on desired criteria. All parameter names and values are not case sensitive. You must provide at least one of the optional parameters. Submitting an empty request does not return all possible results; an empty request returns zero results.

Limits

Call limit: 25 calls per minute

Call restrictions: Publishers only

Request

GET https<no-link>://link-search.api.cj.com/v2/link-search

Sample Request

curl -s XGET "https://link-search.api.cj.com/v2/link-search?website-id=12345&link-type=banner&advertiser-ids=joined" -H "Authorization: Bearer <your-personal-access-token>"

Request Parameters

Refer to the following table for a list of request parameters. All parameter names and values are case-insensitive.

Parameter Name	Description
website-id	This value is your Website ID / Property ID (also known as your PID), which enables the system to generate the appropriate link code in the response. The PID must match the Website PID which you used to register for the developer key.
advertiser-ids	Limits the results to a set of particular advertisers (CIDs) using one of the following four values. CIDs: You may provide a list of one or more advertiser CIDs, separated by commas, to limit the results to a specific sub-set of merchants. joined: This value restricts the search to advertisers with which you have a relationship. notjoined: This value restricts the search to advertisers with which you do not have a relationship. Empty String: Leaving this field blank returns results for non-joined advertisers only. Using the Empty String value for ‘advertiser-ids’ is currently behaving the same as using the ‘non-joined’ value.
keywords	This value restricts the search results based on keywords found in the link’s advertiser name, link name, description and search keywords tagged by the advertiser for the link.
category	Category is comma separated search for advertiser sub-category. Limits the results to links from advertisers in a specific sub-category. Important: The system does not support searching top-level/parent categories. You must choose a specific sub-category in which to search. For example, if you want links for medical equipment, you must use Equipment (the sub-category) as the value of the 'category' parameter. See the enumerated parameter values that can be used. Tip: Use a combination of sub-category and keyword to obtain more precise search results. For example, to find links for medical equipment, try Equipment (the sub-category) as the value of the 'category' parameter and Medical as the value of the 'keyword' parameter.
link-type	Limits the results to links of a specific link type. See the enumerated parameter values Tip: The Link Search API cannot be used to access product links. If you would like to access product links, utilize the Product Search API.
promotion-type	Limits the results to link of the specified promotion type. You must specify a value for this parameter if you use the start-date or end-date parameters. Acceptable values include the following. coupon sweepstakes product sale/discount free shipping seasonal link site to store
promotion-start-date	Specifies the start date of the associated promotion. You must enter dates in the MM/DD/YYYY format. Leaving this field blank returns promotions with any start date.
promotion-end-date	Specifies the end date of the associated promotion. You must enter dates in the MM/DD/YYYY format or enter the value 'ongoing' to specify a promotion with no end date. Leaving this field blank returns promotions with any end date.
page-number	Specifies the page of the results set that is currently being viewed.
records-per-page	Specifies the number of records to be viewed per page.
language	Specifies the language the link was set at. You must use one of the accepted language codes. See the enumerated parameter values
allow-deep-linking	Limits the results to links where the destination URL can be modified when value is set to true or yes.
event-name	Specifies the event or occurrence(s) to which the link is related. This is helpful for promotions and enables publishers to search for links by holiday. You can search by only one event at a time.
link-Id	It is the AdId or Link ID of an individual link. It allows you to limit the results to a specific Link ID. You can search by only one specific link ID at a time. Please note that the API will only return results on active links. If the link is invalid or deleted/archived in the CJ Account Manager, the API will return 0 results.
last-updated	Limits the results based on the date the link was last updated by the advertiser. When entering a specific date in this field, the results will show links that have been updated since that date, inclusive of the date entered. You must enter dates in the MM/DD/YYYY format.
cross-device-only	Search for links that will support tracking a customer's shopping journey across multiple devices regardless of where the final transaction has happened. The input value can be passed as ‘true’ or ‘false’ based on whether you want to narrow down your search with this parameter.
mobile-app-download	Search for links that the advertiser has indicated will direct the user to an App Store to download the advertiser's mobile app. The input value can be passed as ‘true’ or ‘false’ based on whether you want to narrow down your search with this parameter.
mobile-optimized	Search for links that an advertiser has indicated as mobile-optimized. Learn more in the CJ Support Center article: Mobile Optimized. The input value can be passed as ‘true’ or ‘false’ based on whether you want to narrow down your search with this parameter.
targeted-country	Limit the results to links of the specified target country. You may input only one country at a time, using the two-letter country code (you can find the country code abbreviations here). Please note that this is seen as ‘targeted - countries’ in the response but the search parameter input must be passed as ‘targeted-country’.

Keyword Search Boolean

Query	Results
“kitchen sink”	Any product with the word “kitchen” or “sink”
“+kitchen +sink”	Any product with the words “kitchen” and “sink”
“+kitchen -sink”	Any product with “kitchen” and without “sink”
“kitchen +sink”	All the products with the word “sink”; if they also contain “kitchen”, it increases the product’s relevancy.

Response

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<cj-api>
    <links total-matched="2" records-returned="2" page-number="1">
        <link>
            <link>
                <advertiser-id>15058</advertiser-id>
                <advertiser-name>CJ Affiliate Demo</advertiser-name>
                <category>Home Appliances</category>
                <click-commission>0.0</click-commission>
                <creative-height>0</creative-height>
                <creative-width>0</creative-width>
                <language>English</language>
                <lead-commission>3.00%</lead-commission>
                <link-code-html>
                    <a href="https://www.tkqlhce.com/click-3074780-11470088-1700475083000">best diet supplement</a>
                    <img src="https://www.ftjcfx.com/image-3074780-11470088-1700475083000" width="1" height="1" border="0"/>
                    <img src="//tracker.book-secure.com/hit.php?redir=www.centarahotelsresorts.com&amp;typeredir=AcquisitionCJDisplay&amp;hotelnames=CentaraGroupID&amp;param.cj.aid=11470088&amp;param.cj.pid=3074780"></img>
                </link-code-html>
                <link-code-javascript>
                    <form name="CJ11470088X1" method="POST" style="margin:0px;display:inline" action="https://www.anrdoezrs.net/click"></form>
                    <input type="hidden" name="aid" value="11470088"/>
                    <input type="hidden" name="pid" value="3074780"/>
                    <input type="hidden" name="lastUpdatedDate" value="1700475083000"/>
                    <a href="javascript:CJ11470088X1.submit();">best diet supplement</a>
                </form>
                <img src="https://www.awltovhc.com/image-3074780-11470088-1700475083000" width="1" height="1" border="0"/>
                <img src="//tracker.book-secure.com/hit.php?redir=www.centarahotelsresorts.com&amp;typeredir=AcquisitionCJDisplay&amp;hotelnames=CentaraGroupID&amp;param.cj.aid=11470088&amp;param.cj.pid=3074780"></img>
            </link-code-javascript>
            <destination>http://www.seekinghealth.com/catalogsearch/result/?q=best+diet+supplement</destination>
            <link-id>11470088</link-id>
            <link-name>best diet supplement</link-name>
            <description>best diet supplement</description>
            <link-type>Text Link</link-type>
            <allow-deep-linking>false</allow-deep-linking>
            <performance-incentive>false</performance-incentive>
            <promotion-end-date></promotion-end-date>
            <promotion-start-date></promotion-start-date>
            <promotion-type>N/A</promotion-type>
            <coupon-code></coupon-code>
            <relationship-status>joined</relationship-status>
            <sale-commission></sale-commission>
            <mobile-optimized>false</mobile-optimized>
            <mobile-app-download>false</mobile-app-download>
            <cross-device-only>false</cross-device-only>
            <targeted-countries>null</targeted-countries>
            <event-name>null</event-name>
            <ad-content><link>best diet supplement</link></ad-content>
            <last-updated>Mon Nov 20 02:11:23 PST 2023</last-updated>
            <seven-day-epc>N/A</seven-day-epc>
            <three-month-epc>N/A</three-month-epc>
            <clickUrl>https://www.tkqlhce.com/click-3074780-11470088-1700475083000</clickUrl>
        </link>
    </links>
</cj-api>

Response Elements

The response includes information about the general response, as well as specific information for each record in the response. All parameter names and values are case insensitive.

General

Element Name	Description
links	An array of link records. See the Per Record (Link) table for the fields returned for each link record in the response.
total-matched	The total number of matching results in the index, regardless of the number of results in the actual response (the value of the max-results parameter).
records-returned	The number of records returned in the response, if you don't specify in the request, it will be set to 100 records per page by default
page-number	The page number of the results you requested, if you don't specify in the request it will default to page 1

Per Record (Link)

The response includes the following fields for each record (i.e., link).

Element Name	Description
ad-content	The Ad Copy provided by the advertiser. This is the text that the advertiser has provided for publishers to display on their promotional property. The Ad Copy for text links has a maximum length of 200 characters. For Advanced and Content Link types, advertisers can enter up to 32,000 English-based characters to create interactive functionality.
advertiser-id	The advertiser's CID.
advertiser-name	The advertiser's name.
allow-deep-linking	Whether or not the advertiser allows the destination URL to be modified. This value is "true" if they do, or "false" if they do not support deeplinking for this link.
category	The advertiser's sub/child- category.
click-commission	The commission per click offered by the advertiser.
clickURL	The CJ tracking URL.
coupon-code	Coupon code (if present).
creative-height	The height (in pixels) of the link.
creative-width	The width (in pixels) of the link.
cross-device-only	Indicates if link allows cross-device tracking. Cross-device links will support tracking a customer's shopping journey across multiple devices regardless of where the final transaction has happened. This value is ‘true’ if advertiser has marked the link eligible for Cross-Device or ‘false’ if Advertiser has not marked eligible for Cross-Device.
description	The link's description.
destination	The link's destination URL.
event-name	Event associated with the link.
language	Language of offer.
last-updated	The date when the link was last updated by the advertiser in the format MM/DD/YYYY.
lead-commission	The commission per lead offered by the advertiser.
link-code-html	The link code (in HTML). Note: This field is blank for advertisers with which you do not have a relationship (non-joined).
link-code-javascript	The link code (in JavaScript). Note: This field is blank for advertisers with which you do not have a relationship (non-joined). Note: This field is blank for advanced links.
link-id	The link ID.
link-name	The link name.
link-type	The link type.
mobile-app-download	Indicates links that direct the user to an App Store to download the advertiser's mobile app. This value is ‘true’ if yes and ‘false’ if no.
mobile-optimized	Indicates links that ensure that visitors accessing the website from mobile devices have a user-friendly experience. The value is ‘true’ if yes and ‘false’ if no.
performance-incentive	Indicates whether or not the advertiser offers performance incentives. This value is "true" if they do, or "false" if they do not offer incentives.
promotion-end-date	The associated promotion end date. Shown in UTC timing.
promotion-start-date	The associated promotion start date. Shown in UTC timing.
promotion-type	The associated promotion type.
relationship-status	The advertiser's relationship status with a publisher. This value can be either joined or not- joined.
sale-commission	The commission per sale offered by the advertiser.
seven-day-epc	The link's 7-day EPC.
targeted-countries	Shows the country or countries that the advertiser has indicated the link is targeted for. If the link is targeted for multiple countries, then all the countries will show up here. Please note that this is seen as ‘targeted - countries’ in the response vs ‘targeted-country’ as an input in the search parameter.
three-month-epc	The link's 3-month EPC.

Errors

REST Errors For All APIs

The HTTP Response Code for the following errors is 401.

Message	Description
None	Incorrect resource URL
"You must specify a developer key."	No developer key specified
"Not Authenticated: xxxxxx" (where xxxxxx is the echo of the developer key used).	Invalid developer key specified