Discard

Criteo Marketing Solutions API

Migration guide for MAPI users

🚧

New authentication required

Criteo API requires to use credentials issued through Developer Dashboard. Please see this Authentication guide for more information.

Introduction

This article is intended for account owners and application owners to serve as a guide for migrating from MAPI connectors to Criteo API connectors. This article lists actions required to perform successful migration and has an overview of the equivalent Criteo API endpoints. This will help you migrate before the MAPI deprecation by June 2021.

Audience

  • Account owners: Anyone with administrative ownership rights over a Criteo account.

  • Application owners: The team or organization who owns and maintains the code.

If the account owner and application owner are the same entity, then the organization name in the developer portal should be set the same as the advertiser name.

Pre-requisites

  • Application owners should complete the onboarding in our new Developer Portal as indicated in the onboarding checklist.

  • Application owner should generate the consent URL (as noted in the checklist) and share the URL by email, Slack, or any other means with the account owner.

  • Application owners and account owners should get familiar with the versioning policy document. API versioning provides predictability and insight into scheduled changes. This helps you control how you choose to handle feature upgrades and deprecations.

  • Basic understanding of the new Criteo campaigns structure: Campaigns, Ad Sets, and Ads. Bid Strategy and budget became a property of an Ad Set. Targeting controls and bid targets are set at the Ad Set level. Several Ad Sets can be linked to the same Campaign. Ads are the actual media that is used to address the audience of a given Ad Set. There can be many Ads associated with a given Ad Set.

Authorization

Once the account owner (e.g Account Administrator) receives and clicks on the consent link, they will be redirected to the Criteo Consent Portal where they can grant you the requested authorization levels for the accounts in their portfolio.

Endpoints parity

Below, you can see the Criteo API's equivalent for your MAPI endpoints. The column "Versioning" indicates whether the endpoint complies to versioning policy or not. In other words, this indicates whether the endpoint will evolve with new features (marked as "Y") or stay the same (marked as "N").
It is recommended to use versioned endpoints instead of legacy wherever possible. Terminology may differ depending on the legacy status. For example, legacy /v1/campaign endpoints refer the old campaign definition, while versioned endpoints will refer to the same entity as to an Ad Set.
This document will be kept up-to-date and serve as a quick reference during the migration.

Type

MAPI

Criteo API

Description

Versioning policy

POST

/v1/statistics

ReportType: CampaignPerformance

/2021-01/statistics/report

This endpoint contain breaking changes. Please follow the migration instructions here.

Retrieve advertiser performances reports.

Y

POST

/v1/statistics

ReportType: TransactionID

/2021-01/transaction/report

This endpoint contain breaking changes. Please follow the migration instructions here.

Retrieve advertiser performances reports.

Y

GET

/v1/portfolio

/2021-01/advertisers/me

Retrieve your Advertiser(s) ID(s)

Y

GET

/v1/advertisers/{advertiserId}/campaigns

/2021-01/marketing-solutions/ad-sets/search

Retrieve Ad Set(s) for your portfolio.
Currently, the only filter available is adSetIds. The response will contain an advertiserId, which you can use for grouping. More filters will become available in future versions of the API, such as filtering by partnerId, advertiserId. More details can be found here. See Campaigns entry under the Guides section.

Y

GET

/v1/advertiser/{advertiserID}/categories

/legacy/marketing/v1/advertiser/{advertiserID}/categories

Not available in v2020-10, please see the Legacy endpoints reference here

Retrieve your campaign(s) and categories for a specific advertiser

N

GET

/v1/advertiser/{advertiserID}/categories/{categoryHashCode}

/legacy/marketing/v1/advertiser/{advertiserID}/categories/{categoryHashCode}

Not available in v2020-10, please see the Legacy endpoints reference here

Retrieve specific categories for a specific advertiser

N

GET

/v1/audiences

/2021-01/audiences

Get the list of audiences

Y

POST

/v1/audiences/userlist/

/2021-01/audiences

Create an audience

Y

PUT

/v1/audiences/{audienceId}

PATCH /2021-01/audiences/{audience-id}

Change an audience metadata

Y

PATCH

/v1/audiences/userlist/{audienceId}

/2021-01/audiences/{audience-id}/contactlist

Add/Remove users to an audience

Y

DELETE

/v1/audiences/userlist/{audienceId}/users

/2021-01/audiences/{audience-id}/contactlist

Remove all users from an audience

Y

DELETE

/v1/audiences/{audienceId}

/2021-01/audiences/{audience-id}

Delete an audience

Y

GET

/v1/budgets

/2021-01/marketing-solutions/ad-sets/search

Budget is a property of an Ad Set now. More details can be found here. See Campaigns (Poseidon) section under the Guides section.

N

GET

/v1/campaigns/

/2021-01/marketing-solutions/ad-sets/search

Retrieve Ad Set(s) for your portfolio.
Currently, the only filter available is adSetIds. The response will contain an advertiserId, which you can use for grouping. More filters will become available in future versions of the API, such as filtering by partnerId, advertiserId. More details can be found here. See Campaigns entry under the Guides section.

Y

GET

/v1/campaigns/{campaignId}*

*if category bid is used

/legacy/marketing/v1/campaigns/{campaignId}

Not available in v2021-01, please see the Legacy endpoints reference here.

Retrieve your campaign information and categories for a specific campaign.

N

GET

/v1/campaigns/{campaignId}*

*if category bid is not used

GET/PATCH /2021-01/marketing-solutions/ad-sets

Retrieve your campaign information.

Y

GET

/v1/campaigns/{campaignId}/categories

/legacy/marketing/v1/campaigns/{campaignId}/categories

Not available in v2021-01, please see the Legacy endpoints reference here

Retrieve your campaign and categories for a specific campaign

N

GET

/v1/campaigns/{campaignId}/categories/{categoryHashCode}

/legacy/marketing/v1/campaigns/{campaignId}/categories/{categoryHashCode}

Not available in v2021-01, please see the Legacy endpoints guide here

Retrieve specific campaign categories of your portfolio

N

GET/PUT

/v1/campaigns/bids*

*if category bid is used

/legacy/marketing/v1/campaigns/bids

Not available in v2021-01, please see the Legacy endpoints guide here

Set new bid values to your campaign or campaign categories

N

GET/PUT

/v1/campaigns/bids**

** if category bid is not used

GET/PATCH /2021-01/marketing-solutions/ad-sets

Get or set the new bid values for your Ad Set (campaign).

Y

GET

/v1/categories

/legacy/marketing/v1/categories

Not available in v2021-01, please see the Legacy endpoints guide here

Retrieve categories for your portfolio

N

PUT

/v1/categories

/legacy/marketing/v1/categories

Not available in v2021-01, please see the Legacy endpoints guide here

Enabled or disabled categories

N

POST

/marketing/oauth2/token

/oauth2/token

Authentication endpoint. Note, expire_in parameter has been increased from 300 to 900 thus allowing bearer token to live longer than previously. In addition, Criteo API authentication endpoint strictly adheres to OAuth standard. This means that invalid headers, json header with form body will be rejected.

Not applicable

Conclusion

Guides section will help to navigate through various usage scenarios of the endpoints.
Feel free to reach out to us through your account representative or Discussion section of the portal if you have any questions.

Updated about a month ago


Migration guide for MAPI users


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.