Link Search Service

The Link Search Service is a SOAP API  that enables developers to find links in the Commission Junction network based on desired criteria. Developers may search for links by any number of criteria including keywords, country, category, targeted area, relationship status (with the advertiser), link size or link type.

To access the Link Search Service in REST instead of SOAP, click here.

Click the following links to display more specific information..

• Request Parameters

  Request Parameters

  Refer to the following table for a list of the required and optional request parameters. All parameter names and values are case sensitive.

  Important: You must provide all required parameters and at least one of the optional parameters. Submitting an empty request does not return all possible results; an empty request returns zero results.

  Parameter Name	Value	Req?	Description
  developerKey	String	Required	Your developer key obtained from the Web Services Developer Site.
  token	String	Optional	Not currently used.
  websiteId	String	Required	This value is your Web site ID (PID), which enables the system to generate the appropriate link code in the response. The PID must match the Web site PID which you used to register for the developer key (passed in the developerKey parameter).
  advertiserIds	String	Optional	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. Empty String: Leaving this field blank returns results for nonjoined advertisers only. We recommend that you complete this field blank. Note: Empty String for advertiserIds is currently  behaving the same as using  the nonjoined value. We will correct this in a future release. joined: This special value (joined) restricts the search to advertisers with which you have a relationship. notjoined: This special value (notjoined) restricts the search to advertisers with which you do not have a relationship.
  keywords	String	Optional	This value restricts the search results based on keywords found in the link's name or description. You may use simple Boolean logic operators (+, -) to obtain more relevant search results. By default, the system assumes basic OR logic. Tip: Values entered in this field search against advertiser names, link descriptions, link names and keywords. The examples below illustrate how the boolean operators affect search results. Query Results "kitchen sink" Any link with the word "kitchen" or "sink" "+kitchen +sink" Any link with the words "kitchen" and "sink" "+kitchen -sink" Any link with "kitchen" and without "sink" "kitchen +sink" All the links with the word "sink"; if they also contain "kitchen", it increases the link's relevancy.
  category	String	Optional	Limits the results to links in a specific sub-category. You may obtain a list of available categories using the Support Services. Important: The system does not support searching top-level 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. 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.
  linkType	String	Optional	Limits the results to links of a specific link type. You may obtain a list of available link types using the Support Services.
  linkSize	String	Optional	Limits the results to links with a specific link size. You may obtain a list of available link sizes using the Support Services.
  language	String	Optional	Limits the results to links offered in a specific language. You may obtain a list of available languages using the Support Services. If you do not provide a value for this parameter, the system assumes the English language ('en').
  serviceableArea	String	Optional	Limits the results to links offered by advertisers with a specific targeted area or targeted areas. Separate multiple values with a comma. You may obtain a list of available countries using the Support Services.
  promotionType	String	Required if using startDate or endDate	Limits the results to link of the specified promotion type.  You must specify a value for this parameter is you use the startDate or endDate parameters. Acceptable values include the following.  coupon  sweepstakes  product  sale/discount  free shipping  seasonal link
  startDate	Date	Optional	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.
  endDate	Date	Optional	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.
  sortBy	String	Optional	Sort the results by any of the following response fields. linkId advertiserName linkDestination linkType creativeWidth creativeHeight advertiserId promotionStartDate promotionEndDate category If you do not provide a value for this parameter, the default sort is by relevance.
  sortOrder	String	Optional	Specifies the order in which the results are sorted; the following  values are acceptable. asc: ascending dec: descending (default value)
  startAt	String	Optional	Specifies the first record to return in the request. The first record is 0. Leaving this parameter blank assigns a default value of 0.
  maxResults	String	Optional	Specifies the number of records to return in the request. Leaving this parameter blank assigns a default value of 10. Note: 100 results is the system limit for results per request. If you request a value greater than 100, the system only returns 100.

  The following table provides an example of how to use startAt and maxResults values to obtain a total of 100 results, with 25 results at a time.

  Request number	startAt value	maxResults value
  Request 1	0	25
  Request 2	25	25
  Request 3	50	25
  Request 4	75	25

  For more information refer to the forums at the Web Services Developer Site (http://webservices.cj.com).

• Response Fields

  Response Fields

  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 sensitive.

  General

  The response includes the following information about the overall set of results in the response.

  Field Name	Value	Description
  links	Array	An array of link records. See the Per Record (Link) table for the fields returned for each link record in the response.
  totalResults	Integer	The total number of matching results in the index, regardless of the number of results in the actual response (the value of the maxResults parameter).

  Per Record (Link)

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

  Field Name	Value	Description
  advertiserId	String	The advertiser's CID.
  clickCommission	String	The commission per click offered by the advertiser.
  creativeHeight	String	The height (in pixels) of the link.
  creativeWidth	String	The width (in pixels) of the link.
  leadCommission	String	The commission per lead offered by the advertiser.
  linkCodeHtml	String	The link code (in HTML). Note: This field is blank for advertisers with which you do not have a relationship (nonjoined).
  linkCodeJavascript	String	The link code (in JavaScript). Note: This field is blank for advertisers with which you do not have a relationship (nonjoined). Note: This field is blank for advanced links.
  linkDestination	String	The link's destination URL.
  linkDescription	String	The link's description.
  linkId	String	The link ID.
  linkName	String	The link name.
  linkType	String	The link type.
  advertiserName	String	The advertisers name.
  performanceIncentives	String	Whether or not the advertiser offers performance incentives. This value is Yes if they do, or No if they do not offer incentives.
  promotionType	String	The associated promotion type.
  promotionStartDate	TimeStamp	The associated promotion start date.
  promotionEndDate	TimeStamp	The associated promotion end date.
  relationshipStatus	String	The advertisers relationship status with a publisher. This value can be either joined or notjoined.
  saleCommission	String	The commission per sale offered by the advertiser.
  sevenDayEPC	String	The link's 7-day EPC.
  threeMonthEPC	String	The link's 3-month EPC.

• Errors

  Errors

  Error	Description
  Not Authenticated	The system could not authenticate your developer key.