You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 47
Next »
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]"
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
By Advertisers
Returns advertisers stats in a given period of time.
Endpoint
/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 | | |
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
}
By Click
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 |
---|
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 |
---|
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
}
By Sub-Id
Returns paginated sub-id stats in a given period of time.
Endpoint
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 |
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
}
By Domains
Returns paginated sub-id stats in a given period of time.
Endpoint
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 |
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
Available Domains
Get a list of available domains with high level information
Endpoint
/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 |
Link builder
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 |
---|
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 |
Sub Ids
Allowed Sub Ids
Get the Sub Ids allowed running given placement and domain
Endpoint
/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
Placements
Returns all placements information
Endpoint
/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
Conversions Report [POST Scheduled 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"
}
]
}
Get Scheduled Reports
Returns all scheduled reports
Endpoint
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.