Upgrade Guide

Follow these steps to switch to v4 of the reporting API from v2 or v3 of the CreativeX reporting API. Steps that only apply to one starting version are called out inline.

Change the endpoints you are using

In v4, we restructured our endpoints. Steps differ depending on your starting version:

From v2:

1. /audits/dimensions becomes /reports/posts/dimensions
2. /audits/posts becomes /reports/posts (POST to create) and /reports/posts/{id} (GET to retrieve)

From v3:

1. /reports becomes /reports/posts
2. /reports/{id}/posts becomes /reports/posts/{id}
3. /reports/dimensions becomes /reports/posts/dimensions

Make sure to update any places where you access our endpoints to reflect these name changes.

Switch to header-based authorization

In v4, we moved from parameter-based authentication to header-based authentication. You will no longer be able to authenticate by passing your access token in the access_token query parameter. Instead, you will need to include it as a bearer token in the headers. Here's an example of what that might look like:

Ruby

require 'httparty'

def access_token
  'def456'
end

def base_url
  'https://api.creativex.com/v4/reports'
end

def scores
  path = '/posts'
  headers = {
    "Authorization" => "Bearer #{token}",
    "Content-Type" => "application/json"
  }

  url = "#{base_url}#{path}"
  response = HTTParty.get(url, headers: headers)
  response.body
end

Adopt the async report model

This step only applies if you are migrating from v2. v3 already uses the async model.

In v2, GET /audits/posts returned data synchronously. In v4, report generation is asynchronous:

1. POST /reports/posts with your filter parameters — returns { id, status }
2. Poll GET /reports/posts/{id} until status is DONE
3. Once done, the response includes data and response_metadata

Continue fetching pages by passing the next_page value from response_metadata as the page parameter until next_page returns null. Each page contains up to 1,000 posts.

Pluralize optional filter parameter names

Make sure to pluralize each of the following parameters:

1. brand => brands
2. market => markets
3. channel => channels
4. ad_format => ad_formats (v3 only — this parameter did not exist in v2)
5. content_type => content_types (v3 only — this parameter did not exist in v2)

If you are migrating from v2, ad_formats and content_types are new parameters you can optionally start using.

You will not need to change the values you pass in for the existing parameters, just their names.

Check for omitted fields

When processing posts in a report, make sure you check for and handle any missing fields. Fields will be missing for a post when they are not applicable to it. For example, we will not include any inflight metrics for preflights, or video metrics for images.

This means that not every post in a report will contain the same fields. If you are migrating from v2, note that missing values were previously returned as null — in v4, inapplicable fields are omitted entirely.