Under the hood
- You'll need to request your specific access token from the CreativeX team. This is your unique token which will allow you to access your data in the CreativeX dashboard. This is required to be able to make any calls to any of our endpoints.
- Using your access token and other query parameters, you'll need to make a POST request to https://api.creativex.com/api/v3/reports. You'll receive a response with a Report ID and a Status. If you repeat a call with the same query parameters within 3 hours of the initial call, then you’ll receive back the same report id.
- As soon as you get the Report ID from the previous call, you’ll need to directly use that to make a GET request call to https://api.creativex.com/api/v3/reports/{id}/posts for all creative data available (including brands, markets and channels) for a given time period.
- The id in the path would need to be replaced by the Report ID.
- You’ll need to make sure that the status provided is “DONE” in order to have all the data available (keep in mind that if the status is “IN_PROGRESS” then you have to make a GET request call again until the status is “DONE”).
- Because the response will be paginated with 1,000 posts per page, you'll need to keep making GET requests for every page until there are no more pages available which means you've retrieved all the available data (when the "next_page" field is NULL). The next page can be retrieved with https://api.creativex.com/api/v3/reports/{id}/posts?page=page.
- Separately, if you're looking for a list of all the brands, markets and channels available for a given time period, then you'll need to make a GET request on the https://api.creativex.com/api/v3/reports/dimensions.
Version Updates
We'll keep the technical teams up to date with any version updates to our Reporting API.
Version 3
Released December 1st, 2022
We introduced asynchronous pagination for our Reporting API data with a limit of 1,000 posts per page. This will provide a smoother experience for our clients, and reduce any potential timeout errors.
You'll need to make several calls in order to get CreativeX data:
- Generate a report with the same filter criteria you specify today.
- Fetch associated CreativeX data for the report once ready.
- We'll return the first page of data (which would include at most 1,000 posts) and details on how to request the next page (if there are more pages to call on).
- Continue requesting page by page until all pages have been read.
We have not made any changes to the dimensions endpoint except renaming it.
Version 2
Released October 13, 2021
Certain field names and data types have been updated for clarity and better data handling. We've also added a new field for currency (ex: USD) if there's spend present. Lastly, we've started using NULL for irrelevant/empty values.
| Previous Version | New Version |
|---|---|
ctr : string | ctr : float |
cpc : string | cpc : float |
cpm : string | cpm : float |
creative_quality_score : string | creative_quality_score : float |
total_spend_usd | spendcurrency if spend is present |
N/A for irrelevant/empty values | null for irrelevant/empty values |
rule_id | guideline_id, brand_cue_id, regulation_id |
rule_name | guideline_name, brand_cue_name, regulation_name |
Version 1
Released in 2021
CreativeX launched our first Reporting API integration to allow clients to programmatically connect CreativeX data to their internal data lake. This included Creative Quality scores, media post data as well as platform performance metrics.