Worked examples

This page collects practical, ready-to-run request bodies for the most common API tasks: querying and streaming products, working with media, and managing descriptions and corrections. Each example shows the JSON request body you send to the endpoint.

All requests are POST requests and must be authenticated. See Common data formats for an explanation of the filter, hasContent, and pagination concepts used below.

Base URL, locale and example IDs

• The examples target your region's API base URL: https://api.medipim.be/v4.
• Where a filter needs a content locale, the examples use en, which is available in every region. To target a localized field in your primary content language, use nl instead.
• Product IDs (e.g. M22CFEE020), organization IDs, brand IDs, and description IDs are illustrative — replace them with real values obtained from the corresponding query endpoints.
• Timestamps (updatedSince, createdAt) are Unix timestamps in seconds.

How to send these examples

Send the JSON body to the relevant endpoint with HTTP basic authentication. For example, to run the first products query with curl:

curl --user apiKeyId:apiKeySecret \
   --header 'Content-Type: application/json' \
   --request POST https://api.medipim.be/v4/products/query \
   --data '{"filter":{"and":[{"status":"active"},{"hasContent":{"flag":"media","locale":"en"}},{"hasContent":{"flag":"descriptions","locale":"en"}}]},"sorting":{"id":"ASC"},"page":{"size":100,"no":0}}'

For the remaining examples only the request body is shown — send it to the endpoint named in each section.

Products

Query endpoint

The query-products endpoint (/products/query) returns a paginated list of products and supports up to 10,000 results. For larger result sets, use the stream endpoint.

Get all active products that have an image and a description

{
  "filter": {
    "and": [
      { "status": "active" },
      { "hasContent": { "flag": "media", "locale": "en" } },
      { "hasContent": { "flag": "descriptions", "locale": "en" } }
    ]
  },
  "sorting": { "id": "ASC" },
  "page": { "size": 100, "no": 0 }
}

Get all active products with a frontal image and a description that were updated since a specific date

{
  "filter": {
    "and": [
      { "status": "active" },
      { "updatedSince": 1735689600 },
      { "hasContent": { "flag": "media.frontals", "locale": "en" } },
      { "hasContent": { "flag": "descriptions", "locale": "en" } }
    ]
  },
  "sorting": { "id": "ASC" },
  "page": { "size": 100, "no": 0 }
}

Get all active products except prescription drugs

{
  "filter": {
    "and": [
      { "status": "active" },
      { "not": { "prescription": true } }
    ]
  },
  "sorting": { "createdAt": "ASC" },
  "page": { "no": 0, "size": 100 }
}

Get all active products distributed by a specific organization

{
  "filter": {
    "and": [
      { "status": "active" },
      { "organization": "349" }
    ]
  },
  "sorting": { "createdAt": "ASC" },
  "page": { "no": 0, "size": 100 }
}

Get all active products of a specific brand

{
  "filter": {
    "and": [
      { "status": "active" },
      { "brand": "565" }
    ]
  },
  "sorting": { "createdAt": "ASC" },
  "page": { "no": 0, "size": 100 }
}

Get all active products that have a public price

When page is omitted, the default pagination size is used.

{
  "filter": {
    "and": [
      { "status": "active" },
      { "hasContent": { "flag": "publicPrice" } }
    ]
  },
  "sorting": { "createdAt": "ASC" }
}

Get products with a frontal image (images suitable for touchscreens and marketing tools)

{
  "filter": {
    "and": [
      { "hasContent": { "flag": "name", "locale": "en" } },
      { "hasContent": { "flag": "media.frontals", "locale": "en" } }
    ]
  },
  "sorting": { "id": "ASC" },
  "page": { "size": 100, "no": 0 }
}

Stream endpoint

The stream-products endpoint (/products/stream) has no result limit and returns all matching products as newline-delimited JSON (NDJSON). Use it when a query matches more than 10,000 products (i.e. when /products/query returns totalExceedsLimit: true).

Stream all active products with the minimum required content, sorted by name

{
  "filter": {
    "and": [
      { "status": "active" },
      { "minimumContent": true }
    ]
  },
  "sorting": { "name": { "direction": "ASC", "locale": "en" } },
  "page": { "no": 0 }
}

Media

Upload a media item and link it to products (upload-media-item, /media/upload)

The content field holds the Base64-encoded file. See Uploading media for the full upload guide, including the multipart alternative and automatic product linking by file name.

{
  "file": {
    "name": "ean_5400117000014-pa-front.jpg",
    "content": "/9j/4AAQSkZJRg..."
  },
  "products": ["M22CFEE020"]
}

Get media items created on a specific date (query-media-items, /media/query)

{
  "filter": {
    "and": [
      { "published": true },
      { "createdAt": 1735689600 }
    ]
  },
  "sorting": { "id": "ASC" },
  "page": { "size": 100, "no": 0 }
}

Product descriptions

In all description requests the product field accepts either a Medipim product ID (e.g. "M22CFEE020") or a single-key product identifier object (e.g. {"cnk": "1234567"}).

Create a description (/product/descriptions/create)

{
  "product": "M22CFEE020",
  "description": {
    "targetGroups": ["public", "hospital"],
    "locales": ["en"],
    "type": "full_description",
    "content": {
      "en": "Product description"
    }
  }
}

Update a description (/product/descriptions/update)

The description is identified by its Medipim description id.

{
  "product": "M22CFEE020",
  "id": 123,
  "description": {
    "targetGroups": ["public"],
    "locales": ["en"],
    "type": "full_description",
    "content": {
      "en": "Updated product description"
    }
  }
}

Delete a description (/product/descriptions/delete)

{
  "product": "M22CFEE020",
  "id": 123
}

Corrections

Create a correction (/corrections/create)

A correction is feedback about a product's data. The type is one of the supported correction types (e.g. missing_photo, wrong_description, product_does_not_exist). As with descriptions, product accepts a Medipim product ID or an identifier object such as {"cnk": "1234567"}.

{
  "product": "M22CFEE020",
  "locale": "en",
  "type": "missing_photo",
  "text": "The front photo is missing"
}