GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

API Pattern

Suggest Edits

Base URL

https://api.criteo.com/<version>/retail-media/{endpoint}

Synchronous Endpoints

All campaign operations except for Catalogs are achieved through synchronous endpoints. Those will return a response in real-time.

OperationMethodEndpoint
Create an entityPOST/{plural-parent-entity-name}/{parentEntityId}/{plural-entity-name}
Delete from a listPOST/{plural-parent-entity-name}/{parentEntityId}/{plural-entity-name}/delete
Append to a listPOST/{plural-parent-entity-name}/{parentEntityId}/{plural-entity-name}/append
Get all entitiesGET/{plural-parent-entity-name}/{parentEntityId}/{plural-entity-name}
Get a specific entityGET/{plural-entity-name}/{entityId}
Update a specific entityPUT/{plural-entity-name}/{entityId}

📘

  • "Create" operations using the POST method expect every Required (R) field; omitting Optional (O) fields will set those fields to Default values.
  • "Update" operations using the PUT method expect every Write (W) field; omitting these fields is equivalent to setting them to null, if possible.

Asynchronous Endpoints

"Catalogs" and "Reports" are requested and retrieved through asynchronous endpoints. Those will send a response once the request is done processing (not in real-time).

OperationMethodEndpoint
Create a resource requestPOST/{plural-parent-entity-name}/{parentEntityId}/{plural-entity-name}
or
/{plural-parent-entity-name}/{plural-entity-name}
Retrieve the status of the requested resourceGET/{plural-entity-name}/{entityId}/status
Retrieve the output of the requested resourceGET/{plural-entity-name}/{entityId}/output

Bulk Calls

Our "Reporting" endpoints allow for bulk operations. Specifically, through the two following endpoints:

POST/reports/campaigns
POST/reports/line-items

You will be able to send us several CampaignIds or LineItemIds, with a maximum of 50 IDs per call.

To do so, please use the following attributes and terminology in one or the other endpoint (example below for the POST /report/campaigns endpoint, the same applies to the line-item endpoint):

📘

When requesting a single ID then use: "id": "CampaignId1"

OR

When requesting several IDs then use "ids": ["CampaignId1", "CampaignId2", ..., "CampaignIdn"]

⚠️

Do not mix ID with IDs

Please make sure to not use id and ids in the same call, as this will lead to an invalid request response.

Error Codes

When sending more than 50 IDs, you will get the following 400 Bad request HTTP Response:

{
    "errors": [
        {
            "code": "exceeded-ids-cap",
            "title": "Requests are capped for 50 unique ids, 51 were provided",
            "type": "validation",
            "traceId": "aa47dd83-8ca9-4a79-a179-ad5be6932ff1",
            "instance": "/api/v1/reports/line-item",
            "detail": "ids Requests are capped for 50 unique ids, 51 were provided (Value: \"1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51\")",
            "source": {
                "ids": "data/attributes/ids"
            }
        }
    ]
}

This Contains:

  • Error code: exceeded-ids-cap

  • Error title: Requests are capped for 50 unique ids, {count of ids requested} were provided

  • Error Type: validation

  • A traceId: aa47dd83-8ca9-4a79-a179-ad5be6932ff1

  • Instance: the report requested (here /api/v1/reports/line-item)

  • Detail: Title with a list of requested IDs

  • Source: The parameter that caused the error (IDs in this case)

Updated 3 days ago

What’s Next