GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In

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.

Existing MAPI functionality will continue to exist behind the new Criteo API authentication as v2020.07. We will start to decommission Analytics and Campaigns endpoints (except /v1/campaigns/bids and /v1/campaigns/{campaignId}/categories) from July 1st on v2020.07 (Legacy). The remaining v2020.07 endpoints will be decommissioned in the second half of the year, but we will always ensure there is an equivalent in the latest versions. These updates will be communicated in the changelog.

Based on this information, if you're an existing MAPI user, the minimum requirements for migration by June 15th, 2021 are:

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.

Please note, the version v2020.07 is a special version: it mirrors MAPI functionality under Criteo API label. Consequently, if some features are not available under the Criteo API standard version (e.g v2021.01) then v2020.07 should be queried.
The v1/budgets and v1/statistics endpoints have their full equivalents in Criteo API v2021.01 and onwards. See below for more details.

TypeMAPICriteo APIDescriptionVersioning policy
POST/v1/statistics

ReportType: CampaignPerformance
/2021-01/statistics/report

This endpoint contain breaking changes.
Retrieve advertiser performances reports.
Please follow the Migration guide Statistics v1 to v2021-01
Y
POST/v1/statistics

ReportType: TransactionID
/2021-01/transaction/report

This endpoint contain breaking changes.
Retrieve advertiser performances reports.
More detailed guide is available here [TransactionIds] Transaction ID Report
Y
GET/v1/portfolio/2021-01/advertisers/meRetrieve your Advertiser(s) ID(s)Y
GET/v1/advertisers/{advertiserId}/campaigns/2021-01/marketing-solutions/ad-sets/searchRetrieve Ad Set(s) for your portfolio.
Currently, the only filter available is adSetIds, however, the response will contain an advertiserId information. More filters will become available in future versions of the API, such as filtering by partnerId, advertiserId. More details can be found here
Y
GET/v1/advertiser/{advertiserID}/categories/legacy/marketing/v1/advertiser/{advertiserID}/categories

Not available in v2021-01, please see the Legacy endpoints reference here
Retrieve your campaign(s) and categories for a specific advertiserN
GET/v1/advertiser/{advertiserID}/categories/{categoryHashCode}/legacy/marketing/v1/advertiser/{advertiserID}/categories/{categoryHashCode}

Not available in v2021-01, please see the Legacy endpoints reference here
Retrieve specific categories for a specific advertiserN
GET/v1/audiences/2021-01/audiencesGet the list of audiencesY
POST/v1/audiences/userlist//2021-01/audiencesCreate an audienceY
PUT/v1/audiences/{audienceId}PATCH /2021-01/audiences/{audience-id}Change an audience metadataY
PATCH/v1/audiences/userlist/{audienceId}/2021-01/audiences/{audience-id}/contactlistAdd/Remove users to an audienceY
DELETE/v1/audiences/userlist/{audienceId}/users/2021-01/audiences/{audience-id}/contactlistRemove all users from an audienceY
DELETE/v1/audiences/{audienceId}/2021-01/audiences/{audience-id}Delete an audienceY
GET/v1/budgets/2021-01/marketing-solutions/ad-sets/searchBudget is a property of an Ad Set now. See Ad Set Budget section of Anatomy of an Ad Set document.
GET/v1/campaigns//2021-01/marketing-solutions/ad-sets/searchRetrieve 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.
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. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Retrieve your campaign information and categories for a specific campaign.N
GET/v1/campaigns/{campaignId}*

*if category bid is not used
GET/POST /2021-01/marketing-solutions/ad-sets/searchRetrieve your Ad Set information. More details can be found here.Y
GET/v1/campaigns/{campaignId}/categories/legacy/marketing/v1/campaigns/{campaignId}/categories

Not available in v2021-01, please see the Legacy endpoints reference here. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Retrieve your campaign and categories for a specific campaignN
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. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Retrieve specific campaign categories of your portfolioN
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. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Set new bid values to your campaign or campaign categoriesN
GET/PUT/v1/campaigns/bids**






** if category bid is not used
PATCH /2021-01/marketing-solutions/ad-sets for updating the bids

GET/PATCH /2021-01/marketing-solutions/ad-sets/search for retrieving the bids
Get or set the new bid values for your Ad Set.
Refer to Search for Ad Sets and Update Ad Sets for more information.
Y
GET/v1/categories/legacy/marketing/v1/categories

Not available in v2021-01, please see the Legacy endpoints guide here. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Retrieve categories for your portfolioN
PUT/v1/categories/legacy/marketing/v1/categories

Not available in v2021-01, please see the Legacy endpoints guide here. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Enabled or disabled categoriesN
PATCH/marketing/v1/catalogs/products/legacy/marketing/v1/catalogs/products

Not available in v2021-01, please see the Legacy endpoints guide here. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Manage your product catalog, add, remove or edit your product details. Get status reports on your recent imports.Y
POST/marketing/oauth2/token/oauth2/tokenAuthentication 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.
Reference section will provide an up to date endpoints specification.
Feel free to reach out to us through your account representative or Discussion section of the portal if you have any questions.