1 Authentication
2 Endpoints
- 2.1 Reporting
- 2.2 Available Advertisers
- 2.3 Product Feeds
- 2.4 Sub Ids
- 2.5 Placements
- 2.6 Report Scheduler
3 Frequently Asked Questions

Authentication

To get started, please obtain your unique API key by logging into your account and navigating to the Account Details page > API key section. This page allows you to also refresh/revoke the generated keys to maintain the high level of security for your applications.

The provided key serves as your access token and must be included in the X-API-KEY header of each API request.

curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-advertiser" -H "accept: application/json" -H "X-API-KEY: [Your API key]"

The legacy authentication method which uses USERNAME and PASSWORD will be deprecated in the near future. Please transition to the new token-base authentication to ensure uninterrupted service

Rate Limits: API servers expect no more than 200 reqs/minute & same request retry is limited to 10 times/minute. Any call beyond these rate limits will result in “HTTP 429 error responses, i.e., Too Many Requests.”

Transport Layer Security (TLS) Protocol Required Version: 1.3

Partner's can access: https://api.sourceknowledge.com/doc/publisher to view an interactive documentation, which shows and describes all our available endpoints and parameters, and gives partners the ability to test the endpoints directly on the page.

Endpoints

Reporting

Returns advertisers stats in a given period of time.

Endpoint

Filters

Name	Description

Name

Description

from

Required

Data start date, support up to two years (Y-m-d)

Example: from=2022-07-01

to

Required

Data end date. (Y-m-d)

Example: to=2022-07-03

page

Optional

Page of results. Left blank by default will return results for the first page.

Example: If you want to go to the second page, please input page=2

Status Codes

Code	Description

Code	Description
200	Returned when successful
400	Returned when date range is not provided or the dates for the range are not in the expected format
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

{
  "itemsCount": 1,
  "items": [
    {
      "clicks": 111,
      "impressions": 1050,
      "conversions": 0,
      "ecpc": 0.17,
      "revenue": 18.87,
      "advertiserId": 111,
      "advertiserName": "Sample Advertiser 1"
    }
],
  "hasMore": false,
  "page": 0
}

Returns the click stats in a given period of time. It’s granular data, and fetching it day by day is recommended.
Stats for click log are updated once a day.

Endpoint

Filters

Name	Description

Name	Description
from	Required Data start date, can go back up to one month (Y-m-d) Example: from=2021-01-01
to	Required Data end date. (Y-m-d) Example: to=2021-01-01
placement	Required Partner’s placement/zone ID Example: placement=1111
subId	Optional Add subId if you want to filter by partner’s subId Example: subId=examplesubId
page	Optional Page of results. Left blank by default will return results for the first page. Example: If you want to go to the second page, please input page=2
finalized	Optional If you want to show only finalized results (1\|0) Example: finalized=1

Status Codes

Code	Description

Code	Description
200	Returned when successful
400	Returned when: Date range is not provided or the dates for the range are not in the expected format; or Invalid placementId for the logged partner; or `resourcesExceeded`: The data set returned for the given date range is too large; the limit is 250 pages. Please fetch the data in smaller chunks, recommended a single day at a time.
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

{
  "itemsCount": 1,
  "items": [
    {
      "clickId": "SampleClickID",
      "dateTime": "2022-07-01T00:00:12+0000",
      "domain": "sampledomain1.com",
      "advertiserId": 2222,
      "advertiserName": "Sample Advertiser 1",
      "placement": 1111,
      "subId": "",
      "cpc": 0.0154,
      "finalized": "1"
    }
],
  "hasMore": false,
  "page": 0,
  "totalPages": 1
}

Returns paginated sub-id stats in a given period of time.

Endpoint

Filters

Name	Description

Name	Description
placement	Optional Partner’s placement/zone ID Example: placement=1111
from	Required Data start date, support up to three months (Y-m-d) Example: from=2022-07-01
to	Required Data end date. (Y-m-d) Example: to=2022-07-03
page	Optional Page of results. Left blank by default will return results for the first page. Example: If you want to go to the second page, please input page=2
advertiserIds	Optional Comma separated list of advertiser ids. Example: advertiserIds=1,2,3,4,5

Status Codes

Code	Description

Code	Description
200	Returned when successful
400	Returned when the parameter values are not in the expected format
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

Returns paginated sub-id stats in a given period of time.

Endpoint

Filters

Name	Description

Name	Description
placement	Required Partner’s placement/zone ID Example: placement=1111
from	Required Data start date, support up to three months (Y-m-d) Example: from=2022-07-01
to	Required Data end date. (Y-m-d) Example: to=2022-07-03
page	Optional Page of results. Left blank by default will return results for the first page. Example: If you want to go to the second page, please input page=2

Status Codes

Code	Description

Code	Description
200	Returned when successful
400	Returned when the parameter values are not in the expected format
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

Available Advertisers

Get a list of available domains with high level information

Endpoint

Filters

Name	Description

Name

Description

placement

Required

Partner’s placement/zone ID

Example: placement=1111

page

Optional

Page of results. Left blank by default will return results for the first page.

Example: If you want to go to the second page, please input page=2

Link builder

Name	Description

Name

Description

subId

Optional

Add subId if you want to add subId to the tracking link.

Example: subId=examplesubId

fallback-urls

Optional

Adding the fallback-urls parameter to the API endpoint with the value 1 will add a REPLACE_WITH_FALLBACK_URL macro to all the click trackers. Replace this macro with your fallback url.

Example: fallback-urls=1

Status Codes

Code	Description

Code	Description
200	Returned when successful
400	Returned when date range is not provided or the dates for the range are not in the expected format
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

Legends

Value	Description

Value	Description
link	Tracking link for the offer
numberOfAds	The amount of different active campaigns with cap available for that specific domain.
subIdRestricted	This field determines the status of available campaigns based on their allow/block lists. Returns: 0: If at least one of the available campaigns is running without an allow/block list, aka allowing all traffic. 1: If all of the available campaigns are running on lists that either allow or block the sub source of traffic. Please call the "allowed-sub-ids" endpoint to gather detailed list of subID for accurate evaluation.
minCpc	Minimum observed CPC
maxCpc	Maximum observed CPC
geos	Geography targeting data by country For domains with empty geo-targeting responses, these ads are from our Marketplace Buyers and do not have specific geo targeting data available until your click goes up for auction. The majority of the ads from our Marketplace Buyers are approved for the US.
deviceTypes	Device type targeting data, with 1 for Mobile and 2 for Desktop

Product Feeds

Sub Ids

Placements

Report Scheduler

Frequently Asked Questions

What is a Fallback URL?

The SourceKnowledge Fallback URL allows partners to add a substitute URL to the click-through tracker. If for whatever reason, SourceKnowledge is not able to monetize the link (budgetary constraints / advertiser paused), we will redirect to your substitute affiliate link so you will never lose the opportunity to monetize your placement.

What is a SUB ID?

The sub-id parameter is used to track a unique id per traffic source / placement at the click-level. This can help identify which sources of traffic are performing better than others.

How often should I call the API?

It’s recommended that you call our API once an hour, to make sure you have the most up to date information. Advertisers that reach their daily budgets or that get paused will be removed from the API.

Do you offer an XML version instead of JSON?

No, unfortunately we only have a JSON version of our API.