Partner migration guide from MAPI to Criteo API

Overview

On April 1, 2021 our Marketing API (MAPI) will be deprecated. All MAPI users should finalize migration prior to this date. On December 9th, Criteo launched a new API for sending audiences and retrieving campaign statistics, the Criteo API. Criteo API is currently in beta and will be released into GA in January 2021.

For partners, this migration requires several changes to how you interact with our APIs. This guide is intended to help provide clear instructions for partners about how to migrate from MAPI to the new Criteo API.

Migration Path

This guide is to provide instructions for partners who are currently using the Marketing API and who would like to migrate to the new Criteo API. If your organization is integrated using our legacy API, the Partner API (PAPI), please consult this documentation.

Key Differences

Below are the three primary differences for partners currently using MAPI to consider when adopting the Criteo API:

• App-based API credentials: MAPI requires partners to utilize client credentials for each advertiser on behalf of whom they make requests. The Criteo API allows a more partner-centric credential approach. Partners may create a single set of credentials for each App they create in the Developers Dashboard across all Criteo clients for whom they make requests. Learn more here about permissions and authorization requests

• Authentication: The Criteo API upgrades our APIs to the standardized OAuth2 authentication flow. This includes some changes to URL-form Encoded content-type that require an update to the headers used during authentication

• Endpoints: MAPI endpoints will be deprecated on April 1, 2021. Partners must migrate to the new Criteo API endpoints to send audience identifiers (see our Audiences API Guide), retrieve statistics (see our Analytics API Guide ), or perform other types of requests in order to continue interacting with Criteo’s platform on behalf of mutual clients.

• A more detailed migration guide can be found here.

Sample Migration Plan

Below is a migration plan to provide a recommended implementation approach for migrating from MAPI to the new Criteo API.

Phase 1: Set Up

Sign up on the Developers Portal. Create an app. Request client permission for access to the required advertiser identifiers and within the functional scope of your organization’s App (e.g. Analytics, Audience, etc. . . .). Please consult the Onboarding Checklist for a more detailed step-by-step and Criteo API introduction.

Phase 2: Implementation

Create a new authentication flow to conform to the Criteo API’s new OAUTH2 authentication requirements. Modify the endpoints to reflect the new Criteo API’s endpoint specification.

Phase 3: Testing

Perform internal UA testing on the new version of your Criteo connector. Send test data to Criteo’s test advertiser identifier to perform a final validation of the connector API migration.

Phase 4: Migration & Release

Disconnect your legacy partner MAPI connector and enable the new Criteo API partner connector to allow sync between your platform and the Criteo API across all live mutual clients for whom you send Criteo API requests.

🚧

Timing

Be sure to time this migration in a manner so that any existing audience syncs made on behalf of mutual clients are not interrupted (e.g. any triggers from the partner platform that are intended to update Criteo audiences should be pointed at the new connector prior to disabling the legacy MAPI connector to ensure that no updates are lost during the migration process).

The migration workflow is only a suggested approach. This code update can be managed in the way that suits the needs of your engineering team. The actual migration will take only a few hours, in total, of engineering dev resources. However, some partners may find it useful to spread this work out over the course of several days.

Additional Resources

• Test our requests on the Criteo API within an interactive UI format using our Criteo API Swagger Tool

• Keep up to date with any changes or new features by consulting the Changelog

• Connect with other to chat about questions or wins in Criteo’s Developer Community Discussion Forum

Additional Support

Please feel free to reach out to [email protected] if you have any additional issues or questions!