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

note

/publisher/v2/reporting/by-advertiser

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-advertiser?from=2022-07-01&to=2022-07-03”

/publisher/v2/reporting/by-advertiser

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-advertiser?from=2022-07-01&to=2022-07-03”

Filters

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

When the response contains “hasMore”: true, it means that more results are available on the next page.

Status Codes

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

note

/publisher/v2/reporting/by-click

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-click?from=2023-05-30&to=2023-05-30&placement=[placementId]&page=1&finalized=0"

/publisher/v2/reporting/by-click

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-click?from=2023-05-30&to=2023-05-30&placement=[placementId]&page=1&finalized=0"

Filters

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

The flag "totalPages" indicates how many pages the requested data split into. We return 2000 records per page, when the response contains “"hasMore":true, it means that more results are available on the next page.

finalized

Optional

If you want to show only finalized results (1|0)

Example: finalized=1

Status Codes

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

note

/publisher/v2/reporting/by-subid

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-subid?from=2022-07-01&to=2022-07-03"

/publisher/v2/reporting/by-subid

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-subid?from=2022-07-01&to=2022-07-03"

Filters

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

When the response contains “hasMore”: true, it means that more results are available on the next page.

advertiserIds

Optional

Comma separated list of advertiser ids.

Example: advertiserIds=1,2,3,4,5

Status Codes

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:

{
   "itemsCount":1,
   "items":[
    {
      "advertiserId": 2222,
      "advertiserName": "Sample Advertiser 1",
      "date": "2022-07-01",
      "subId": "N/A",
      "revenue": 84.3,
      "impressions": 0,
      "clicks": 281,
      "conversions": 0
    }
   ],
   "hasMore":false,
   "page":1
}

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

Endpoint

note

/publisher/v2/reporting/by-domains

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-domains?from=2022-07-01&to=2022-07-03&placement=1111"

/publisher/v2/reporting/by-domains

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/reporting/by-domains?from=2022-07-01&to=2022-07-03&placement=1111"

Filters

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

When the response contains “hasMore”: true, it means that more results are available on the next page.

Status Codes

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:

{
   "itemsCount":1,
   "items":[
    {
      "domain": 2222,
      "clicks": "Sample Advertiser 1",
      "eCPC": 0.0,
      "revenue": 84.3,
      "conversions": 0,
      "bidFloor": 0
    }
   ],
   "hasMore":false,
   "page":1
}

Available Advertisers

Get a list of available domains with high level information

Endpoint

note

/publisher/v2/available-domains

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/available-domains?placement=1111&fallback-urls=0"

/publisher/v2/available-domains

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/available-domains?placement=1111&fallback-urls=0"

Filters

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

When the response contains “hasMore”: true, it means that more results are available on the next page.

Link builder

Name

Description

subId

Optional

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

Example: subId=examplesubId

SubID data is used to differentiate traffic sources and optimize performance. This data will directly influence our bidding strategy.

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

Not supported when url has been shortened.

Status Codes

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": [
    {
      "link": "https://lg.provenpixel.com/plp.php?zoneid=7780&oadest=sampledomain1.com",
      "businessName": "SampleBusiness",
      "logo": "https://dissets.provenpixel.com/company_logos/sampledomain1.png",
      "numberOfAds": 14,
      "subIdRestricted": 0,
      "minCpc": 0.044,
      "maxCpc": 0.244
      "geos": [
        "US",
        "CA",
        "FR"
      ],
      "deviceTypes": [
        1,
        2
      ],
      "domain": "sampledomain1.com"
    }
],
  "hasMore": false,
  "page": 1
}

Legends

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

Get merchants product feeds

Endpoint

note

/publisher/v2/product-feed

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/product-feed?placement=1111"

/publisher/v2/product-feed

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/product-feed?placement=1111"

Filters

Name

Description

placement

Required

Partner’s placement/zone ID

Example: placement=1111

Status Codes

Code	Description
200	Returned when successful
400	Returned when an invalid request or payload is sent to the server.
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

[
  {
    "merchantDomain": "sampledomain1.com",
    "cpcRate": 0.3,
    "feedLink": "example-url-to-product-feed-hosted-by-sourceknowledge.com"
  }
]

The feedLink urls expire after 60 minutes. You are expected to download the feed and not use those urls indefinitely.

Sub Ids

Get the Sub Ids allowed running given placement and domain

Endpoint

note

/publisher/v2/allowed-subids

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/allowed-subids?domain=sampledomain.com&placement=1111"

/publisher/v2/allowed-subids

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/allowed-subids?domain=sampledomain.com&placement=1111"

Filters

Name

Description

domain

Required

Domain that you want to get detailed info for

Example: domain=sampledomain.com

placement

Required

Partner’s placement/zone ID

Example: placement=1111

Status Codes

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 when those 3 subIds are blocked, others are all allowed to run traffic:

{
  "placement": 1111,
  "domain": "sampledomain.com",
  "default": "allowed",
  "except": [
  		"Sample-Sub-Id-1",
		"Sample-Sub-Id-2",
		"Sample-Sub-Id-3",
  ]
}

Response Body when only those 2 subIds are allowed/whitelisted, others are all blocked:

{
  "placement": 1111,
  "domain": "sampledomain.com",
  "default": "blocked",
  "except": [
  		"Sample-Sub-Id-1",
		"Sample-Sub-Id-2"
  ]
}

When no allow/block list restriction, open to all traffic

{
  "placement": 1111,
  "domain": "sampledomain.com",
  "default": "allowed",
  "except": []
}

When campaign(s) is running on allow list(s) but there are no subID belong to this placement in those list(s). Please don’t run traffic in this case

{
  "placement": 1111,
  "domain": "sampledomain.com",
  "default": "blocked",
  "except": []
}

Placements

Returns all placements information

Endpoint

note

/publisher/v2/placements

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/placements"

/publisher/v2/placements

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/placements"

Filters: No parameter/filter

Status Codes

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:

[
  {
    "placement": 0,
    "name": "string"
  }
]

Report Scheduler

/publisher/v2/schedule/conversions-report

e.g. /publisher/v2/schedule/conversions-report

Filters

Name

Description

body

Required

Report settings

Example:

Schedule one time report with the stats from October 1 to October 31 for zone 4444 with the finalized stats and send it to the mail

{
  "frequency": "ONE_TIME",
  "startDate": "2022-12-16",
  "expirationDate": "2022-12-17",
  "emails": [
    "user@report.com"
  ],
  "filters": [
    {
      "filterName": "placementId",
      "filterValue": "4444"
    },
    {
      "filterName": "finalized",
      "filterValue": "true"
    },
    {
      "filterName": "reportStartDate",
      "filterValue": "2022-10-01"
    },
    {
      "filterName": "reportEndDate",
      "filterValue": "2022-10-31"
    }
  ]
}

Value

Meaning

Description

frequency*

Report Frequency

(string) Options: [ONE_TIME', 'DAILY', 'WEEKLY', 'MONTHLY']

Note:

if frequency is 'ONE_TIME', reportStartDate and reportEndDate filters are mandatory.
if frequency is 'DAILY', the report contains only yesterday stats. First day sent is startDate and after that the report will be sent every day until expirationDate.
if frequency is 'WEEKLY', the report contains the last 7 days stats. First day sent is startDate and after that the report will be sent every 7 days until expirationDate.
if frequency is 'MONTHLY', the report contains the last month stats. First day sent is startDate and after that the report will be sent every 30 days until expirationDate.

startDate*

Report Start Date

(string) First day for sending the report. It's a date greater than or equal than today, format: YYY-MM-DD.

expirationDate*

Report Expiration Date

(string) Report expiration date. It's a date greater than startDate, format: YYY-MM-DD.

emails*

Emails for sending the report

(array) String array with all the emails for sending the report.

filters

Report Filters

(array) Report Filters array.

Note: The Conversions report accepts 5 filters:

placementId: Placement (Zone id) (integer)
subId: Sub ID (string)
finalized: Final Stats ('bool) [1, 0, '1', '0', 'true', 'false', 'True', 'False']
reportStartDate: Report Start Date (string), format: YYY-MM-DD.
reportEndDate: Report End Date (string), format: YYY-MM-DD.

e.g.

  "filters": [
    {
      "filterName": "placementId",
      "filterValue": "4444"
    {
      "filterName": "reportStartDate",
      "filterValue": "2022-10-01"
    },
    {
      "filterName": "reportEndDate",
      "filterValue": "2022-10-31"
    }
  ]

Status Codes

Code	Description
200	Returned when successful
400	Returned when an invalid request or payload is sent to the server
401	Returned when not authorized
403	Returned when access is forbidden

Sample response data

Response Body:

{
  "frequency": "ONE_TIME",
  "startDate": "2022-12-16",
  "expirationDate": "2022-12-17",
  "emails": [
    "user@report.com"
  ],
  "filters": [
    {
      "filterName": "placementId",
      "filterValue": "4444"
    },
    {
      "filterName": "finalized",
      "filterValue": "true"
    },
    {
      "filterName": "reportStartDate",
      "filterValue": "2022-10-01"
    },
    {
      "filterName": "reportEndDate",
      "filterValue": "2022-10-31"
    }
  ]
}

Returns all scheduled reports

Endpoint

note

/publisher/v2/get-scheduled-reports

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/get-scheduled-reports"

/publisher/v2/get-scheduled-reports

e.g. curl -X GET "https://api.sourceknowledge.com/publisher/v2/get-scheduled-reports"

Filters: No parameter/filter

Status Codes

Code	Description
200	Returned when successful
401	Returned when not authorized
403	Returned when access is forbidden
404	When no reports were found

Sample response data

Response Body:

[
  {
    "frequency": "ONE_TIME",
    "startDate": "2022-12-16",
    "expirationDate": "2022-12-17",
    "emails": [
      "user@report.com"
    ],
    "filters": [
      {
        "filterName": "placementId",
        "filterValue": "4444"
      },
      {
        "filterName": "finalized",
        "filterValue": "true"
      },
      {
        "filterName": "reportStartDate",
        "filterValue": "2022-10-01"
      },
      {
        "filterName": "reportEndDate",
        "filterValue": "2022-10-31"
      }
    ]
  }
]

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.