Sign in

Welcome to our Support Center

Get help with integration and live campaigns

Welcome to our Support Center. Get help with integration and live campaigns

Marketing API details

The Criteo API can be accessed using this url: https://api.criteo.com/marketing

Endpoints

Authentication

Type

Endpoint

Objective

Parameters

Remarks

POST

/oauth2/token

Retrieve token that will allow you to post request to the API

  • client_id (mandatory)
  • client_secret (mandatory)
  • grant_type (mandatory)

The token will be valid for 300s

 

Advertiser management

Type

Endpoint

Objective

Parameters

GET

/portfolio

Retrieve your advertiser_Id(s)

none

GET

/advertiser/{advertiser_Id}/campaigns

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

advertiser_Id (mandatory): string

GET

/advertiser/{advertiser_Id}/categories

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

Filter per category status

advertiser_Id (mandatory): int

enabledOnly: bool

GET

/advertiser/{advertiser_Id}/categories/{categoryHashCode}

Retrieve specific categories for a specific advertiser

advertiser_Id (mandatory)

categoryHashCode (mandatory)

 


Campaign management

Type

Endpoint

Objective

Parameters

GET

/campaigns/

Retrieve campaign(s) for your portfolio

advertiser_Ids: string

campaignIds: string

campaignstatus: string

bidtype: string

GET

/campaigns/{campaignId}

Retrieve your campaign and categories for a specific campaign

campaignId (mandatory): int

GET

/campaigns/{campaignId}/categories

Retrieve your campaign and categories for a specific campaign

Filter per category status

campaignId (mandatory): int

enabledOnly: string

GET

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

Retrieve specific campaign categories of your portfolio

campaignId (mandatory): int

categoryHashCodes (mandatory): int

GET

/campaigns/bids

Retrieve your bid(s) for your portfolio

advertiser_Ids: string

campaignIds: string

categoryHashCodes:string

bidType: string

campaignStatus: string

pendingChanges: bool

PUT

/campaigns/bids

Set new bid values to your campaign or campaign categories

bidChanges (mandatoy): string

 

Campaign reporting

Type

Endpoint

Objective

Parameters

Remarks

POST

/statistics

Retrieve advertising performances reports

statsQuery (mandatoy)

Details about this endpoint are in the dedicated documentation section

 

Budget management

Type

Endpoint

Objective

Parameters

GET

/budgets

Retrieve budget(s) for your portfolio

advertiser_Ids: string

budgetIds: string

onlyActiveCampaigns:bool

 

Categories management

Type

Endpoint

Objective

Parameters

GET

/categories

Retrieve categories for your portfolio

campaign_Ids: : string

advertiser_Ids: string

categoryHashCodes: string

enabledOnly: bool

PUT

/categories

Enabled or disabled categories

categoriesPerCatalog (mandatoy)

 

Audience management

Type

Endpoint

Objective

Parameters

Remarks

GET

/audiences

Fetch the list of audiences

advertiser_Id : int

Without advertiser ID specified, the user's portfolio will be returned

POST

 /audiences/userlist/ 

Create an audience

advertiser_Id : int

name: string

description:string

The audience ID is the next ID (incremented each time an audience is created)

PUT

/audiences/{audienceId} 

Change an audience metadata

name: string

description: string

 

PATCH

/audiences/userlist/{audienceId}

Add/Remove users to an audience

operation: string (ADD  or REMOVE) 

schema: string (email or madid)

identifiers: list of string

Limited to 50,000 identifiers per request.

identifiers can be

emails: Plain text, MD5 or SHA256 of MD5

MADID: IDFA or AAID

Note: the API doesn't accept cookies IDs from DMPs

DELETE 

/audiences/userlist/{audienceId}/users

Remove all users from an audience

   

DELETE 

/audiences/{audienceId}

Delete an audience

   

 

Parameters

Parameter

Used for...

Details

client_id

Token retrieval

Your e-mail (same login as for Criteo Management Center)

client_secret

Token retrieval

Your password (same login as for Criteo Management Center)

grant_type

Token retrieval

Always equals "client_credentials"

advertiser_Id

Specific advertiser data retrieval

Retrieved from /portfolio endpoint

Retrieved from /advertisers endpoint

Retrieved from /audience endpoint

Retrieved from /audiences/userlist/ 

advertiser_Ids

Specifics advertisers data retrieval

Retrieved from /budget endpoint

Retrieved from /campaigns endpoint

Retrieved from /campaigns/bids endpoint

Retrieved from /categories endpoint

Retrieved from /statistics endpoint

You can request multiple advertiser_Ids by separating them with commas e.g. 1,2,3

enabledOnly

Filter list of categories

Retrieved from /categories endpoints

Retrieved from /advertiser/{advertiser_id}/categories endpoint

Retrieved from /campaigns/{campaignid}/categories endpoint

enabled

update category status

Retrieved from /categories endpoints

categoryHashCode

Specific category data retrieval

Specific category status update

Retrieved from /advertiser/{advertiser_id}/categories/{categoriesHashCode} endpoint

categoryHashCodes

Specific categories data retrieval

Specific campaign categories bid value update

Retrieved from /categories endpoint

Retrieved from /campaigns/bids endpoint

Retrieved from /campaigns/{campaignid}//categories/{categoriesHashCode} endpoint

You can request multiple categoryhashcodes by separating them with commas e.g. 1,2,3

budgetIds

Specific budget data retrieval

Retrieved from /budgets endpoint

onlyactiveCampaigns

Filter campaigns per status

Retrieved from /budgets endpoint

campaignId

Specific campaign data retrieval

Specific campaign bid value update

Retrieved from /campaigns/{campaignid} endpoint

Retrieved from /campaigns/{campaignid}/categories endpoint

Retrieved from /campaigns/{campaignid}/categories/{categoriesHashCode} endpoint

Retrieved from /campaigns/bids endpoint

campaignIds

Specific campaigns data retrieval

Retrieved from /campaigns endpoint

Retrieved from /campaigns/bids endpoint

Retrieved from /categories endpoint

You can request multiple campaignids by separating them with commas e.g. 1,2,3

bidType

Filter per bid types

Retrieved from /campaigns endpoint

Retrieved from/campaigns/bids endpoint

bidValue

Specific campaign categories bid value update

Retrieved from/campaigns/bids endpoint

campaignStatus

Filter per campaign status

Retrieved from /campaigns endpoint

Retrieved from /campaigns/bids endpoint

pendingChanges

Filter campaign with pending changes or settled ones

Retrieved from /campaigns/bids endpoint

catalogId

Update category status

Retrieved from /categories endpoints

audienceId

Update a specific audience

Retrieved from /audiences/ 

name

Update audience name

Retrieved from /audiences/userlist/ endpoint

Retrieved from /audiences/{audience_id} endpoint

description

Update audience description

Retrieved from /audiences/userlist/ endpoint

Retrieved from /audiences/{audience_id} endpoint

operation

Action on an audience

Retrieved from /audiences/userlist/{audience_id} endpoint

Value must be from the following: ADD / REMOVE

schema

Type of audience data

Retrieved from /audiences/userlist/{audience_id} endpoint

identifiers

List of users identifier

Retrieved from /audiences/{audience_id} endpoint

reportType

Statistics report export

Retrieved from /statistics

Value must be from the following : Campaign performance / Facebook DPA Report / Transaction ID Report

ignoreXDevice

Statistics report export

Retrieved from /statistics

startDate

Statistics report export

Retrieved from /statistics

endDate

Statistics report export

Retrieved from /statistics

dimensions

Statistics report export

Retrieved from /statistics

Max 3 dimensions

metrics

Statistics report export

Retrieved from /statistics

Metrics should be picked from MC UI

format

Statistics report export

Retrieved from /statistics

Value must be from the following : XML, JSON, CSV, EXCEL, HTML

currency

Statistics report export

Retrieved from /statistics

Value must be ISO currency code

timezone

Statistics report export

Retrieved from /statistics

Value must be from the following: GMT / PST / JST 


Response codes

Response code

Reason

200

Success

400

Bad request, invalid syntax

401

Authentication failed

403

Access forbidden

429

Rate limit reached, no more than 200 requests per minute, per client

500

Unknown error

Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk