Skip to main content

Publisher API Reference

Michael Cheng
  • Updated

This guide is a detailed resource for publishers on each of Connexity's most frequently used API calls. It outlines the purpose and functionality of each call, including use case examples. Leverage this to effectively utilize Connexity's tools to their full potential.

Table of Contents

Deep Link API

The Deep Link API allows publishers to convert merchant landing page URLs into monetized links. These links incorporate tracking and revenue-generating parameters for Connexity's CPC relationships with merchants.

Common Use Cases

  • Generate monetized deep links for merchant pages
  • Track clicks and performance by campaigns, placements, or individual sessions
  • Retrieve ECPC (Estimated Cost Per Click) values for merchant URLs

Endpoint: Generate Link

URL: /api/link/generate

METHOD: GET

 

Request Parameters

Parameter Type Required Description
url string yes The merchant’s landing page URL (url-encoded)
publisherId integer yes The publisher’s unique Connexity identifier
apiKey string yes The publisher’s API key for authentication
af_campaign_id string no A custom campaign identifier for grouping or tracking clicks
af_placement_id string no A custom placement identifier for tracking ad unit performance (max 50 alphanumeric characters, including dash (-), period (.) or underscore (_)
af_rid string no A custom session or click-level identifier (max 1020 alphanumeric characters)


Example Request

curl -X GET "https://api.cnnx.link/api/link/generate?url=http%3A%2F%2Fwww.connexity.com
&publisherId=12345&apiKey=YOUR_API_KEY&af_campaign_id=campaign1&af_placement_id=
placementA&af_rid=session123"


Response Attributes

Attribute Type Description
deepLinkUrl string The generated, monetizing link for the merchant
 

Example Response (JSON)

{
  "deeplinkUrl": "https://link.sylikes.com/?publisherId=12345&url=http%3A%2F%2Fwww.connexity.com"
}

 

Endpoint: Calculate ECPC

URL: /api/link/ecpc

METHOD: GET

 

Request Parameters

Parameter Type Required Description
url string yes The merchant’s landing page URL (url-encoded)
publisherId integer yes The publisher’s unique Connexity identifier
apiKey string yes The publisher’s API key for authentication
af_placement_id string no A custom placement identifier for tracking ad unit performance (max 50 alphanumeric characters, including dash (-), period (.) or underscore (_)


Example Request

curl -X GET 
"https://api.cnnx.link/api/link/ecpc?url=http%3A%2F%2Fwww.connexity.com&publisherId=12345
&apiKey=YOUR_API_KEY&af_placement_id=placementA"
 

Response Attributes

Attribute Type Description
originalUrl string The original merchant URL
ecpc  integer The estimated cost per click value for the merchant landing page


Example Response (JSON)

{
  "ecpcList": [
    {
      "originalUrl": "http://www.connexity.com",
      "ecpc": 20
    },
    {
      "originalUrl": "http://www.bizrate.com",
      "ecpc": 25
    }
  ]
}


Endpoint: Retrieve Active Merchants

URL: /api/activeMerchants

METHOD: GET


Request Parameters

Parameter Type Required Description
publisherId integer yes The publisher’s unique Connexity identifier
apiKey string yes The publisher’s API key for authentication


Example Request

curl -X GET 
"https://api.cnnx.link/api/activeMerchants?publisherId=12345&apiKey=YOUR_API_KEY"


Response Attributes

Attribute Type Description
merchantId integer The unique identifier of the merchant
merchantName  string The name of the merchant
 

Example Response (JSON)

{
  "merchants": [
    {
      "merchantId": 401,
      "merchantName": "Walmart"
    },
    {
      "merchantId": 417,
      "merchantName": "Macy's"
    }
  ]
}

 

 

Merchant Match API

The Merchant Match API enables publishers to use keywords submitted by shoppers to find Connexity merchants matching the search criteria. Results include merchant details and related product offers.

Common Use Cases

  • Search for merchants by user-provided keywords
  • Display a list of merchants offering products relevant to the keyword
  • Generate deep links for monetizing merchant pages

Endpoint: Merchant Match

URL: /api/keyword/merchantMatch 

METHOD: GET


Request Parameters

Parameter Type Required Description
publisherId integer yes The publisher’s unique Connexity identifier
apiKey string yes The publisher’s API key for authentication
keyword string yes The keyword for searching related merchants (url-encoded)
 

Example Request

curl -X GET 
"https://api.cnnx.link/api/keyword/merchantMatch?publisherId=12345&
apiKey=YOUR_API_KEY&keyword=Bedding"
}


Response Attributes

Attribute Type Description
merchantId integer The unique identifier of the merchant
merchantName string The name of the merchant
merchantUrl string The homepage URL of the merchant
deeplinkEcpc integer Estimated CPC value for a valid merchant deep link click
deeplinkUrl string Monetized link for the merchant’s homepage
searchCategoryId integer The ID of the Connexity category related to the search
productSearchUrl string The Catalog API URL for product offers from the matched merchant


Example Responses (JSON)

Single Merchant Match

{
  "merchantMatches": [
    {
      "merchantId": 417,
      "merchantName": "Macy's",
      "merchantUrl": "http://www.macys.com",
      "deeplinkEcpc": 48,
      "deeplinkUrl": "https://link.sylikes.com/?publisherId=12345&url=http%3A%2F%2Fwww.macys.com",
      "searchCategoryId": 13030200,
      "productSearchUrl": "https://catalog.bizrate.com/services/catalog/v1/api/product/1?publisherId=12345&apiKey=YOUR_API_KEY&categoryId=13030200&keyword=&offersOnly=true&merchantId=417"
    }
  ]
}

 
Multiple Merchant Matches 

{
  "merchantMatches": [
    {
      "merchantId": 326058,
      "merchantName": "Wayfair",
      "merchantUrl": "http://www.wayfair.com",
      "deeplinkEcpc": 87,
      "deeplinkUrl": "https://link.sylikes.com/?publisherId=12345&url=http%3A%2F%2Fwww.wayfair.com",
      "searchCategoryId": 13170100,
      "productSearchUrl": "https://catalog.bizrate.com/services/catalog/v1/api/product/1?publisherId=12345&apiKey=YOUR_API_KEY&categoryId=13170100&keyword=&offersOnly=true&merchantId=326058"
    },
    {
      "merchantId": 401,
      "merchantName": "Walmart",
      "merchantUrl": "http://www.walmart.com",
      "deeplinkEcpc": 9,
      "deeplinkUrl": "https://link.sylikes.com/?publisherId=12345&url=http%3A%2F%2Fwww.walmart.com",
      "searchCategoryId": 13010500,
      "productSearchUrl": "https://catalog.bizrate.com/services/catalog/v1/api/product/1?publisherId=12345&apiKey=YOUR_API_KEY&categoryId=13010500&keyword=&offersOnly=true&merchantId=401"
    }
  ]
}

 

Publisher Reporting APIs

Publishers can effortlessly access key reports for adjustments, earnings, and performance, with a simple API call.

  • Get Adjustments Report - Summary of all adjustments made to a publisher's account during a specified date range. Adjustments include changes made to earnings or other account balances.
  • Get Earnings Report - Summary of earnings during a specified date range, including breakdowns by redirects, CPC, and other metrics.
  • Get Performance Report - Performance metrics from a saved report identified by a report ID.

Common Use Cases

  • Retrieve financial adjustments for reconciliation
  • Analyze adjustments over a specific period
  • Analyze earnings and performance over a specific period
  • Break down earnings by day, week or month
  • Retrieve custom performance metrics generated in the Connexity dashboard


Endpoint: Get Adjustments

URL: /api/reporting/adjustments

METHOD: GET


Request Parameters

Parameter Type Required Description
apiKey string yes The publisher’s API key for authentication
publisherId integer yes The publisher’s unique Connexity identifier
startDate string yes The start date for the report in yyyy-mm-dd format
endDate string yes The end date for the report in yyyy-mm-dd format (inclusive)
firstResult integer no The index of the first result (default: 0)
maxResults integer no The maximum number of results to return (default: 100; max: 500)
 

Example Request

curl -X GET 
"https://publisher-api.connexity.com/api/reporting/adjustments?apiKey=YOUR_API_KEY&
publisherId=12345&startDate=2024-11-01&endDate=2024-11-30"

Response Attributes

Attribute Type Description
publisherId integer The publisher’s unique Connexity identifier
entriesCount integer The number of adjustment entries returned
adjustments array A nested list of adjustments, including amount and adjustmentDate
amount decimal The amount of a given adjustment
adjustmentDate string The date of a given adjustment in yyyy-mm-dd format


Example Response (JSON)

{
  "publisherId": 12345,
  "entriesCount": 2,
  "adjustments": [
    {
      "amount": 25.50,
      "adjustmentDate": "2024-11-10"
    },
    {
      "amount": -15.00,
      "adjustmentDate": "2024-11-15"
    }
  ]
}


Endpoint: Get Earnings

URL: /api/reporting/earnings

METHOD: GET

Request Parameters

Parameter Type Required Description
apiKey string yes The publisher’s API key for authentication
publisherId integer yes The publisher’s unique Connexity identifier
startDate string yes The start date for the report in yyyy-mm-dd format
endDate string yes The end date for the report in yyyy-mm-dd format (inclusive)
groupBy string yes The preferred grouping of results (day; week; month)
order string no The preferred sorting order of results (ascending; descending)
firstResult integer no The index of the first result (default: 0)
maxResults integer no The maximum number of results to return (default: 100; max: 500)


Example Request

curl -X GET 
"https://publisher-api.connexity.com/api/reporting/earnings?apiKey=YOUR_API_KEY&publisherId=12345&startDate=2024-11-01&endDate=2024-11-30&groupBy=day&order=ascending"


Response Attributes

Attribute Type Description
publisherId integer The publisher’s unique Connexity identifier
entriesCount integer The number of adjustment entries returned
earnings array A nested list of earnings, including date, redirects, estimatedEarnings and cpc
date string The date of a given earnings item in yyyy-mm-dd format
redirects integer The number of redirects associated with a given earnings item
estimatedEarnings decimal The estimated earnings for a given earnings item
cpc decimal The cost per click associated with a given earnings item
totals object Aggregate totals for the request, including cpcRedirects, cpaRedirects and earnings
cpcRedirects integer The total number of cpcRedirects for the given request
cpaRedirects integer The total number of cpaRedirects for the given request
earnings decimal The total earnings for the the given request


Example Response (JSON)

{
  "publisherId": 12345,
  "entriesCount": 2,
  "earnings": [
    {
      "date": "2024-11-01",
      "redirects": 100,
      "estimatedEarnings": 150.00,
      "cpc": 0.50
    },
    {
      "date": "2024-11-02",
      "redirects": 120,
      "estimatedEarnings": 180.00,
      "cpc": 0.55
}
  ],
  "totals": {
    "cpcRedirects": 220,
    "cpaRedirects": 50,
    "earnings": 330.00
  }
}


Endpoint: Get Performance

URL: /api/reporting/getPerformanceReport

METHOD: GET

Request Parameters

Parameter Type Required Description
apiKey string yes The publisher’s API key for authentication
publisherId integer yes The publisher’s unique Connexity identifier
reportId integer yes The unique identifier of a performance report saved in the Connexity dashboard


Example Request

curl -X GET 
"https://publisher-api.connexity.com/api/reporting/getPerformanceReport?apiKey=YOUR_API_KEY&publisherId=12345&reportId=789"

*NOTE: This endpoint is asynchronous and will return a “pending” or “completed” status in the response; One or more report URLs will be returned upon a “completed” status, and these URLs can be used to retrieve the data specific to the saved, custom reporting in comma-separated format.

Response Attributes

Attribute Type Description
reportDeliveryMethod string This will be “ASYNCHRONOUS” for this type of request
reportStatus string The status of the current request (PENDING; COMPLETED)
reportUrls array A nested list of zero (0) or more reportURLs, including the URL and ttlInMin
url string A URL from which completed report data may be retrieved
ttlInMin integer The Time to Live for a given URL after which the URL will become inactive 
reportMeta object The details for the requested reportId, including publisherId, fieldList, aggregationType and timeRangeType
publisherId integer The publisher’s unique Connexity identifier
fieldList string A comma-separated list of fields associated with the requested reportId
aggregationType string The grouping associated with the requested reportId
timeRangeType string The time range type associated with the requested reportId
reportType string The report type from the Connexity dashboard associated with the requested reportId
startDate string The specific start date for the given request based on the time range associated with the requested reportId
endDate string The specific end date for the given request based on the time range associated with the requested reportId


Example Response - PENDING (JSON)*

{
  "reportDeliveryMethod": "ASYNCHRONOUS",
  "reportStatus": "PENDING",
  "reportUrls": [],
  "reports": [],
  "reportMeta": {
    "publisherId": 727808,
    "queryParams": "publisherId=727808&fieldList=DATE,CLICKS,SALES,EARNINGS,CONVERSION_RATE,CPC,AOV,MERCHANT_ID,MERCHANT_NAME,CAMPAIGN_ID,PLACEMENT_ID,RID,PAYMENT_DATE&aggregationType=DAY&timeRangeType=LAST_90_DAYS",
    "reportType": "CLICK_REPORT",
    "startDate": "2024-10-18",
    "endDate": "2025-01-15",
    "aggregationType": "DAY",
    "resultsReturned": 0
  },
  "preview": false
}


Example Response - COMPLETED (JSON)*

{
  "reportDeliveryMethod": "ASYNCHRONOUS",
  "reportStatus": "COMPLETED",
  "reportUrls": [
    {
      "url":"https://storage.googleapis.com/pubreporting-service-v2_cnnx-prod-publisher/large-reports/performance/2025-01-16/727808/D48086ECA7F424870E45F0924EEF1F9F000000000000.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=pubreporting-service-v2%40cnnx-prod-publisher.iam.gserviceaccount.com%2F20250116%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250116T152053Z&X-Goog-Expires=600&X-Goog-SignedHeaders=host&X-Goog-Signature=a4f6ad5c7bad44d46e534694e5b5ef156ab5774b5f5c937f5255abcd75e9c28c4d2aff386cd0c328300254c542798942e900f9d7f09f91dd2feca7bcc78e30014e543cba5c1f4389aa2001f6c00d095193375c8cbeb35499d4871d5efc72ffe131a8ca2c8ee0e7bd1c1386d61e4aa80d07e61e0c3f168b9291d8dfde699a75994b13ff678536c703081cac75f7a7bdd289c420ef2504972958e0cac63de366595280869e6dac450c4f9628b7faa715584e57390f0070f0a77b897bae42162a400c81912d613cde4174c09a9afcf5c5d1be51fa543db18fe697c28c847245a901982e341e7a6937337a4dd04c3467e6920ecde147a48f65852e02687eca842807",
      "expiryDate": "2025-01-16T07:30:53.297736-08:00",
      "ttlInMin": 9
    }
  ],
  "reports": [],
  "reportMeta": {
    "publisherId": 727808,
    "queryParams": "publisherId=727808&fieldList=DATE,CLICKS,SALES,EARNINGS,CONVERSION_RATE,CPC,AOV,MERCHANT_ID,MERCHANT_NAME,CAMPAIGN_ID,PLACEMENT_ID,RID,PAYMENT_DATE&aggregationType=DAY&timeRangeType=LAST_90_DAYS",
    "reportType": "CLICK_REPORT",
    "startDate": "2024-10-18",
    "endDate": "2025-01-15",
    "aggregationType": "DAY",
    "resultsReturned": 0
  },
  "preview": false
}

 

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk