Overview

The Advertiser Lookup API is a REST API that allows publishers to find advertisers based on CID, program name, or program URL. Publishers can use the Advertiser Lookup API to automatically look up advertisers and details about their programs in the CJ network. This API displays advertiser account status so publishers can determine whether their joined advertisers’ programs are in good standing with CJ (active), or temporarily deactivated. Publishers can use the Advertiser Lookup API to identify non-joined advertisers with whom they would like to establish a relationship, or to look at advertisers with whom they have an active relationship.

The Advertiser Lookup API does contain some commission rate information for each advertiser's default Program Term (for a non-joined advertiser) or the Program Term that is currently active between the publisher and advertiser. However, this API will not contain any commission rates for Situations or Promotional Properties. To pull accurate commission rates through an API, we recommend using the Program Terms API, which is detailed in the GraphQL API section of this developer portal.

Limits

Call limit: 25 calls per minute
Call restrictions: Publishers only

Request

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

Sample Request

This sample request would be used to generate a list of all of your joined advertisers. Use the parameters below to customize a request for your needs.

curl -s -XGET "https://advertiser-lookup.api.cj.com/v2/advertiser-lookup?requestor-cid=4567&advertiser-ids=joined" -H "Authorization: Bearer <your-personal-access-token>"

Request Query Parameters

Refer to the following table for a list of request query parameters. All parameter names and values are case-insensitive. Submitting an empty request does not return all possible results; an empty request returns zero results.

Parameter Name	Description
requestor-cid	Specify the CID of company for which you would like to make this request. You must be a member of the specified company. If you are a member of the specified company, you will be authorized to view data that that company is allowed to access. THIS PARAMETER IS REQUIRED
advertiser-ids	Limits the results to a set of particular advertisers (CIDs) using one of the following four values. CIDs: You may provide 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.
advertiser-name	Limits the results to a set of particular advertisers (CIDs) using one of the following values. Advertiser name: Limits results to advertisers matching specified program name. Program URL: Limits results to advertisers matching specified program URL.
keywords	This value restricts the search results based on keywords found in the advertiser’s name, the product name or the product description. This parameter may be left blank. You may use simple Boolean logic operators (’+’, ’-’) to obtain more relevant search results. By default, the system assumes basic OR logic. The examples below illustrate how these operators affect search results.
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. If this parameter is not given, the response will return 25 records per page. The maximum value for this parameter is 100.
mobile-tracking-certified	Limits the results to a set of particular advertisers (CIDs) using one of the following two values: True: This special value restricts the search to advertisers that have been certified for mobile tracking. False: This special value restricts the search to advertisers that have not been certified for mobile tracking

Keyword Search Format

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

The response includes information about the general response, as well as specific information for each record in the response.

Sample Response

Refer to the following sample XML response.

<?xml version="1.0" encoding="UTF-8"?>
<cj-api>
  <advertisers total-matched="1" records-returned="1" page-number="1">
    <advertiser>
      <advertiser-id>1234567</advertiser-id>
      <account-status>Active</account-status>
      <seven-day-epc>20.00</seven-day-epc>
      <three-month-epc>25.00</three-month-epc>
      <language>en</language>
      <advertiser-name>Sample Advertiser</advertiser-name>
      <program-url>http://www.Advertiser.com</program-url>
      <relationship-status>joined</relationship-status>
      <mobile-supported>true</mobile-supported>
      <mobile-tracking-certified>true</mobile-tracking-certified>
      <cookieless-tracking-enabled>false</cookieless-tracking-enabled>
      <network-rank>5</network-rank>
      <primary-category>
        <parent>Home & Garden</parent>
        <child>Utilities</child>
      </primary-category>
      <performance-incentives>false</performance-incentives>
      <actions>
        <action>
          <name>Online Sale</name>
          <type>advanced sale</type>
          <id>1234</id>
          <commission>
            <itemlist name="Item List 1" id="2179">USD 1.00</itemlist>
            <itemlist name="Item List 2" id="2180">USD 2.00</itemlist>
            <itemlist name="Item List 3" id="2181">USD 3.00</itemlist>
            <default>USD 0.50</default>
          </commission>
        </action>
      </actions>
      <link-types>
        <link-type>Content Link</link-type>
        <link-type>Banner</link-type>
        <link-type>Text Link</link-type>
        <link-type>Advanced Link</link-type>
      </link-types>
    </advertiser>
  </advertisers>
</cj-api>

Response Elements

General

The following response fields get returned in XML for joined publishers that meet the request parameters.

Element Name	Description
advertisers	An array of advertiser records. See the Per Record (Advertiser) table for the fields returned for each advertiser record in the response.
total-matched	The total number of matching results in the index.
records-returned	The total number of records returned for the current page.

Per Record (Advertiser)

Element Name	Description
advertiser-id	The advertiser's CID.
account-status	Represents the advertiser’s current standing with CJ. `Active` signifies the advertiser is in good standing and live within the CJ network. `Deactive` signifies an advertiser that has been temporarily deactivated. Note: This response field is only shown for your joined Advertisers.
seven-day-epc	The advertiser’s 7-day EPC. Currently defaults to USD.
three-month-epc	The advertiser’s 3-month EPC. Currently defaults to USD.
language	The advertiser’s primary website language.
advertiser-name	The advertiser program name.
program-url	The advertiser program’s website URL.
relationship-status	The advertiser’s relationship status with a publisher. This value can be either `joined` or `notjoined`.
mobile-supported	Returns a value of `True` if the advertiser has a mobile-supported website or app else returns `False`
mobile-tracking-certified	Returns a value of True if the advertiser has been mobile tracking certified or else returns false
cookieless-tracking-enabled	Indicates whether the advertiser’s CJ transactions are leveraging cookieless tracking appropriately for the previous three days. This value is true or false.
network-rank	The advertiser’s network ranking.
primary-category	An array of strings that contains the advertiser’s primary parent and child category names.
performance-incentives	Whether or not the advertiser offers performance incentives. This value is `True` if they do, or `False` if they do not offer incentives.
actions	An array of advertiser actions and associated commission. See the Per Record (Action) table for the fields returned for each advertiser record in the response. Note: Commissions shown are tied to the current Program Term in place for ‘joined’ relationships, but will otherwise display the advertiser’s default Program Term.
link-types	An array of strings containing the link types offered by the advertiser.

Per Record (Action)

Element Name	Description
name	The action name.
type	The action’s integration type.
commission	Shows the advertiser’s default commission associated to the specified action. If an action includes Item Lists, the name and ID are shown along with the associated commission to each list. This commission will not include Situations or Promotional Properties rates even if they exist in the Program Term. To see all applicable commission rates for a Program Term, use the Program Terms API.

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