🚧

Authorization

In order to query this API you will need to use a Secret Key in the Authorization header of the request. To learn more about generating a Secret Key for your site, visit our Authorization guide.

🚧

Required Field

Both clickDateStart and clickDateEnd are required for each API call.

Date Range

📘

Date Range Limit

1 month (31 days)

You will need to submit both clickDateStart and clickDateEnd with each call to the API in the format "yyyy-mm-dd" where yyyy is the four digit year, mm is the two digit month and dd is the two digit day.

The supplied clickDateEnd is excluded from the range and functions similarly to a less-than operator. For example, if you would like to select the complete month of March, set clickDateStart to '2023-03-01' and clickDateEnd to '2023-04-01'. Additionally, if you would like to select a single day like March 1, 2023, set clickDateStart to '2023-03-01' and clickDateEnd to '2023-03-02'.

This API is currently limited to return 1 month (31 days) of data per request. However, this limit will be increased in future updates.

Rate Limiting

📘

API Rate Limit

1 request every 60 seconds

You can make API requests at a rate of up to 1 request every 60 seconds. To adhere to this rate limit, include a delay of at least 60 seconds between consecutive calls. For example, if you need to make multiple requests for data across multiple months, ensure there is a minimum gap of 60 seconds between each request.

Filters

You can filter the response by including one or more of the query parameters at the bottom of the page (with their respective data types). For an example of specifying multiple filters, see Example of multiple filters below. Note that some filters like campaignIds and merchantGroupIds can also take a comma separated list of numeric ID values.

Campaigns

You can filter the response by campaignIds, or by using multiple campaignIds. To filter by campaignIds, include the campaignIds parameter in the request, followed by the equal sign, followed by one or more campaignIds, separated by commas. For example: campaignIds=1,2,3. The campaignIds must only contain numeric values, greater than 0. See Example of filtering by multiple campaignIds below.

To get a list of campaigns, or search for a specific campaign by name, visit our Campaigns reference guide.

Merchants

You can filter the response by merchantGroupIds, or by using multiple merchantGroupIds. To filter by merchantGroupIds, include the merchantGroupIds parameter in the request, followed by the equal sign, followed by one or more merchantGroupIds, separated by commas. For example: merchantGroupIds=1,2,3. The merchantGroupIds must only contain numeric values, greater than 0.

To get a list of Merchant Group IDs, or search for a specific merchant by name, visit our Merchant Status reference guide. Ensure that you utilize the groupId acquired through this API when making requests.

Other Arguments

programType

sovrnProduct

deviceType

country

To filter by country, please use two-letter ISO Country Codes.

Examples

You can use CURL, Postman, Insomnia, Talend, or your favorite REST API tool of choice, in order to make the v1/reports/cuids request. Using gzip compression will compress the response, therefore making the response time quicker. Note that the response will always be in JSON format.

A CURL example executed from the command line, using gzip compression and writing the response to a file named commerce-cuid-reporting.json would be:

curl --request GET --location 'https://viglink.io/v1/reports/cuids?clickDateStart=2023-01-01&clickDateEnd=2023-01-02' \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-cuid-reporting.json

Example without gzip compression:

curl --request GET --location 'https://viglink.io/v1/reports/cuids?clickDateStart=2023-01-01&clickDateEnd=2023-01-02' \
--header 'Authorization: secret <your_secret_key_here>' > commerce-cuid-reporting.json

Example of multiple filters:

curl --request GET --location 'https://viglink.io/v1/reports/cuids?clickDateStart=2023-01-01&clickDateEnd=2023-01-02&campaignIds=100&merchantGroupIds=78910&programType=CPC'  \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-cuid-reporting.json

Example of filtering by multiple campaignIds:

curl --request GET --location 'https://viglink.io/v1/reports/cuids?clickDateStart=2023-01-01&clickDateEnd=2023-01-02&campaignIds=100,200,300&merchantGroupIds=78910&programType=CPC'  \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-cuid-reporting.json

Example of filtering by multiple merchantGroupIds:

curl --request GET --location 'https://viglink.io/v1/reports/cuids?clickDateStart=2023-01-01&clickDateEnd=2023-01-02&campaignIds=100&merchantGroupIds=70,80,90,100&programType=CPA'  \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-cuid-reporting.json

FAQ

Q: deviceType is sometimes unknown, why?
A: We don't always have access to detailed information about the click, or there may be instances where we are unable to accurately determine the device type.